The DRMCreateUser function creates a user that will be granted a right.

Syntax

HRESULT DRMCreateUser(
  __in   PWSTR wszUserName,
  __in   PWSTR wszUserId,
  __in   PWSTR wszUserIdType,
  __out  DRMPUBHANDLE *phUser
);

Parameters

wszUserName [in]

A null-terminated string that identifies a user or group of users (see Remarks). This parameter is often an e-mail address. When the user created is passed in as hOwner to DRMCreateIssuanceLicense, this value is attached to the Owner node in the license XrML. For more information about possible values for this parameter, see the wszUserIdType parameter.

wszUserId [in]

A null-terminated string that identifies a user that will be granted a right. This parameter can be a Passport ID (PUID), Windows ID security ID (SID), or NULL. If this parameter is NULL, wszUserIdType must contain "Unspecified". This ID is verified by the Active Directory Rights Management Services system. For more information about possible values for this parameter, see the wszUserIdType parameter.

wszUserIdType [in]

The user ID type. This parameter can be one of the following values.

Value	Meaning
"Windows"	For this value, wszUserName and wszUserId can contain the following. wszUserName Fully qualified SMTP address. Can be NULL if wszUserId contains a SID. wszUserId Optional SID (used for decorative purposes only; not verified). If not given, the license records "Unspecified".
"Passport"	For this value, wszUserName and wszUserId can contain the following. wszUserName Fully qualified SMTP address. Required in all cases. wszUserId Optional PUID (used for decorative purposes only; not verified). If not given, the license records "Unspecified".
"Unspecified"	For this value, wszUserName and wszUserId can contain the following. wszUserName Fully qualified SMTP address. Required in all cases. wszUserId NULL (see Remarks).
"Internal"	For this value, wszUserName and wszUserId can contain the following. wszUserName NULL wszUserId One of the following: "Anyone" A license will be granted to anyone who requests one, but it will be attached to the requesting user. "Owner" A license will be granted to the owner, specified in DRMCreateIssuanceLicense.
"Federation"	For this value, wszUserName and wszUserId can contain the following. wszUserName Fully qualified SMTP address. Can be NULL if wszUserId contains a SID. wszUserId Optional SID (used for decorative purposes only; not verified). If not given, the license records "Unspecified".

 

phUser [out]

A pointer to the handle of the created 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. For a list of common error codes, see Common HRESULT Values.

Remarks

At license request time, a user must present a rights account certificate identifying themselves by SID or PUID if the user ID is WINDOWS or PASSPORT. If the user ID type is UNSPECIFIED (that is, if you do not know if it will be Windows, Passport, or some other type), you can simply enter an e-mail address of a client, and the AD RMS system will use the e-mail address alone to verify identity. However, this method is much less secure.

Windows authorization is used when a client is within an enterprise with its own license server (typically this occurs over a LAN or Virtual Private Network). When a client will be requesting a use license from a server outside an enterprise (typically over the Internet), you should use Passport authorization. To use Passport authorization on your AD RMS service, go to the AD RMS Global Administration Web page, view the Trust Policies page, and then click Trust Passport RACs. You may mix Windows and Passport users in a single issuance license.

If you want to create an issuance license for a group of people under an e-mail distribution list (such as marketing@contoso.com), insert the fully-qualified distribution list name into wszUserName, and leave wszUserId empty. The server will expand the distribution list when obtaining the use license. Note that this can cause a performance lag if the distribution list contains several nested distribution lists within it.

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

Requirements

See Also

AD RMS Functions

Creating and Using Issuance Licenses

OnlineSigning_GetUnsignedIL.cpp

Send comments about this topic to Microsoft

Build date: 11/12/2009