DRMSetMetaData function (msdrm.h)

Article
10/13/2021

[The AD RMS SDK leveraging functionality exposed by

the client in Msdrm.dll is available for use in Windows Server 2008, Windows Vista, Windows Server 2008 R2, Windows 7, Windows Server 2012, and Windows 8. It may be altered or

unavailable in subsequent versions. Instead, use Active Directory Rights Management Services SDK 2.1,

which leverages functionality exposed by the client in Msipc.dll.]

The DRMSetMetaData function adds application-specific metadata to an issuance license.

Syntax

DRMEXPORT HRESULT UDAPICALL DRMSetMetaData(
  [in]           DRMPUBHANDLE hIssuanceLicense,
  [in]           PWSTR        wszContentId,
  [in]           PWSTR        wszContentIdType,
  [in, optional] PWSTR        wszSKUId,
  [in, optional] PWSTR        wszSKUIdType,
  [in, optional] PWSTR        wszContentType,
  [in, optional] PWSTR        wszContentName
);

Parameters

[in] hIssuanceLicense

The handle of the issuance license to which the metadata will be added.

[in] wszContentId

A pointer to a null-terminated Unicode string that uniquely identifies an item of content. The string can contain up to 40 characters plus a terminating null character. We recommend that you use CoCreateGUID to create a GUID. For more information about content IDs, see Remarks.

[in] wszContentIdType

A pointer to a null-terminated Unicode string that specifies the type of identifier represented by the wszContentId parameter. Possible examples include "MSGUID", "ISBN", "CatalogNumber", and any other that you consider appropriate.

[in, optional] wszSKUId

A pointer to a null-terminated Unicode string that contains an optional identifier. The string can contain up to 40 characters plus a terminating null character. The SKU ID is optional and allows for further content identification beyond that provided by the required content ID. If wszSKUIdType is specified, the wszSKUId parameter must be specified. Otherwise, it can be NULL.

[in, optional] wszSKUIdType

A pointer to a null-terminated Unicode string that contains the type of identifier represented by the wszSKUId parameter. If wszSKUId is specified, the wszSKUIdType parameter must be specified. Otherwise, it can be NULL.

[in, optional] wszContentType

A pointer to a null-terminated Unicode string that contains application-defined information about the content. Examples include "Financial Statement", "Source Code", "Office Document", and any other that you consider appropriate. This parameter is optional and can be NULL.

[in, optional] wszContentName

A pointer to a null-terminated Unicode string that contains a display name for the content. This parameter is optional and can be NULL.

Return value

If the function succeeds, the function returns S_OK.

If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following list. For a list of common error codes, see Common HRESULT Values.

Remarks

The DRMSetMetaData function is typically called after DRMCreateIssuanceLicense to set the content ID, name, and type in an issuance license for a specific item of content. The function is also called before DRMCreateBoundLicense or DRMEnumerateLicense.

Content IDs are created and set in issuance licenses by a publishing application. For example, the application can call DRMCreateIssuanceLicense to create a new issuance license. It can then call CoCreateGUID to create a unique ID and DRMSetMetaData to associate the ID with the license. The AD RMS client places the ID in the <WORK> node of the issuance license as shown by the following diagram. For more information, see Creating an Issuance License.

&lt;WORK&gt;
   &lt;OBJECT type="Microsoft Office Document"&gt;
      &lt;ID type="MSGUID"&gt;{AEADA9BD84F246BD92385A611D624A02}&lt;/ID&gt;
      &lt;NAME&gt;Microsoft Office Document&lt;/NAME&gt;
   &lt;/OBJECT&gt;
    .
    .
    .
&lt;/WORK&gt;

After an issuance license has been created, a consuming application can use it to acquire an end–user license. For more information, see DRMAcquireLicense. The appropriate <WORK> nodes and their respective content IDs are copied from the issuance license to the end–user license.

Once an end–user license has been acquired, consuming applications internally use the content ID to bind to that license. For more information, see DRMCreateBoundLicense. Binding verifies the license chain, principals, and environment, and removes all rights that do not apply to the specified user. The bound license can then be used to decrypt protected content.

Finally, the content ID can be used to enumerate end–user licenses. For more information, see DRMEnumerateLicense and DRMCreateLicenseStorageSession. The content ID is used to locate an end–user license in the license store.

Requirements

Requirement	Value
Target Platform	Windows
Header	msdrm.h
Library	Msdrm.lib
DLL	Msdrm.dll