0 out of 2 rated this helpful - Rate this topic

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

Syntax

C++


HRESULT DRMInitEnvironment(
  _In_   DRMSECURITYPROVIDERTYPE eSecurityProviderType,
  _In_   DRMSPECTYPE eSpecification,
  _In_   PWSTR wszSecurityProvider,
  _In_   PWSTR wszManifestCredentials,
  _In_   PWSTR wszMachineCredentials,
  _Out_  DRMENVHANDLE *phEnv,
  _Out_  DRMHANDLE *phDefaultLibrary
);

Parameters

eSecurityProviderType [in]: Specifies the type of security provider to use.
eSpecification [in]: Specifies which security provider to use.
wszSecurityProvider [in]: 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.
wszManifestCredentials [in]: A signed XrML structure that specifies conditions on the environment. For information about making a manifest, see Creating an Application Manifest.
wszMachineCredentials [in]: The machine certificate.
phEnv [out]: A pointer to an environment handle. Close the handle by calling DRMCloseEnvironmentHandle.
phDefaultLibrary [out]: 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 table. For a list of common error codes, see Common HRESULT Values.

Return code	Description
E_DRM_ALREADYINITIALIZED	The environment has already been initialized.
E_DRM_AUTHENTICATION_FAILED	Authentication has failed, possibly because of a manifest conflict.
E_DRM_BIND_VALIDITY_TIME_VIOLATED	The validity time on the manifest or the computer certificate is not valid, or the validity time on the manifest or computer certificate is in the future when compared to the time on the client computer.
E_DRM_BROKEN_CERT_CHAIN	One of the certificates used to create the manifest has expired.
E_DRM_DEBUGGER_DETECTED	A debugger has been detected.
E_DRM_INVALID_LICENSE	The license structure in one of the certificates passed in is not valid.
E_DRM_INVALID_LICENSE_SIGNATURE	Possibly that the machine and the manifest have different roots.
E_DRM_MANIFEST_POLICY_VIOLATION	The modules specified in the application manifest could not be authenticated. You can receive this error if you have modified the module list without recreating the manifest or the modules have been corrupted. This error only applies to modules that are not considered to be part of the platform. If the module is part of the platform (stored in %WINDIR%) and it cannot be authenticated, the E_DRM_PLATFORM_POLICY_VIOLATION error code is returned. Note If you are running RMS SP1 or earlier, the E_DRM_MANIFEST_POLICY_VIOLATION error is returned when a module cannot be authenticated, regardless of whether that module is considered part of the platform.
E_DRM_MODULE_NOT_FOUND	A required module specified in the manifest was not found.
E_DRM_NEEDS_MACHINE_ACTIVATION	This error code can mean two things: The computer has never been activated or, the lockbox is out of date. In both cases, the solution is to call DRMActivate. For an application to determine the cause (and alert the user why the computer needs to acquire a new lockbox), it should call DRMIsActivated. If TRUE, it is an upgrade; if FALSE, it has never been activated.
E_DRM_PLATFORM_POLICY_VIOLATION	The operating system or the cryptographic service provider (CSP) could not be authenticated. You can receive this error if the CSP or operating system files have not been signed or have been corrupted. Authentication of the operating system includes authentication of platform modules, that is, modules listed in the manifest and stored in the %WINDIR% folder. Note If you are running RMS SP1 or earlier, E_DRM_MANIFEST_POLICY_VIOLATION is returned when a platform module cannot be authenticated.
E_DRM_UNEXPECTED_EXCEPTION	Undefined exception. Also thrown when an application runs in debug mode.

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

Product	Rights Management Services client 1.0 SP2 or later
Header	Msdrm.h
Library	Msdrm.lib
DLL	Msdrm.dll

Community Additions

ADD