Expand Minimize

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.0, 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.

Syntax


HRESULT DRMCreateBoundLicense(
  _In_   DRMENVHANDLE hEnv,
  _In_   DRMBOUNDLICENSEPARAMS *pParams,
  _In_   PWSTR wszLicenseChain,
  _Out_  DRMHANDLE *phBoundLicense,
  _Out_  DRMHANDLE *phErrorLog
);

Parameters

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 table. For a list of common error codes, see Common HRESULT Values.

Return codeDescription
E_DRM_BIND_ACCESS_PRINCIPAL_NOT_ENABLING

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

E_DRM_BIND_ACCESS_UNSATISFIED

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.

E_DRM_BIND_CONTENT_NOT_IN_EUL

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

E_DRM_BIND_INDICATED_PRINCIPAL_MISSING

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

E_DRM_BIND_MACHINE_NOT_FOUND_IN_GROUP_IDENTITY

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

E_DRM_BIND_NO_APPLICABLE_REVOCATION_LIST

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

E_DRM_BIND_NO_SATISFIED_RIGHTS_GROUP

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.

E_DRM_BIND_POLICY_VIOLATION

One of the policies has been violated.

E_DRM_BIND_REVOCATION_LIST_STALE

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

E_DRM_BIND_REVOKED_LICENSE E_DRM_BIND_REVOKED_ISSUER E_DRM_BIND_REVOKED_PRINCIPAL E_DRM_BIND_REVOKED_CONTENT E_DRM_BIND_REVOKED_MODULE

The indicated item in the license has been revoked.

E_DRM_BIND_REVOKED_RESOURCE

The right to view this content has been revoked.

E_DRM_BIND_VALIDITY_TIME_VIOLATED

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

E_DRM_BROKEN_CERT_CHAIN

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

E_DRM_CLOCK_ROLL_BACK_DETECTED

The system clock has been modified.

E_DRM_CRYPTO_OPERATION_UNSUPPORTED

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

E_DRM_INFO_NOT_IN_LICENSE

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

E_DRM_INFO_NOT_PRESENT

Some information is missing.

E_DRM_INVALID_HANDLE

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

E_DRM_INVALID_LICENSE

The license being passed is not valid.

E_DRM_INVALID_VERSION

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.

E_DRM_KEY_TYPE_UNSUPPORTED

The key type specified is not supported.

E_DRM_RIGHT_NOT_GRANTED

The requested right is not granted.

E_DRM_UNEXPECTED_EXCEPTION

An unspecified error occurred.

 

Remarks

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:

Requirements

Product

Rights Management Services client 1.0 SP2 or later

Header

Msdrm.h

Library

Msdrm.lib

DLL

Msdrm.dll

See also

AD RMS Functions
DRMBOUNDLICENSEPARAMS

 

 

Show:
© 2014 Microsoft