The 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.
Caution WTSQueryUserToken is
intended for highly trusted services. Service providers must use caution that they do not leak user tokens when
calling this function. Service providers must close token handles after they have finished with them.
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.
| Return code/value | Description |
|---|
- 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_CTX_WINSTATION_NOT_FOUND
- 7022
| 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
| Minimum supported client | Windows XP |
|---|
| Minimum supported server | Windows Server 2003 |
|---|
| Header | Wtsapi32.h |
|---|
| Library | Wtsapi32.lib |
|---|
| DLL | Wtsapi32.dll |
|---|
See Also
- WTSEnumerateSessions
- CloseHandle
Send comments about this topic to Microsoft
Build date: 1/14/2010