DRMAcquireLicense 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 DRMAcquireLicense function attempts to acquire an end-user license or client licensor certificate asynchronously.

Syntax


HRESULT DRMAcquireLicense(
  _In_ DRMHSESSION hSession,
  _In_ UINT        uFlags,
  _In_ PWSTR       wszGroupIdentityCredential,
  _In_ PWSTR       wszRequestedRights,
  _In_ PWSTR       wszCustomData,
  _In_ PWSTR       wszURL,
  _In_ VOID        *pvContext
);

Parameters

hSession [in]

A handle to a client or license storage session.

A client session handle is obtained by using the DRMCreateClientSession function. In this case, a client licensor certificate is acquired. The application callback function specified in the DRMCreateClientSession function will be called with the DRM_MSG_ACQUIRE_CLIENTLICENSOR message to provide status feedback.

A license storage session handle is obtained by calling the DRMCreateLicenseStorageSession function. In this case, an end-user license is acquired. The application callback function specified in the client session passed in the hClient parameter of the DRMCreateLicenseStorageSession function will be called with the DRM_MSG_ACQUIRE_LICENSE message to provide status feedback.

uFlags [in]

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

DRM_AL_NONSILENT ()

Nonsilent license acquisition is not supported. DRMAcquireLicense returns E_INVALIDARG if this flag is set.

For Rights Management Services (RMS) client 1.0, acquire the license nonsilently. The default is silent license acquisition.

DRM_AL_NOPERSIST ()

Store the license only in the temporary (in-memory) license store. The default is to store the license in the permanent license store.

DRM_AL_CANCEL ()

Cancel the previous request.

DRM_AL_FETCHNOADVISORY ()

Do not acquire revocation lists required by the license. The default action is to acquire all revocation lists that a returned license requires. All revocation lists must still be registered, however, by using the DRMRegisterRevocationList function.

DRM_AL_NOUI ()

This flag suppresses the Windows network authentication dialog box. If the license request is denied because the user does not have permission, this flag will prevent the network authentication dialog box from being displayed. This is useful when attempting to handle license acquisition on a background or other non-user interface thread because you can avoid potentially confusing dialog boxes. If authentication does fail, and this flag is specified, the callback that is associated with the request will immediately receive an error of E_DRM_LICENSEACQUISITIONFAILED.

If hSession is a client session handle, this flag is ignored.

wszGroupIdentityCredential [in]

An optional rights account certificate (RAC). If this is not used, this function will check the license store for a RAC that matches the license used to create hSession. If none is found, this function will fail.

wszRequestedRights [in]

This parameter is reserved and must be NULL.

wszCustomData [in]

Optional application-specific data that might be required for a license. This must be a valid XML string. After returning control to the caller, this function creates a license request by using the application-specific data specified here.

wszURL [in]

A license acquisition URL. This parameter is required when a client licensor certificate is being acquired and optional when an end-user license is being acquired. The URL can be used for both silent and nonsilent license acquisition. When present, this URL overrides the URL specified in the license that was used to create the license storage session passed into hSession.

A license may hold multiple license acquisition URLs, but only the first is used by default. To use any of the other URLs specified, you must parse the license. For more information, see the Remarks section.

pvContext [in]

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. Possible values include, but are not limited to, those in the following list. For a list of common error codes, see Common HRESULT Values.

E_DRM_ABORTED

Returned when DRM_AL_CANCEL is used to cancel license acquisition.

E_DRM_AUTHENTICATION_FAILED

The user could not be authenticated. The certificate store of the user does not contain a client authentication certificate, and no smart card has been supplied.

E_DRM_LICENSEACQUISITIONFAILED

Possibly an HTTP 401 error (an authentication error) returned by an Internet request. If DRM_AL_NOUI was specified for uFlags, remove DRM_AL_NOUI from uFlags and call DRMAcquireLicense again to respond to any credential request user interface that may result.

E_DRM_NEEDS_GROUPIDENTITY_ACTIVATION

No RAC was submitted and none was found in the license store to match the license associated with hSession. This error can also be returned when the RAC has been excluded; in which case the user will have to recertify.

E_DRM_NEEDS_MACHINE_ACTIVATION

