IAzApplication::InitializeClientContextFromStringSid method (azroles.h)
The InitializeClientContextFromStringSid method gets an IAzClientContext object pointer from the specified security identifier (SID) in text form.
Syntax
HRESULT InitializeClientContextFromStringSid(
[in] BSTR SidString,
[in] LONG lOptions,
[in, optional] VARIANT varReserved,
[out] IAzClientContext **ppClientContext
);
Parameters
[in] SidString
A string that contains the text form of the SID of the security principal. This must be a valid string SID that can be converted by the ConvertStringSidToSid function.
[in] lOptions
Options for the context creation.
If AZ_CLIENT_CONTEXT_SKIP_GROUP is specified, the SID specified in the SidString parameter is not necessarily a valid user account. The SID will be used to create the context without validation. The created context will be flagged as having been created from a SID, the SID string will be stored in the client name field, and the domain name field will be empty. Token groups will not be used in the client context creation. Lightweight Directory Access Protocol (LDAP) query groups are not supported when AZ_CLIENT_CONTEXT_SKIP_GROUP is specified. Because the account is not validated in Active Directory, the client context's user information properties, such as UserSamCompat, will not be valid, and when accessed, they will return ERROR_INVALID_HANDLE. The RoleForAccessCheck property and the AccessCheck method of IAzClientContext can still be used to specify a role for access checking. The GetRoles method of IAzClientContext can still be used to enumerate roles assigned to the context within a specific scope.
If AZ_CLIENT_CONTEXT_SKIP_GROUP is not specified, the SID must represent a valid user account.
[in, optional] varReserved
Reserved for future use. This parameter can be one of the following values:
- varReserved.vt == VT_ERROR and varReserved.scode == DISP_E_PARAMNOTFOUND
- varReserved.vt == VT_EMPTY
- varReserved.vt == VT_NULL
- varReserved.vt == VT_I4 and varReserved.lVal == 0
- varReserved.vt == VT_I2 and varReserved.iVal == 0
[out] ppClientContext
A pointer to a pointer to the returned IAzClientContext object.
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
If possible, call the InitializeClientContextFromToken function instead of InitializeClientContextFromStringSid. InitializeClientContextFromStringSid attempts to retrieve the information available in a logon token had the client actually logged on. An actual logon token provides more information, such as logon type and logon properties, and reflects the behavior of the authentication package used for the logon. The client context created by InitializeClientContextFromToken uses a logon token, and the resulting client context is more complete and accurate than a client context created by InitializeClientContextFromStringSid.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows Vista [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | azroles.h |
Library | Azroles.lib |
DLL | Azroles.dll |
Redistributable | Windows Server 2003 Administration Tools Pack on Windows XP |