Skip to content

Latest commit

 

History

History
131 lines (92 loc) · 6.96 KB

nf-msdrm-drmsetmetadata.md

File metadata and controls

131 lines (92 loc) · 6.96 KB
Raw
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist req.product ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NF:msdrm.DRMSetMetaData
DRMSetMetaData function (msdrm.h)
Adds application-specific metadata to an issuance license.
DRMSetMetaData
DRMSetMetaData function [Active Directory Rights Management Services SDK 1.0]
msdrm/DRMSetMetaData
rm.drmsetmetadata
rm\drmsetmetadata.htm
rm
dcf95e9e-e2de-449e-a45a-4974094ecb7e
12/05/2018
DRMSetMetaData, DRMSetMetaData function [Active Directory Rights Management Services SDK 1.0], msdrm/DRMSetMetaData, rm.drmsetmetadata
msdrm.h
Windows
Msdrm.lib
Msdrm.dll
Windows
Rights Management Services client 1.0 SP2 or later
19H1
DRMSetMetaData
msdrm/DRMSetMetaData
c++
APIRef
kbSyntax
DllExport
Msdrm.dll
DRMSetMetaData

DRMSetMetaData function

-description

[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.

-parameters

-param hIssuanceLicense [in]

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

-param wszContentId [in]

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.

-param wszContentIdType [in]

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.

-param wszSKUId [in, optional]

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.

-param wszSKUIdType [in, optional]

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.

-param wszContentType [in, optional]

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.

-param wszContentName [in, optional]

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

-returns

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.

-see-also

AD RMS Functions

DRMGetMetaData