WTSEnumerateSessionsExA function (wtsapi32.h)
Retrieves a list of sessions on a specified Remote Desktop Session Host (RD Session Host) server or Remote Desktop Virtualization Host (RD Virtualization Host) server.
Syntax
BOOL WTSEnumerateSessionsExA(
[in] HANDLE hServer,
[in, out] DWORD *pLevel,
[in] DWORD Filter,
[out] PWTS_SESSION_INFO_1A *ppSessionInfo,
[out] DWORD *pCount
);
Parameters
[in] hServer
A handle to the target server. Specify a handle returned by the WTSOpenServer or WTSOpenServerEx function. To enumerate sessions on the RD Session Host server on which the application is running, specify WTS_CURRENT_SERVER_HANDLE.
[in, out] pLevel
This parameter is reserved. Always set this parameter to one. On output, WTSEnumerateSessionsEx does not change the value of this parameter.
[in] Filter
This parameter is reserved. Always set this parameter to zero.
[out] ppSessionInfo
A pointer to a PWTS_SESSION_INFO_1 variable that receives a pointer to an array of WTS_SESSION_INFO_1 structures. Each structure in the array contains information about a session on the specified RD Session Host server. If you obtained a handle to an RD Virtualization Host server by calling the WTSOpenServerEx function, the array contains information about sessions on virtual machines on the server. When you have finished using the array, free it by calling the WTSFreeMemoryEx function. You should also set the pointer to NULL.
[out] pCount
A pointer to a DWORD variable that receives the number of WTS_SESSION_INFO_1 structures returned in the ppSessionInfo buffer.
Return value
If the function succeeds, the return value is a nonzero value.
If the function fails, the return value is zero. To get extended error information, call the GetLastError function.
Remarks
To obtain information about sessions running on virtual machines on an RD Virtualization Host server, you must obtain the handle by calling the WTSOpenServerEx function. To free the returned buffer, call the WTSFreeMemoryEx function and set the WTSClassType parameter to WTSTypeSessionInfoLevel1.
To enumerate a session, you need to have the Query Information permission for that session. For more information, see Remote Desktop Services Permissions. To modify permissions on a session, use the Remote Desktop Services Configuration administrative tool.
To enumerate sessions running on a virtual machine hosted on an RD Virtualization Host server, you must be a member of the Administrators group on the RD Virtualization Host server.
Note
The wtsapi32.h header defines WTSEnumerateSessionsEx as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 |
| Minimum supported server | Windows Server 2008 R2 |
| Target Platform | Windows |
| Header | wtsapi32.h |
| Library | Wtsapi32.lib |
| DLL | Wtsapi32.dll |
| API set | ext-ms-win-session-wtsapi32-l1-1-0 (introduced in Windows 8) |