DRMAcquireAdvisories function (msdrm.h)

Article
10/13/2021

[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 DRMAcquireAdvisories function retrieves revocation lists required by a submitted license. Retrieved revocation lists are added to the user's permanent license store. A revocation list is a signed XrML document that specifies principals that have been revoked because they are no longer considered trustworthy or valid. These principals can include rights account certificates, machine certificates, code-signing certificates, manifests, and server licensor certificates, among other things.

Syntax

DRMEXPORT HRESULT UDAPICALL DRMAcquireAdvisories(
  [in]           DRMHSESSION hLicenseStorage,
  [in]           PWSTR       wszLicense,
  [in, optional] PWSTR       wszURL,
  [in]           VOID        *pvContext
);

Parameters

[in] hLicenseStorage

A handle to a license storage session created by using the DRMCreateLicenseStorageSession function.

[in] wszLicense

A pointer to a null-terminated Unicode string that contains the license that requires a revocation list. This can be any license or certificate (or certificate chain or concatenated licenses) that supports revocation lists, including end-user licenses, rights account certificates, or client licensor certificates.

[in, optional] wszURL

A pointer to a null-terminated Unicode string that contains an additional URL to query for advisories. This will be checked in addition to any URLs mentioned in the license passed in. This parameter can be set to NULL.

[in] pvContext

A 32-bit, application-defined value that is sent 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. For a list of common error codes, see Common HRESULT Values.

Remarks

This function retrieves advisory lists asynchronously. The URL where the revocation list is posted is stored in the license that is passed in, but it can be overridden by wszURL.

After an advisory list has been obtained, it must be registered by using DRMRegisterRevocationList. It is simplest to enumerate all licenses in the license store by using DRMEnumerateLicense and then register each, rather than attempting to locate the item you just acquired.

You should periodically delete duplicate or outdated revocation lists from the license store by enumerating revocation lists. To enumerate revocation lists, call DRMEnumerateLicense with the DRM_EL_EXPIRED flag, and then call DRMDeleteLicense. Because enumerating and examining licenses can be time-consuming, an application might perform this task only periodically.

An application will be informed that a new revocation list must be acquired if the call to the DRMCreateBoundLicense function returns E_DRM_BIND_REVOCATION_LIST_STALE or E_DRM_BIND_NO_APPLICABLE_REVOCATION_LIST.

For more information about revocation lists and how to create them, see the Active Directory Rights Management Services deployment guide, which comes with Rights Management Services.

The application callback function specified in the DRMCreateClientSession function will be called with the DRM_MSG_ACQUIRE_ADVISORY message to provide status feedback.

Requirements

Requirement	Value
Target Platform	Windows
Header	msdrm.h
Library	Msdrm.lib
DLL	Msdrm.dll