Expand Minimize

DRMActivate 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 DRMActivate function obtains a lockbox and machine certificate for a machine or a rights account certificate for a user.

Syntax


HRESULT DRMActivate(
  _In_  DRMHSESSION hClient,
  _In_  UINT uFlags,
  _In_  UINT uLangID,
  _In_  DRM_ACTSERV_INFO *pActServInfo,
  _In_  VOID *pvContext,
  _In_  HWND hParentWnd
);

Parameters

hClient [in]

A handle to a client session, created by DRMCreateClientSession.

uFlags [in]

Specifies the type of activation wanted, plus additional options; for more information, see Remarks. This parameter can be a combination of one or more of the following flags.

ValueMeaning
DRM_ACTIVATE_MACHINE

Activate the computer. The DRM_ACTIVATE_SILENT flag is also required, but the DRM_ACTIVATE_GROUPIDENTITY flag must not be set. The pActServInfo parameter is ignored.

Each computer is activated on a per-user basis. That is, the machine certificate is generated and stored for the currently logged-in user.

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

DRM_ACTIVATE_GROUPIDENTITY

Activates a rights account. This flag cannot be combined with DRM_ACTIVATE_MACHINE.

The DRM_ACTIVATE_SILENT flag is required for RMS v1.0 SP2 and Windows Vista. The DRM_ACTIVATE_SILENT flag is, however, optional for Windows Vista with SP1 and Windows Server 2008.

The application callback function specified in the DRMCreateClientSession function will be called with the DRM_MSG_ACTIVATE_GROUPIDENTITY message to provide rights account activation status feedback.

DRM_ACTIVATE_TEMPORARY

Acquire a temporary rights account certificate (RAC). A temporary RAC is only good for a short period of time, but it is stored in the permanent license store. This flag is ignored in nonsilent activation; for more information, see Remarks.

DRM_ACTIVATE_CANCEL

Cancel an in-progress activation attempt.

DRM_ACTIVATE_SILENT

Activate a user without displaying a Windows password dialog box. This flag is required for DRM_ACTIVATE_MACHINE and optional for DRM_ACTIVATE_GROUPIDENTITY, depending on the operating system. For more information, see the DRM_ACTIVATE_GROUPIDENTITY parameter.

If this flag is used with DRM_ACTIVATE_GROUPIDENTITY, the pActServInfo parameter cannot be NULL. If it is used with DRM_ACTIVATE_MACHINE, pActServInfo is ignored.

DRM_ACTIVATE_SHARED_GROUPIDENTITY

This flag is not used.

DRM_ACTIVATE_DELAYED

Delayed machine activation. In normal silent activation, the client receives a CAB file that contains activation files that are expanded and run automatically. With this flag, the files are saved to a location that is passed to the pvParam parameter of the callback function, where a client can check them for viruses before expanding and running them.

 

uLangID [in]

The language ID used by the application. If this parameter is set to zero, the default language ID for the logged-on user is used.

pActServInfo [in]

Optional server information. If the client has not been configured to use Active Directory Federation Services (ADFS) with AD RMS, you can pass NULL to use the Windows Live ID service for service discovery. If the client has been configured to use ADFS, you must pass the Windows Live certification URL. Currently, the Windows Live ID certification service URL is https://certification.drm.microsoft.com/certification. For more information about service discovery, see DRMGetServiceLocation.

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.

hParentWnd [in]

Parent window handle used in nonsilent Windows Live ID activation (user activation only). In nonsilent activation, a Windows Live ID window opens to request user information. This parameter allows the application to assign an arbitrary window as the window's parent. If this parameter is NULL, the active window is used.

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_DRM_ABORTED

The activation attempt was canceled by using the DRM_ACTIVATE_CANCEL flag during machine activation.

E_DRM_ACTIVATIONFAILED

The activation failed. You can receive this error if operating system or cryptographic service provider (CSP) files have not been signed or have been corrupted.

E_DRM_ATTRIB_NOT_SET

The application attempted to activate a group identity, but no group ID was specified in the specified client session object.

