DRMInitEnvironment function (msdrm.h)

[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 DRMInitEnvironment function creates a secure environment for all rights management calls.

Syntax

DRMEXPORT HRESULT UDAPICALL DRMInitEnvironment(
  [in]  DRMSECURITYPROVIDERTYPE eSecurityProviderType,
  [in]  DRMSPECTYPE             eSpecification,
  [in]  PWSTR                   wszSecurityProvider,
  [in]  PWSTR                   wszManifestCredentials,
  [in]  PWSTR                   wszMachineCredentials,
  [out] DRMENVHANDLE            *phEnv,
  [out] DRMHANDLE               *phDefaultLibrary
);

Parameters

[in] eSecurityProviderType

Specifies the type of security provider to use.

[in] eSpecification

Specifies which security provider to use.

[in] wszSecurityProvider

The file name and ID of the security provider. A security provider can be a file on the computer (the lockbox) or a hardware device that holds the secure machine key. The path to this key is obtained by calling DRMGetSecurityProvider.

[in] wszManifestCredentials

A signed XrML structure that specifies conditions on the environment. For information about making a manifest, see Creating an Application Manifest.

[in] wszMachineCredentials

The machine certificate.

[out] phEnv

A pointer to an environment handle. Close the handle by calling DRMCloseEnvironmentHandle.

[out] phDefaultLibrary

A pointer to the handle of the library used to create the principal object. You must close this handle before closing the environment handle. For more information, see the Remarks section. Close by calling DRMCloseHandle.

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.

Remarks

This function loads the lockbox, and makes sure that only legal DLLs are loaded, according to the manifest.

The order of certificates is from least trusted first to most trusted (closest to the root) last.

When closing the handles returned by this function, close the library handle before closing the environment handle. Otherwise, you will receive an E_DRM_ENV_NOT_LOADED error. Close the library handle by calling DRMCloseHandle. Close the environment handle by calling DRMCloseEnvironmentHandle.

Requirements

See also

AD RMS Functions