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.

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:

• DRMGetBoundLicenseAttribute
• DRMGetBoundLicenseAttributeCount
• DRMGetBoundLicenseObject
• DRMGetBoundLicenseObjectCount

Requirements

See Also

AD RMS Functions

DRMBOUNDLICENSEPARAMS

Send comments about this topic to Microsoft

Build date: 6/25/2009