Obtains information for a specified session on a specified terminal server.
wtsQuerySessionInfo(server,session)
(s) server: This is the name of the terminal server system on which a session will be queried for info. The server name should have the leading "\\" characters on it. Passing in an empty string for this parameter will cause the local terminal server system to be used.
(i) session:This is a session id number that identifies the session that is to be queried for info.
(arr) Returns a single dimensional array containing session information. Refer to the "Notes:" section for more information about the format of the data in the array.
This function can obtain detailed information for any specific session on any specific terminal server system. The script that calls this function must be running on a terminal server system in order to gather information for sessions on either the local system or on a remote terminal server system.
If this function is called for the console session id [usually session # zero], then some of the array element values will be empty strings or zero values. The array element [4], however, is guaranteed to contain the value "CONSOLE" if this function is called for the console session, so it is advisable to check the value of array element [4] before making any assumptions about the validity of any of the other array elements.
The return value is an array with a single dimension. The array contains the following
information:
(s) Result[0] = Session Name. This is the name of the terminal server session.
(s) Result[1] = Connection State. This is the connection state for the terminal server session.
The following connection state values are defined:
"ACTIVE"
"CONNECTED"
"CONNECTQUERY"
"SHADOW"
"DISCONNECTED"
"IDLE"
"LISTEN"
"RESET"
"DOWN"
"INIT"
"*UNKNOWN*"
(s) Result[2] = Client Address. This is the network address of the client workstation that is running the terminal services client program.
This can be a TCP/IP address in decimal dotted notation [e.g. "nnn.nnn.nnn.nnn", or it can be one of the following mnemonic codes that indicates that a network protocol other than TCP/IP is being used for the session [and thus the client address cannot be obtained]:
"*IPX*"
"*NETBIOS*"
"*UNSPEC*" [unspecified]
(s) Result[3] = Client Name. This is the name of the client workstation that is running the terminal services client program. Please note that it is possible for various terminal services client programs [e.g. the Citrix client] to actually override this value via a configuration setting, so there is no 100% guarantee that the client name stored in this array element will actually have any meaning.
(s) Result[4] = Client Protocol. This is the name of the protocol that the terminal services client program used to connect to this particular terminal server session.
The following client protocol names are valid:
"CONSOLE" - The WinNT/2K/XP system physical console.
"ICA" - Citrix's protocol that is used in their Winframe & Metaframe products.
"RDP" - Microsoft's own Remote Desktop Protocol, which is the default protocol used in the Windows Terminal Services product.
(i) Result[5] = Client Hardware Id.
(i) Result[6] = Client Product Id.
(i) Result[7] = Client Build Number.
(s) Result[8] = Client Directory. This is the directory [on the client workstation] in which the terminal services client program was installed.
(i) Result[9] = Client Horizontal Display Resolution.
(i) Result[10] = Client Vertical Display Resolution.
(i) Result[11] = Client Display Color Depth.
The following color depth values are defined:
|
Value |
Meaning |
|
1 |
4 bpp / 16 colors |
|
2 |
8 bpp / 256 colors |
|
4 |
16 bpp / 64K colors |
|
8 |
24 bpp / 16M colors |
(s) Result[12] = OEM Id string.
(s) Result[13] = Domain Name. This is the name of the domain in which the user's account is located.
(s) Result[14] = Username. This is the name of the account used to login to this session.
(s) Result[15] = Application Name. This is the published name of the application that this session is running.
Note: There is a memory leak in the underlying Win32 API function WTSQuerySessionInformation() that only occurs on WinXP & newer systems when the Application Name and Initial Program information items are retrieved. This extender function has been modified to not retrieve these values on WinXP & newer; the value "*UNSUPPORTED*" is returned in the appropriate array elements when this function is called on WinXP & newer systems.
(s) Result[16] = Initial Program Name. This is the name of the program that was initially run when this session was established. Normally, this program is a desktop shell program.
Note: There is a memory leak in the underlying Win32 API function WTSQuerySessionInformation() that only occurs on WinXP & newer systems when the Application Name and Initial Program information items are retrieved. This extender function has been modified to not retrieve these values on WinXP & newer; the value "*UNSUPPORTED*" is returned in the appropriate array elements when this function is called on WinXP & newer systems.
(s) Result[17] = Working Directory. This is the working directory that was specified for the initial program to use when this session was established.
(s) Result[18] = Current Time. This is the current time on the terminal server system on which the session is located. This value can be used in combination with the other session time values to calculate differential times.
(s) Result[19] = Login Time. This is the time when the session was originally logged on.
(s) Result[20] = Last Input Time. This is the last time when the session received input from the terminal services or Citrix client. If the difference between the current time and this time is calculated then the result will be the amount of idle time for the session. The system console session cannot ever go into an idle or disconnected state, so the last input time value for the console session is always the same as the current time value.
(s) Result[21] = Connect Time. This is the most recent time at which a TS/Citrix client has connected to this session. The connected time value may change if a session goes disconnected and then later on is reconnected to another instance of the TS/Citrix client.
(s) Result[22] = Disconnect Time. This is the most recent time at which a TS/Citrix client has disconnected from the session. If the session has never been disconnected, then this value will be an empty string. If the session was disconnected and then was reconnected again later on, this value won't be altered at all. When this value is not an empty string, a comparison between this value and the connected time value may be performed to see which one is greater. If the disconnect time value is greater than the connect time, then the session's status should be disconnected. If the connect time is greater than the disconnect time, then the session was disconnected at one time but has been reconnected and the status for the session should be active or connected.
;Load 32-bit or 64-bit extender AddExtender( "WWWTS44I.DLL" , 0, "WWWTS64I.DLL" )
Title01 = 'Test wtsQuerySessionInfo()' ServerSpec = AskLine('Send a message','Server','') SessId = AskLine('Send a message','Session Id #','') ErrorMode(@OFF) Result = wtsQuerySessionInfo(ServerSpec,SessId) RC = LastError() ErrorMode(@CANCEL) TempMsg = StrCat('wtsQuerySessionInfo("',ServerSpec,'",',SessId,') RC = ',RC,@CRLF) If (RC == 0) TempMsg = StrCat(TempMsg,@CRLF,' Session Name = "',Result[0],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Connection State = "',Result[1],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Address = "',Result[2],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Name = "',Result[3],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Protocol = "',Result[4],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Hardware Id = ',Result[5]) TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Product Id = ',Result[6]) TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Build # = ',Result[7]) TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Directory = "',Result[8],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Display H. Res = ',Result[9]) TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Display V. Res = ',Result[10]) TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Client Display Color Depth = ',Result[11]) TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'OEM Id = "',Result[12],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Domain Name = "',Result[13],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Username = "',Result[14],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Application Name = "',Result[15],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Initial Program Name = "',Result[16],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Working Directory = "',Result[17],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Current Time = "',Result[18],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Login Time = "',Result[19],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Last Input Time = "',Result[20],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Connect Time = "',Result[21],'"') TempMsg = StrCat(TempMsg,@CRLF,@CRLF,'Disconnect Time = "',Result[22],'"') EndIf Message(Title01,TempMsg) Exit