The computer has not been activated yet or the version of the Lockbox certificate has been excluded; in this case the computer will have to be reactivated.

E_DRM_NO_CONNECT

Unable to acquire a revocation list required by the issuance license because the server was unavailable.

E_DRM_SERVER_NOT_FOUND

Returned when an attempt to contact a service through the Internet (either to acquire an end-user license or a revocation list) returns HTTP 404, indicating that the requested server was not found, or that a revocation list was not present at the specified location.

E_DRM_SERVICE_GONE

Returned when an attempt to contact a Passport service returns HTTP 410 (indicating that the service is gone).

E_DRM_SERVICE_MOVED

Returned when an attempt to contact a Passport service returns HTTP 303 (indicating that the service has moved).

Remarks

This function is used for retrieving an end-user license or client licensor certificate asynchronously. There is no synchronous version of this function. To cancel a license request in process, call DRMAcquireLicense again with DRM_AL_CANCEL specified in uFlags. The progress of this function, and any data returned, will be returned to the callback function (see Creating a Callback Function).

If the retrieved end-user license requires any revocation lists, these are acquired at the same time, unless DRM_AL_FETCHNOADVISORY is specified in uFlags. A failure to retrieve required revocation lists will be indicated by E_DRM_NO_CONNECT. The application must register any retrieved lists by using DRMRegisterRevocationList.

This function can occur silently or nonsilently.

Note  Nonsilent license acquisition is supported only in RMS client 1.0. Effective with RMS client 1.0 SP1, nonsilent license acquisition is no longer supported, and MSDRMCtrl.dll is not shipped.
 

In nonsilent license acquisition, a license acquisition URL is returned to the callback function in a DRM_LICENSE_ACQ_DATA structure. The application then opens a web browser that is directed to a URL that specifies an HTML page that contains the ActiveX control in MSDRMCtrl.dll. The page is used to obtain additional information, such as a credit card number, and then calls the ActiveX control's AcquireLicense function, which causes license acquisition to proceed as normal. The license can only be returned to the permanent license store.

In silent license acquisition, no webpages need be opened, and license acquisition progress is noted in the application's callback function.

The retrieved license is added to the temporary or permanent license store, depending on whether DRM_AL_NOPERSIST is specified or not. In nonsilent license acquisition, the acquired license cannot be added to the temporary license store, only to the permanent license store, where it must be retrieved by using DRMEnumerateLicense. The following list describes possible combinations of license acquisition type with license store type.

License storeSilent acquisitionNonsilent acquisition
TemporaryDRM_AL_NOPERSISTNot possible
PermanentNo flagsDRM_AL_NONSILENT

 

Note  Although the issuance license is signed and protected by encryption, it would be possible for a malicious publisher to include the URL of a malicious website; there is no way to verify the nature of this URL in advance.
 

AD RMS allows an administrator to specify an extranet licensing URL in addition to an internal (intranet) URL. Each URL is copied into the license under a separate <DISTRIBUTIONPOINT> node with the internal URL appearing first. This is illustrated by the following example.



      <DISTRIBUTIONPOINT>
      - <OBJECT type="License-Acquisition-URL">
          <ID type="MS-GUID">
            {0F45FD50-383B-43EE-90A4-ED013CD0CFE5}
          </ID> 
          <NAME>DRM Server Cluster</NAME> 
          <ADDRESS type="URL">
            https://corprights/_wmcs/licensing
          </ADDRESS> 
        </OBJECT>
      </DISTRIBUTIONPOINT>
      <DISTRIBUTIONPOINT>
      - <OBJECT type="Extranet-License-Acquisition-URL">
          <ID type="MS-GUID">
            {94BF969A-CA04-44d6-AA96-51071281FAG2}
          </ID> 
          <NAME>DRM Server Cluster</NAME> 
          <ADDRESS type="URL">
            https://corprights.example.com/_wmcs/licensing
          </ADDRESS> 
        </OBJECT>
      </DISTRIBUTIONPOINT>


Multiple URLs are often specified so that users can access protected content both at work and at home. The second URL provides a license acquisition point that does not require the user working at home to log on to the corporate network. The DRMAcquireLicense function, however, uses the first URL by default. Therefore, to allow the consumer to use an alternate URL, your application must parse the license.

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

 

 

Show: