WTSEnumerateSessionsExW function (wtsapi32.h)

Article
02/09/2023

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 WTSEnumerateSessionsExW(
  [in]      HANDLE               hServer,
  [in, out] DWORD                *pLevel,
  [in]      DWORD                Filter,
  [out]     PWTS_SESSION_INFO_1W *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 which 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 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)