Expand Minimize

DRMAcquireIssuanceLicenseTemplate 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 DRMAcquireIssuanceLicenseTemplate function asynchronously retrieves issuance license templates from a server.

Syntax


HRESULT DRMAcquireIssuanceLicenseTemplate(
  _In_      DRMHSESSION hClient,
  _In_      UINT uFlags,
  _In_      VOID *pvReserved,
  _In_      UINT cReserved,
  _In_opt_  PWSTR *pwszReserved,
  _In_      PWSTR wszURL,
  _In_      VOID *pvContext
);

Parameters

hClient [in]

A handle to a client session. The handle is obtained by calling the DRMCreateClientSession function. When you call DRMCreateClientSession, you must specify a callback function that AD RMS can use to return the result of an operation. A string that contains the templates is sent to the callback function in a DRM_MSG_ACQUIRE_ISSUANCE_LICENSE_TEMPLATE message.

uFlags [in]

Specifies options for the function call. This parameter can be a combination of one or more of the following flags.

FlagDescription
DRM_AILT_NONSILENT

Non-silent template acquisition is supported. That is, an authentication prompt is displayed if an access control list (ACL) is applied to the template and default authentication fails.

DRM_AILT_OBTAIN_ALL

Retrieves all templates from the server and adds them to the local store:

  • Templates in the local store that are not present on the server are deleted from the local store.
  • Templates in the local store that have been updated on the server are replaced.
  • Templates that are found on the server but not in the local store are added to the local store.
DRM_AILT_CANCEL

Cancels the previous request.

 

pvReserved [in]

Reserved for future use. This parameter must be NULL.

cReserved [in]

Reserved for future use. This value must be zero.

pwszReserved [in, optional]

Reserved for future use. This parameter must be NULL.

wszURL [in]

A null-terminated Unicode string that contains the template acquisition URL. You can retrieve this value by calling DRMGetServiceLocation and setting the uServiceType parameter to DRM_SERVICE_TYPE_CLIENTLICENSOR.

pvContext [in]

A 32-bit, application-defined value that is returned in the pvContext parameter of the callback function. This value can be a pointer to data, a pointer to an event handle, or whatever else the custom callback function is designed to handle. For more information, see Callback Prototype.

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_INVALIDARG

The hClient parameter is NULL, the wszURL parameter is not valid, or you have not specified either DRM_AILT_OBTAIN_ALL or DRM_AILT_CANCEL for the uFlags parameter.

E_DRM_ALREADY_IN_PROGRESS

A previous request to retrieve templates is still operating. You can cancel that request by specifying DRM_AILT_CANCEL for the uFlags parameter, but you cannot request another template retrieval operation while a previous request is still running.

 

Remarks

The DRMAcquireIssuanceLicenseTemplate function is asynchronous. It returns immediately with a value of S_OK or an error code. To cancel a request in process, call the function with DRM_AILT_CANCEL specified for the uFlags parameter. To determine the result of the template retrieval operation, you must examine the hr parameter in the DRM_MSG_ACQUIRE_ISSUANCE_LICENSE_TEMPLATE message that AD RMS sends to your callback function.

The template collection is saved in the template store of the local AD RMS store. Each template is stored in a file with the format TMP-HashValue-TemplateGUID where the hash value is a base64-encoded SHA-1 hash of server public key. You can call the DRMEnumerateLicense function to enumerate the templates.

If properly configured, AD RMS clients can automatically obtain templates from the AD RMS server by using a WMI job in the task scheduler. Therefore, if WMI distribution is enabled, call DRMEnumerateLicense to enumerate the rights policy templates from the local template store. Applications should avoid calling DRMAcquireIssuanceLicenseTemplate because the WMI job automatically copies templates to the client computer. However, DRMAcquireIssuanceLicenseTemplate can be used to retrieve templates from multiple servers, functionality not supported by the WMI job. You can also use it to retrieve templates if your application relies on a server lockbox. The WMI job is only available to applications that use a client lockbox.

Requirements

Minimum supported client

Windows Vista with SP1

Minimum supported server

Windows Server 2008

Header

Msdrm.h

Library

Msdrm.lib

DLL

Msdrm.dll

See also

AD RMS Functions
DRMAcquireLicense

 

 

Show:
© 2014 Microsoft