DRMCreateRight function (msdrm.h)

Article
10/13/2021

[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 DRMCreateRight function creates an XrML right that will define a right granted to a user or group.

Syntax

DRMEXPORT HRESULT UDAPICALL DRMCreateRight(
  [in]  PWSTR        wszRightName,
  [in]  SYSTEMTIME   *pstFrom,
  [in]  SYSTEMTIME   *pstUntil,
  [in]  UINT         cExtendedInfo,
  [in]  PWSTR        *pwszExtendedInfoName,
  [in]  PWSTR        *pwszExtendedInfoValue,
  [out] DRMPUBHANDLE *phRight
);

Parameters

[in] wszRightName

A pointer to a null-terminated Unicode string that contains the name of a user-defined or standard XrML (version 1.2) right. For more information, see Official Template XrML.

[in] pstFrom

A pointer to a SYSTEMTIME structure that contains the time, in UTC time, when this right will become valid. For more information, see Remarks. Both pstFrom and pstUntil must be specified, or both must be NULL.

[in] pstUntil

A pointer to a SYSTEMTIME structure that contains the time, in UTC time, when this right will expire. For more information, see Remarks. Both pstFrom and pstUntil must be specified, or both must be NULL.

[in] cExtendedInfo

The number of elements in the pwszExtendedInfoName and pwszExtendedInfoValue arrays. If this parameter is zero, then both the pwszExtendedInfoName and pwszExtendedInfoValue parameters must be NULL.

[in] pwszExtendedInfoName

An array of null-terminated Unicode string pointers that contains the names of extended information data. Each name in this array must be unique. The cExtendedInfo parameter contains the number of elements in this array.

[in] pwszExtendedInfoValue

An array of null-terminated Unicode string pointers that contains the values of the extended information items. The cExtendedInfo parameter contains the number of elements in this array.

[out] phRight

A pointer to a handle that receives the handle of the created right. This handle can be used with the DRMAddRightWithUser function to bind the right to a user. Call DRMClosePubHandle to close the handle.

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

Determining which rights a user can be granted is the responsibility of the application. The only right that Active Directory Rights Management Services enforces is EDIT, which grants the user the right to modify content.

A right can have any name that can be validly expressed in XML.

The pstFrom and pstUntil parameters specify the start and end validity times of the right. These parameters must either both be specified, or both be NULL. An application cannot set only one validity time.

One problem that can arise when creating licenses with short validity times is the problem of clock skew. Clock skew is when the publishing computer's clock and the end user's computer clock are not exactly aligned. Clock skew can cause attempts to exercise rights to fail. For more information, see Clock Skew.

The pwszExtendedInfoName and pwszExtendedInfoValue parameters are pointers to two parallel arrays that associate name-value pairs that hold additional right-specific information. These name-value pairs can specify any additional information you want, and they are retrieved by index number by using DRMGetRightExtendedInfo. Extended information items are optional, but if a name or value is given, the corresponding item in the other array cannot be NULL.

Call DRMClosePubHandle to close the handle of the right created by calling this function.

Requirements

Requirement	Value
Target Platform	Windows
Header	msdrm.h
Library	Msdrm.lib
DLL	Msdrm.dll