Expand Minimize

DRMCreateClientSession 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 DRMCreateClientSession function creates a client session, which hosts license storage sessions and is used in activation and other function calls.

Syntax


HRESULT DRMCreateClientSession(
  _In_      DRMCALLBACK pfnCallback,
  _In_      UINT uCallbackVersion,
  _In_      PWSTR wszGroupIDProviderType,
  _In_opt_  PWSTR wszGroupID,
  _Out_     DRMHSESSION *phClient
);

Parameters

pfnCallback [in]

A pointer to an application-defined callback function that will receive asynchronous function status messages in response to other AD RMS functions, such as DRMActivate. The format of this callback function is defined in Callback Prototype. This parameter cannot be NULL.

uCallbackVersion [in]

Specifies the version of the callback function. Currently, only version zero is supported.

wszGroupIDProviderType [in]

A pointer to a null-terminated Unicode string that specifies the authentication type of the submitted rights account certificate (RAC). This can be one of the following values.

ValueMeaning
DRM_DEFAULTGROUPIDTYPE_WINDOWSAUTH

Use Windows authentication. Specify this value also for an Active Directory Federation Services (ADFS) RAC.

DRM_DEFAULTGROUPIDTYPE_PASSPORT

Use Passport authentication.

 

wszGroupID [in, optional]

A pointer to a null-terminated Unicode string that contains an email address for the user in the format someone@example.com. Typically, this value already exists in Active Directory (AD) and is the same ID as that supplied in the logon credentials. If it is not the same, later calls to DRMIsActivated and DRMEnumerateLicense will fail. For more information, see Remarks.

Set this parameter to NULL if you intend only to use the client session handle created by this function to retrieve a service location by calling DRMGetServiceLocation.

phClient [out]

A pointer to a DRMHSESSION value that receives the client session handle. When you have finished using the client session, close it by passing this handle to the DRMCloseSession function.

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 code/valueDescription
E_DRM_SAFEMODE_DETECTED

A session cannot be created because the client is running in SafeMode. There are no scenarios that require an AD RMS client to be used in SafeMode.

 

Remarks

If this function is successful, the AD RMS server returns a client session handle that is used by DRMActivate to create a rights account certificate (RAC) in the license store for the new client session. The RAC is created by using the credentials of the logged–on user. If the email address specified in the wszGroupID parameter does not match that specified in the credentials, functions such as DRMIsActivated and DRMEnumerateLicense that use information associated with the client session to search the license store for the RAC will fail.

For example, assume that the user logged on by using cat@example.com but the wszGroupID parameter is set to dog@example.com. The RAC is created for cat@example.com. The DRMEnumerateLicense function, however, searches the license store for a RAC that contains dog@example.com and fails.

All license storage sessions must be closed before closing the client session. When you have finished using the client session, close it by passing the handle provided by this function to the DRMCloseSession function.

The DRMCreateClientSession function cannot be called concurrently by different processes running as different users on the same computer if one or more of these processes is a service process. A call by a second process, for example, can succeed only after the client session handle for the first process has been closed.

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
Creating a Callback Function
DRMCloseSession

 

 

Show:
© 2014 Microsoft