WTSQueryUserToken function

Obtains the primary access token of the logged-on user specified by the session ID. To call this function successfully, the calling application must be running within the context of the LocalSystem account and have the SE_TCB_NAME privilege.

Syntax

BOOL WTSQueryUserToken(
  _In_  ULONG   SessionId,
  _Out_ PHANDLE phToken
);

Parameters

SessionId [in]

A Remote Desktop Services session identifier. Any program running in the context of a service will have a session identifier of zero (0). You can use the WTSEnumerateSessions function to retrieve the identifiers of all sessions on a specified RD Session Host server.

To be able to query information for another user's session, you need to have the Query Information permission. For more information, see Remote Desktop Services Permissions. To modify permissions on a session, use the Remote Desktop Services Configuration administrative tool.

phToken [out]

If the function succeeds, receives a pointer to the token handle for the logged-on user. Note that you must call the CloseHandle function to close this handle.

Return value

If the function succeeds, the return value is a nonzero value, and the phToken parameter points to the primary token of the user.

If the function fails, the return value is zero. To get extended error information, call GetLastError. Among other errors, GetLastError can return one of the following errors.

ERROR_PRIVILEGE_NOT_HELD

1314

The caller does not have the SE_TCB_NAME privilege.

ERROR_INVALID_PARAMETER

87

One of the parameters to the function was incorrect; for example, the phToken parameter was passed a NULL parameter.

ERROR_ACCESS_DENIED

5

The caller does not have the appropriate permissions to call this function. The caller must be running within the context of the LocalSystem account and have the SE_TCB_NAME privilege.

ERROR_FILE_NOT_FOUND

2

The token query is for a session that does not exist.

ERROR_NO_TOKEN

1008

The token query is for a session in which no user is logged-on. This occurs, for example, when the session is in the idle state or SessionId is zero.

Remarks

For information about primary tokens, see Access Tokens. For more information about account privileges, see Remote Desktop Services Permissions and Authorization Constants.

See LocalSystem account for information about the privileges associated with that account.

Requirements

See also

WTSEnumerateSessions

CloseHandle