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.

Requirements

See also

WTSFreeMemoryEx

WTSOpenServerEx

WTS_SESSION_INFO_1