Upgrade your Internet Experience
Microsoft.com
Welcome Sign in
Microsoft Developer Network
Click to Rate and Give Feedback
MSDN
MSDN Library
System Services
 WTSQuerySessionInformation Function

  Switch on low bandwidth view
WTSQuerySessionInformation Function

The WTSQuerySessionInformation function retrieves session information for the specified session on the specified Remote Desktop Session Host (RD Session Host) server. It can be used to query session information on local and remote RD Session Host servers.

Syntax

C++
BOOL WTSQuerySessionInformation(
  __in   HANDLE hServer,
  __in   DWORD SessionId,
  __in   WTS_INFO_CLASS WTSInfoClass,
  __out  LPTSTR *ppBuffer,
  __out  DWORD *pBytesReturned
);

Parameters

hServer [in]

Handle to an RD Session Host server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the RD Session Host server on which your application is running.

SessionId [in]

A Remote Desktop Services session identifier. To indicate the session in which the calling application is running (or the current session) specify WTS_CURRENT_SESSION. Only specify WTS_CURRENT_SESSION when obtaining session information on the local server. If WTS_CURRENT_SESSION is specified when querying session information on a remote server, an error will be returned.

Windows Server 2008, Windows Server 2003, Windows Vista, Windows XP, and Windows 2000:  If WTS_CURRENT_SESSION is specified when querying session information on a remote server, the returned session information will be inconsistent. Do not use the returned data in this situation.

You can use the WTSEnumerateSessions function to retrieve the identifiers of all sessions on a specified RD Session Host server.

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.

WTSInfoClass [in]

Specifies the type of information to retrieve. This parameter can be one of the values from the WTS_INFO_CLASS enumeration type. The following table shows the format of the data returned in ppBuffer for each of the information types.

WTSApplicationName (1)

Pointer to a null-terminated string containing the published name of the application the session is running. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientAddress (14)

Pointer to a WTS_CLIENT_ADDRESS structure containing the network type and network address of the client. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

Note that the first byte of the IP address returned in the ppBuffer parameter will be located at an offset of 2 bytes from the start of the Address member of the returned WTS_CLIENT_ADDRESS structure.

WTSClientBuildNumber (9)

Pointer to a ULONG variable. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientDirectory (11)

Pointer to a null-terminated string indicating the directory in which the client is installed. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientDisplay (15)

Pointer to a WTS_CLIENT_DISPLAY structure containing information about the client's display. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientHardwareId (13)

Pointer to a ULONG variable containing a client-specific hardware identifier. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientInfo (23)

Pointer to a WTSCLIENT structure containing information about a Remote Desktop Connection (RDC) client.

WTSClientName (10)

Pointer to a null-terminated string containing the name of the client. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientProductId (12)

Pointer to a USHORT variable containing a client-specific product identifier. If the session specified in the SessionId parameter is a session at the physical console, ppBuffer returns a NULL pointer.

WTSClientProtocolType (16)

Pointer to a USHORT variable containing the protocol type. This is one of the following values.

ValueMeaning

0

The console session.

1

This value is retained for legacy purposes.

2

The RDP protocol.

 

WTSConnectState (8)

Pointer to an INT variable that contains a value from the WTS_CONNECTSTATE_CLASS enumeration type to indicate the session's current connection state.

WTSDomainName (7)

Pointer to a null-terminated string that names the domain of the logged-on user.

WTSInitialProgram (0)

Pointer to a null-terminated string containing the name of the initial program that Remote Desktop Services runs when the user logs on.

WTSOEMId (3)

Pointer to a null-terminated string that contains an OEM identifier; however, this value is not currently used.

WTSSessionId (4)

Pointer to a ULONG variable containing the session identifier.

WTSSessionInfo (24)

Pointer to a WTSINFO structure containing information about a client session on an RD Session Host server.

WTSUserName (5)

Pointer to a null-terminated string containing the name of the user associated with the session.

WTSWinStationName (6)

Pointer to a null-terminated string containing the name of the specified session.

Note  Despite its name, specifying this type does not return the window station name. Rather, it returns the name of the Remote Desktop Services session. Each Remote Desktop Services session is associated with an interactive window station. Currently, since the only supported window station name for an interactive window station is "WinSta0", each session is associated with its own "WinSta0" window station. For more information, see Window Stations.

WTSWorkingDirectory (2)

Pointer to a null-terminated string containing the default directory used when launching the initial program.

ppBuffer [out]

Pointer to a variable that receives a pointer to the requested information. The format and contents of the data depend on the information class specified in the WTSInfoClass parameter. To free the returned buffer, call the WTSFreeMemory function.

pBytesReturned [out]

Pointer to a variable that receives the size, in bytes, of the data returned in ppBuffer.

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 GetLastError.

