DRMCreateBoundLicense function

[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 DRMCreateBoundLicense function allows an application to examine or exercise the rights on a locally stored license.


HRESULT DRMCreateBoundLicense(
  _In_  DRMENVHANDLE          hEnv,
  _In_  PWSTR                 wszLicenseChain,
  _Out_ DRMHANDLE             *phBoundLicense,
  _Out_ DRMHANDLE             *phErrorLog


hEnv [in]

A handle to an environment; the handle is created by using the DRMInitEnvironment function.

pParams [in]

A pointer to a DRMBOUNDLICENSEPARAMS structure that specifies additional options; for more information, see the Remarks section. The principal specified here is the one the application will try to bind to. If you pass in NULL to identify the principal or rights group, the first principal or rights group in the license will be used.

wszLicenseChain [in]

A pointer to a null-terminated Unicode string that contains the end-user license (or license chain).

phBoundLicense [out]

A pointer to a handle that receives the bound license. The DRMHANDLE passed back through phBoundLicense allows an application to navigate through all the license's objects (such as principals or rights) and attributes (such as maximum play count). A bound license consolidates duplicated rights information in the license and removes any rights information that is not available to the current user.

phErrorLog [out]

This parameter must 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.


The access condition is not matched to the enabling principal that is handed into the bind.


There are multiple access conditions and none is satisfied. If there is only one access condition, the error that caused the access condition to be unsatisfied will be returned.


The content ID you specified when calling DRMSetMetaData did not match the ID you specified in the DRMBOUNDLICENSEPARAMS structure (supplied to the DRMBOUNDLICENSEPARAMS parameter in the preceding syntax).


The enabling principal does not match the issued principal of the EUL.


The machine certificate to which the environment was initialized is not found in the machine's group ID principals.


A revocation list required by the license or one of the user's certificates has not been acquired, or it has not been registered.


There are multiple rights groups and none is satisfied. If there is only one group, the error that caused the group to be unsatisfied will be returned.


One of the policies has been violated.


Issued time of revocation list exceeds the license's allowed refresh condition interval time.


The indicated item in the license has been revoked.


The right to view this content has been revoked.


The current time is outside the validity time for the license.


The issuer key of one certificate in the chain does not match the key of the issued principal of its parent certificate.


The system clock has been modified.


A cryptographic operation that was requested is not supported. For example, passing an AD RMS encrypting object for decrypting purposes.


An issuance license, not an end-use license, was passed in.


Some information is missing.


Either the environment or the enabling principal handle is not valid.


The license being passed is not valid.


The operating system exclusion policy has been violated, or there is XrML that is not valid or a body node version that is not valid.


The key type specified is not supported.


The requested right is not granted.


An unspecified error occurred.


Calling this function binds a license to the right or rights specified in the DRMBOUNDLICENSEPARAMS structure passed to the pParams parameter. If any right requested cannot be exercised by the current user, the function will fail. Note also that you must call DRMSetMetaData and specify a value for the wszContentId parameter before calling this function and that this value must be the same as the ID set in the DRMBOUNDLICENSEPARAMS structure or the function will fail.

If the function succeeds, it returns a handle to the bound license that can be examined, and also allows an application to exercise the bound right. This function does not decrement metered rights. Decrementing metered rights upon use is the responsibility of the application.

When license binding fails because of a missing or out of date revocation list, the return value does not indicate which license or certificate is causing the error. It could be the end-user license, the user's rights account certificate, a client licensor certificate, or another license or certificate. You must call DRMAcquireAdvisories (and DRMRegisterRevocationList) for each certificate until the error does not occur.

Principal authenticators required for a license must be loaded before calling this function. However, the authenticator can continue to function after the license is created.

When you have finished using the license handle, close it by calling the DRMCloseHandle function. DRMCloseHandle closes the handle to the library and deletes the license from memory.

The handle returned by this function can be passed into one of the following functions to navigate deeper into the license hierarchy:



Rights Management Services client 1.0 SP2 or later







See also

AD RMS Functions