If the session represents a remote user (someone not logged on through the console's keyboard), the script performs additional steps. Two pieces of information that the function returns—the client machine's IP address and display size—are packed into binary structures that the script must unpack. The code at callout C unpacks the IP address structure into two components: the network identifier ($Net) and a 20-byte address array ($Address) that the script must also unpack. When $Net is a value of 0x02, the network is TCP/IP. (Other values indicate IPX, NetBIOS, or other networks.) If the network is TCP/IP, the client's IP address is in bytes 2 through 5 in $Address. The code at callout D looks in those positions to discover the address. The client display's width, height, and color depth are simply packed as three unsigned long values. The trick that the code in callout E performs is to roll the color depth value left by 2 bits to discover the color depth (i.e., the number of colors). The resulting value is the number of bits used to represent a color pixel.
The code at callout F finally displays the information about remote-client sessions that the script has discovered. The script prints to the screen the remote client's IP address, machine name, and display size and color depth.
Managing a Terminal Services Session
If you know the current terminal services sessions on a particular machine, you can perform an action that affects a session. The WTSLogoff.pl script, which Listing 2 shows, lets an administrator disconnect a user's terminal services session or log off the user. Disconnecting a session just closes the connection between the user and the terminal services machine. The user can reconnect later and continue where he or she had left off when you disconnected the session—programs keep running and no data loss occurs. Forcing a log off, however, causes all the user's running applications to close, which might result in the user losing data if he or she had any open files.
When you call WTSLogoff.pl, you pass in the name of the terminal services server and the ID of the session that you want to disconnect or log off. (You can find a session's ID by using WTSListUsers.pl, Task Manager, or Terminal Services Manager.) By default, the script forces the specified session to log off. However, if you pass in a /D parameter, the script disconnects the session instead. For example, the command
perl WTSLogoff.pl myserver 3
logs off session 3 on the terminal server MyServer. The command
perl WTSLogoff.pl myserver 3 /D
disconnects session 3 on MyServer. The user can reconnect and continue his or her session at a later time.
As the code at callout A in Listing 2 shows, WTSLogoff.pl calls the WTSEnumerateSessions() and WTSQuerySessionInformation() functions to procure the remote clients' IP addresses. If you included the /D parameter when you launched WTSLogoff.pl, the code at callout B calls the WTSDisconnectSession() function to force the disconnection. If you didn't specify the /D parameter, the code at callout C calls the WTSLogoffSession() function to close all of the session's applications and log off the user.
Terminal Services Power with Perl
Terminal services is one of the most powerful features of Windows .NET Server, Windows XP, Windows 2000, and Windows NT. The Perl Win32::Lanman extension provides the functions to harness this powerful service. This month, I revealed just the tip of the iceberg. You can access many other interesting and useful terminal services features from Perl. Have a look at the Win32::Lanman extension's documentation and see which functions can make your job easier. Then drop me an email message and let me know what you think.