 |
Windows Terminal Server, Virtualization, Application Delivery, Windows Software Development, Market Analysis, Training Classes and more... |
 |
Navigation |
 |
|||||||||||||||||||
|
|||||||||||||||||||||
|
|
Awards |
|
||
|
||||
An Introduction into Terminal Services API Programming
Posted by Benny Tritsch on July 4, 2007 – updated on November 30, 2007
[Introduction] [TS API] [Sample Code] [More Advanced Examples]
The Terminal Services API
You can list function names for a specific DLL by running a variety of command-line tools. For example, you can use dumpbin –exports wtsapi32.dll or link –dump –exports wtsapi32.dll provided by Microsoft Visual Studio 2003 to obtain the function names of the Terminal Services API.
As an alternative the Visual Studio tool Dependency Walker provides a graphical user interface which allows you to list the function names for DLLs. Dependency Walker lists all public Terminal Server functions exposed. It also shows all dependencies to other system DLLs exposing internal system functions, such as Winsta.dll.
Terminal Services API Functions
The following table provides a brief overview of the function set needed for developing terminal server administration tools. Some functions provide both an ANSI (A) and a Unicode (W) entry point which results in associated function name extensions and two assigned ordinals.
| Function | Ordinal | Description |
|---|---|---|
| WTSCloseServer | 1 | Closes an open handle to a terminal server. |
| WTSDisconnectSession | 2 | Disconnects the logged-on user from the specified Terminal Services session without closing the session. If the user subsequently logs on to the same terminal server, the user is reconnected to the same session. |
| WTSEnumerateProcessesA WTSEnumerateProcessesW | 3 4 |
Retrieves information about the active processes on a specified terminal server. |
| WTSEnumerateServersA WTSEnumerateServersW | 5 6 |
Returns a list of all terminal servers within the specified Windows domain. |
| WTSEnumerateSessionsA WTSEnumerateSessionsW | 7 8 |
Retrieves a list of sessions on a specified terminal server. |
| WTSFreeMemory | 9 | Frees memory allocated by a Terminal Services function. |
| WTSLogoffSession | 10 | Logs off a specified Terminal Services session. |
| WTSOpenServerA WTSOpenServerW | 11 12 |
Opens a handle to the specified terminal server. |
| WTSQuerySessionInformationA WTSQuerySessionInformationW | 13 14 |
Retrieves session information for the specified session on the specified terminal server. It can be used to query session information on local and remote terminal servers. |
| WTSQueryUserConfigA WTSQueryUserConfigW | 15 16 |
Retrieves configuration information for the specified user on the specified domain controller or terminal server. |
| WTSQueryUserToken | 17 | Obtains the primary access token of the logged-on user specified by the session ID. To call this function successfully, the calling application must be running within the context of the LocalSystem account and have the SE_TCB_NAME privilege. It is not necessary that Terminal Services be running for the function to succeed, but if Terminal Services is not running, the only valid session identifier is zero (0). This function is intended for highly trusted services. Service providers must use caution that they do not leak user tokens when calling this function. Service providers must close token handles after they have finished with them. |
| WTSRegisterSessionNotification | 18 | Registers the specified window to receive session change notifications. |
| WTSSendMessageA WTSSendMessageW | 19 20 |
Displays a message box on the client desktop of a specified Terminal Services session. |
| WTSSetSessionInformationA WTSSetSessionInformationW | 21 22 |
|
| WTSSetUserConfigA WTSSetUserConfigW | 23 24 |
Modifies configuration information for the specified user on the specified domain controller or terminal server. |
| WTSShutdownSystem | 25 | Shuts down and optionally reboots the specified terminal server. To shut down or reboot the system, the calling process must have the SE_SHUTDOWN_NAME privilege enabled. |
| WTSTerminateProcess | 26 | Terminates the specified process on the specified terminal server. |
| WTSUnRegisterSessionNotification | 27 | Function unregisters the specified window so that it receives no further session change notifications. |
| WTSWaitSystemEvent | 35 | Waits for a Terminal Services event before returning to the caller. |
Very common tasks for custom terminal server applications are to enumerate and manage servers, sessions and processes. To open a handle to a specific terminal server, its server name needs to be passed in a call to the WTSOpenServer function. The handle returned can be used by functions such as WTSEnumerateSessions, WTSQuerySessionInformation or WTSEnumerateProcesses to perform the required operations on the server. Some of these functions allocate buffers to return information to the caller which requires a call of the WTSFreeMemory to free the buffer after usage. A call of the WTSCloseServer function finally closes the handle to the terminal server.
Terminal Services API Structures
Some of the functions may require a parameter that is a pointer to a variable that receives a pointer to an array of structures – a rather advanced construction in traditional C/C++ programming. Such structures are used to receive detailed return information about active processes or sessions after calling the associated function. This is why these structures belong to the Terminal Services API. The same is true for some predefined enumeration types that are used with the Terminal Services API.
| Structure | Description |
|---|---|
| WTS_CLIENT_ADDRESS | Contains the client network address of a Terminal Services session. |
| WTS_CLIENT_DISPLAY | Contains information about the display of a Terminal Services client, such as horizontal resolution, vertical resolution or color depth. |
| WTS_PROCESS_INFO | Contains information about a process running on a terminal server, such as session ID, process ID, process name or user SID. |
| WTS_SESSION_INFO | Contains information about a client session on a terminal server, such as session ID or WinStation name. |
The Terminal Services API is documented in the SDK help files. Structures and constants used are available in the wtsapi32.h header file which is installed to an Include subfolder of the SDK install.
Setting Up the Development Environment
Before we start looking at some sample code you need to know about the requirements for TS API programming. You will need Visual Studio with the Platform SDK installed. If you want to start from scratch without using my sample projects, create a new C++ Win32 Console Application project. Keep all standard settings in the Win32 Application Wizard with one exception: uncheck the option “Precompiled header”. As the next step delete all files you will not need for a C console application and change the project settings according to the following list.
- Add “Wtsapi32.lib” to Configuration Properties | Linker | Command Line | Additional Options
- Change Configuration Properties | General | Character Set to “Use Multi-Byte Character Set”
- Change Configuration Properties | C/C++ | Advanced | Compile As to “Compile as C Code (/TC)”
- Change Configuration Properties | C/C++ | Code Generation | Runtime Library to “Multi-Threaded Debug (/MTd)” or “Multi-Threaded (/MT)”
NOTE: All TS API function headers are declared in Wtsapi32.h, which is stored under %ProgramFiles%\Microsoft Visual Studio 8\VC\PlatformSDK\Include
BEST PRACTICE: Save all (Ctrl+Shift+S), build the solution (F6) and run the executable from the command line.