E_DRM_AUTHENTICATION_FAILED

The user could not be authenticated. This error can occur for the following reasons:

  • The user does not have valid domain credentials to activate silently.
  • The certification server used for silent activation is not in the local intranet or trusted sites zone.
  • The user's certificate store does not contain a client authentication certificate, and no smart card has been supplied.
E_DRM_HID_CORRUPTED

The HID used in a machine activation attempt is incorrectly formatted.

E_DRM_NEEDS_MACHINE_ACTIVATION

This error will occur for one of the following reasons:

  • The application is attempting to activate a user and the machine is not activated.
  • The application is attempting to activate a user and the current certificate hierarchy does not match the hierarchy of the machine certificate.
E_DRM_NO_CONNECT

Unspecified connection error. Try activating again later.

E_DRM_SERVER_ERROR

This HRESULT value can be returned for any of the following reasons:

E_DRM_SERVER_NOT_FOUND

Returned when an attempt to contact a service through the Internet returns HTTP 404 (which indicates that the requested server was not found).

E_DRM_SERVICE_GONE

Returned when an attempt to contact a Windows Live ID service in a rights account certificate activation request returns HTTP 410 (which indicates that the service is gone).

E_DRM_SERVICE_MOVED

Returned when an attempt to contact a Windows Live ID service in a rights account certificate activation request returns HTTP 303 (which indicates that the service has moved).

E_DRM_SERVICE_NOT_FOUND

The default server was specified (NULL is passed to pActServInfo), and it cannot be found in the UDDI directory.

 

Remarks

If an application attempts to activate a user on a computer that has not yet been activated, the function will fail. We recommend that an application call DRMIsActivated before calling this function to determine the activation status of the computer. Activating a machine that is already activated will overwrite the existing lockbox and machine certificate. Activating a user a second time will add an additional rights account certificate to the computer. A user needs to activate a particular computer only once, although updates in the lockbox architecture may require downloading and activating a new lockbox.

There are several options in activation.

OptionDescription
Silent or nonsilentNonsilent activation is the default. Silent activation is specified by DRM_ACTIVATE_SILENT and is required for machine activation. If silent activation is specified and pActServInfo is not NULL, the function creates and sends an activation request to the URL specified in the wszURL member of pActServInfo. For more information, see DRM_ACTSERV_INFO.
Windows or Windows Live IDThis is determined by the type of client handle passed in to hClient.
Temporary or permanentThis applies only to a rights account certificate (RAC), not to a machine certificate. Permanent activation is the default. Temporary is specified by the DRM_ACTIVATE_TEMPORARY flag. When you acquire a temporary RAC by using the DRM_ACTIVATE_TEMPORARY flag, the RAC is stored in the permanent license store, though it will expire shortly. The default validity time for a temporary RAC is 15 minutes, although this can be changed by the AD RMS service's administrator. To avoid cluttering the license store with expired RACs, you should delete a temporary RAC when ending a client session.

 

The following table describes what happens with combinations of these options.

OptionTemporaryPermanent
Silent WindowsActivation occurs without a dialog box. The user currently logged in is activated.Activation occurs without a dialog box. The user currently logged in is activated.
Nonsilent WindowsA Windows password dialog box appears. The user specified is activated.A Windows password dialog box appears. The user specified is activated.
Silent Windows Live IDNot allowed.Not allowed.
Nonsilent Windows Live IDA Windows Live ID login window appears. The user specified is activated.A Windows Live ID login window appears. The user specified is activated.

 

During execution, DRMActivate calls into the user-defined callback function and sets the msg parameter to DRM_MSG_ACTIVATE_MACHINE or DRM_MSG_ACTIVATE_GROUPIDENTITY. For more information, see Creating a Callback Function.

Requirements

Product

Rights Management Services client v1.0 SP2 or later

Header

Msdrm.h

Library

Msdrm.lib

DLL

Msdrm.dll

See also

Activating a Computer
Activating a User
AD RMS Functions
Creating a Callback Function
DRMIsActivated

 

 

Show:
© 2014 Microsoft