Remarks

To retrieve the session ID for the current session when Remote Desktop Services is running, call WTSQuerySessionInformation and specify WTS_CURRENT_SESSION for the SessionId parameter and WTSSessionId for the WTSInfoClass parameter. The session ID will be returned in the ppBuffer parameter. If Remote Desktop Services is not running, calls to WTSQuerySessionInformation fail. In this situation, you can retrieve the current session ID by calling the ProcessIdToSessionId function.

To determine whether your application is running on the physical console, you must specify WTS_CURRENT_SESSION for the SessionId parameter, and WTSClientProtocolType as the WTSInfoClass parameter. If ppBuffer is "0", the session is attached to the physical console.

Requirements

Minimum supported clientWindows 2000 Professional
Minimum supported serverWindows 2000 Server
HeaderWtsapi32.h
LibraryWtsapi32.lib
DLLWtsapi32.dll
Unicode and ANSI namesWTSQuerySessionInformationW (Unicode) and WTSQuerySessionInformationA (ANSI)

See Also

WTS_INFO_CLASS
WTS_CLIENT_ADDRESS
WTS_CLIENT_DISPLAY
WTS_CONNECTSTATE_CLASS

Send comments about this topic to Microsoft

Build date: 6/26/2009

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Determining Active Session versus background session and console versus remote.      William Sproule - MSFT   |   Edit   |   Show History

WTSQuerySessionInformation(WTSClientProtocolType) **ppBuffer = 2 = WTS_PROTOCOL_TYPE_RDP when the
current session is connected to via remote desktop and 0 = WTS_PROTOCOL_TYPE_CONSOLE when not.

WTSQuerySessionInformation(WTSConnectState) **ppBuffer = 0 = WTSActive when the session is active either
at the console or via remote desktop, 4 = WTSDisconnected when the session is not active.

When WTSGetActiveConsoleSessionId() == the value you get back from ProcessIdToSessionId(GetCurrentProcessId()) then the session is being used at the console (local computer) and is active.

GetSystemMetrics(SM_REMOTESESSION) == 1 indicates either the current session is connected to via a remote desktop client OR the current session is not active (a remote desktop connection may or may not be present on a FUS enabled machine). GetSystemMetrics(SM_REMOTESESSION) == 0 indicates the current session is the active console session (ie locally logged in to the machine). Bottom line, don't rely the non-zero value indicating a remote desktop connection unless you know code will only run when you are the active session (eg WM_PAINT handler, keyboard or mouse event handlers).

Note that on Vista, unlike XP, FUS (Fast User Switching) is enabled for domain joined computers and so you can have more than one user logged in at the same time just like you could in XP non-domain joined computers.

    bool fActiveSession = false;
    DWORD dwSessionID = -1; // 0 is 1st console session created on XP, 1 is 1st console session on Vista
    LPTSTR pData = NULL;
    DWORD cbReturned = 0;
 
    ProcessIdToSessionId(GetCurrentProcessId(), &dwSessionID);
 
    if( WTSQuerySessionInformation(WTS_CURRENT_SERVER_HANDLE, dwSessionID, WTSConnectState, &pData, &cbReturned)
     && (cbReturned == sizeof(INT)) )
    {
        // if we get WTSActive we're in the active session, otherwise we assume we're not in the active session (WTSDisconnected)
        fActiveSession = (*((INT *)pData) == WTSActive) ? true : false;
    }
    WTSFreeMemory(pData);
 
    // fActiveSession indicates if we are the active session (true) or not (false)
    // Note on a terminal services server, there can be more than one active session
    // on most machines (ie desktops) there can be only one active session
Tags What's this?: Add a tag
Flag as ContentBug
How to enumerate all applications in a session?      ppadmana   |   Edit   |   Show History
If more than one application is running in a session, is there a way to enumerate all the application names running in that session? Using WTSApplicationName only enumerates the first application launched in that session.
Please direct questions to the microsoft.public.platformsdk.security newsgroup.      Jo Lines - MSFT   |   Edit   |   Show History

The Community Content section of an MSDN library topic provides an area where developers can collaborate on additional information related to that topic. Use this section to contribute code examples, tips and tricks, and links to other relevant content.

You can use the MSDN Forums (http://forums.microsoft.com/msdn/) or the Microsoft public security newsgroups (http://www.microsoft.com/technet/community/newsgroups/security/) to ask questions or participate in discussions about the APIs.

To submit feedback on the documentation, use the feedback link on this page (see the "Send comments about this topic to Microsoft" link).

If you receive useful information from the forums that you want to share with other developers, you can post the information here in the community content.

Thank you.

Tags What's this?: Add a tag
Flag as ContentBug
© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker