Using and Understanding APIs for Terminal Server

Article
02/20/2014

Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Archived content - No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Abstract
Introduction
Functions of Terminal Services API
Terminal Services Administration
Terminal Services Client/Server Support
Kernel Object Name Spaces
Detecting the Terminal Services Environment
Terminal Services Virtual Channels
Using Terminal Services API
Terminal Services API Reference
For More Information

Abstract

Most Microsoft® Win32® applications run without modification in a Terminal Services environment and do not need to use the Terminal Services APIs (advanced programming interfaces.) These new APIs will give software developers the ability to customize existing applications and even develop completely new applications utilizing some of the advanced capabilities and functionality in Terminal Server and Windows® 2000 Server.The Terminal Services API is primarily useful to client/server applications and applications for Terminal Services administration. This paper provides an introduction and reference to the Terminal Server APIs.

Introduction

New API's exposed for Terminal Server Edition and Windows 2000 Server

New APIs (application programming interfaces) will be exposed at the release of Service Pack 4 (SP4) for Microsoft® Windows NT® Server 4.0, Terminal Server Edition (Terminal Server) and Windows® 2000 Server. SP4 for Terminal Server is scheduled for release in early 1999. These new APIs will give software developers the ability to customize existing applications and even develop completely new applications utilizing some of the advanced capabilities and functionality in Terminal Server and Windows 2000 Server.

About Terminal Services

The primary difference between Terminal Services and the traditional mainframe environment is that the dumb terminals in a mainframe environment only provide character-based input and output. Terminal Services enables the Microsoft Windows 2000 Server operating system to act as a terminal server for multiple, simultaneous client sessions. This feature is currently available in Windows NT Server 4.0, Terminal Server Edition. A user of Windows NT can connect to a machine running Terminal Server by logging on to a Terminal Services client or a Terminal Services emulator.

A Terminal Services client is a thin-client hardware device that runs an embedded Windows-based operating system. A Terminal Services emulator is client software that enables a Windows-based, Macintosh, or UNIX client to connect to a machine running Terminal Server to display Windows-based applications. This combination of Terminal Services clients provides access to 16-bit and 32-bit applications for Windows from virtually any desktop.

Terminal Services provides functionality similar to a terminal-based, centralized host, or mainframe environment, in which multiple terminals connect to a host computer. Each terminal provides a conduit for input and output between a user and the host computer. A user can log on at a terminal, and then run applications on the host computer, accessing files, databases, and network resources. Each terminal session is independent, with the host operating system managing conflicts between multiple users contending for shared resources.

A Terminal Services client or emulator provides a complete graphical user interface including a Windows desktop and support for a variety of input devices, such as a keyboard and mouse.

In the Terminal Services environment, an application runs entirely on the computer running Terminal Server. The Terminal Services client performs no local processing of application software. The computer running Terminal Server transmits the graphical user interface to the client. The client transmits the user's input back to the server.

Most Microsoft® Win32® applications run without modification in a Terminal Services environment and do not need to use the Terminal Services API. The Terminal Services API is primarily useful to client/server applications and applications for Terminal Services administration.

The Terminal Services API is a set of function calls into Wtsapi32.dll. This .dll is present on Windows NT Server 4.0 SP4, Terminal Server Edition, and on Windows 2000. These functions will not work on other Windows platforms. To design your application to run in both Terminal Services and non-Terminal Services environments, use run-time dynamic linking to check for the presence of Wtsapi32.dll. For more information, see the section below on Page13: "Run-time Linking to Wtsapi32.dll."

Functions of Terminal Services API

The Terminal Services API enables application programs to perform the following tasks in a Terminal Services environment.

Terminal Services administration, such as enumerating and managing computers running Terminal Server in a domain, or enumerating and managing sessions and processes on a computer running Terminal Server. This is especially useful for software developers who want to add the management of computers running Terminal Server to the suite of functionality that their applications can provide.
Enhancing client/server applications for use in a Terminal Services environment.
Using Terminal Services virtual channels to communicate between client and server components of an application. Utilizing the access provided to the virtual channel structure, existing applications can be augmented and new applications can be developed to add just about any feature to the local client that requires communications between the server and the client.
Setting and retrieving Terminal Services-specific user configuration information for inclusion or use by other applications, such as enterprise-wide management applications. For example, security programs designed by companies and software vendors for specific security tracking can support Terminal Server environments in addition to the regular Desktop/Server infrastructure.

Setting and retrieving Terminal-Services-specific user configuration information.

Terminal Services Administration

The Terminal Services API enables you to enumerate and manage the following: Terminal Servers, client sessions on a Terminal Server, and processes on a Terminal Server.

To retrieve the names of all the Terminal Servers in a domain, call the NetServerEnum function to enumerate servers of the SV_TYPE_TERMINALSERVER type. To open a handle to a specific Terminal Server, pass the server name in a call to the WTSOpenServer function. Call the WTSCloseServer function to close the handle when you are finished with it.

You can use the handle returned by WTSOpenServer to perform the following operations on the server.

WTSDisconnectSession	Disconnects the client from a specified session. The session remains active and the user can log on again to connect to the same session.
WTSEnumerateSessions	Returns a list of sessions on the specified Terminal Server.
WTSEnumerateProcesses	Returns a list of processes on the specified Terminal Server.
WTSLogoffSession	Logs off the specified session.
WTSQuerySessionInformation	Returns information about the specified session on the specified Terminal Server.
WTSSendMessage	Shows a message box on the client display of a specified session.
WTSShutdownSystem	Shuts down and optionally restarts a specified Terminal Server.
WTSTerminateProcess	Terminates a specified process on a specified Terminal Server.
WTSVirtualChannelOpen	Opens a handle to the server end of a specified virtual channel.
WTSWaitSystemEvent	Waits for a Terminal Services event, such as the creation of a client session or a user logging on to the Terminal Server.

Several of these functions allocate buffers to return information to the caller. Call the WTSFreeMemory function to free the buffer when you are finished with it.

Terminal Services Client/Server Support

Client/server applications can use the Terminal Services API to enhance their functionality when running in a Terminal Services environment.

The client component of a client/server application can call the ProcessIdToSessionId function to retrieve its Terminal Services session identifier. The client then uses some form of interprocess communication to pass its session identifier to the server component. The client and server components can then use the session identifier to set up a private communication channel. For example, the server can use the session identifier to access objects in the session's name space for kernel objects. For more information, see Kernel Object Name Spaces.

The server component of a client/server application can use the session identifier in a WTSQuerySessionInformation call to retrieve additional information about the client. The server component can also use the session identifier in a WTSSendMessage call to display a message on the client terminal.

Kernel Object Name Spaces

A Terminal Server has multiple name spaces for the following named kernel objects: events, semaphores, mutexes, waitable timers, file-mapping objects, and job objects. There is a global name space used primarily by Windows NT services such as client/server applications. In addition, each client session has a separate name space for these objects. Note that this differs from the standard Windows environment in which all processes and services share a single name space for these objects.

The separate client session name spaces enable multiple clients to run the same applications without interfering with each other. For processes started under a client session, the system uses the session name space by default. However, these processes can use the global name space by prepending the "Global\" prefix to the object name. For example, the following code creates an event object named CSAPP in the global name space:

CreateEvent( NULL, FALSE, FALSE, "Global\\CSAPP" );

Windows NT services on a Terminal Server use the global name space by default. Processes started under the Terminal Server console session (session zero) also use the global name space by default. The global name space enables processes on multiple client sessions to communicate with a Windows NT service or the console session. For example, a client/server application might use a mutex object for synchronization. The server component running as a Windows NT service can create the mutex object in the global name space. Then the client component running as a process running under a client session can use the "Global\" prefix to open the mutex object.

Another use of the global name space is for applications that use named objects to detect that there is already an instance of the application running in the system across all sessions. This named object must be created or opened in the global name space instead of the per-session name space. Note that the more common case of running the application once per session is supported by default since the named object is created in a per session name space.

Client processes can also use the "Local\" prefix to explicitly create an object in their session name space.

The keywords "Local", "Global" and "Session" are reserved for system use and should not be used as names for named kernel objects. These keywords are case sensitive. On Windows 2000 and later without Terminal Services, these keywords are ignored. On earlier versions of the system, the functions for creating or opening these objects fail if you specify a name containing the backslash character ' \ '.

Detecting the Terminal Services Environment

An application can detect if it is being installed in or is running in a Terminal Services environment. The application can then optimize its behavior for its environment.

This topic describes two techniques for detecting whether Terminal Services is running:

For applications that will run only on Windows 2000 or later.
For applications that must be binary-compatible with earlier versions of Windows.

Applications designed for Windows 2000 and later can use the VerifyVersionInfo function to detect Terminal Services. The following code sample shows a function that return a nonzero value if Terminal Services is running. Note that this code is not compatible with earlier versions of Windows.

BOOL AreWeRunningTerminalServices(void)
{
OSVERSIONINFOEX osVersionInfo;
DWORDLONG dwlConditionMask = 0;
ZeroMemory(&osVersionInfo, sizeof(OSVERSIONINFOEX));
osVersionInfo.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osVersionInfo.wSuiteMask = VER_SUITE_TERMINAL;
VER_SET_CONDITION( dwlConditionMask, VER_SUITENAME, VER_AND );
 return VerifyVersionInfo(
 &osVersionInfo,
 VER_SUITENAME,
 dwlConditionMask
 );
}

If your application needs to be binary-compatible with Windows 2000 and earlier versions of Windows, use the following code to detect Terminal Services. On a Windows 2000 system, this code dynamically links to the VerifyVersionInfo function which it uses to test for the Terminal Services product suite. On earlier versions of Windows, the code checks for registry values that indicate the presence of Terminal Services on those platforms.

#include <windows.h>
#include <winbase.h>
BOOL ValidateProductSuite (LPSTR SuiteName);
BOOL IsTerminalServicesEnabled( VOID )
{
BOOL    bResult = FALSE;
DWORD   dwVersion;
OSVERSIONINFOEXA osVersionInfo;
DWORDLONG dwlConditionMask = 0;
HMODULE hmodK32 = NULL;
HMODULE hmodNtDll = NULL;
typedef ULONGLONG (*PFnVerSetConditionMask) (ULONGLONG, ULONG, UCHAR);
typedef BOOL (*PFnVerifyVersionInfoA) (POSVERSIONINFOEXA, 
                                        DWORD, DWORDLONG);
PFnVerSetConditionMask pfnVerSetConditionMask;
PFnVerifyVersionInfoA pfnVerifyVersionInfoA;
dwVersion = GetVersion();
// Are we running Windows NT?
if (!(dwVersion & 0x80000000)) {
// Is it Windows 2000 or greater?
if (LOBYTE(LOWORD(dwVersion)) > 4) {
// In Windows 2000, use the VerifyVersionInfo and 
// VerSetConditionMask functions. Don't static link because 
// it won't load on earlier systems.
// Get a VerSetConditionMask pointer and set the condition mask.
hmodNtDll = GetModuleHandleA( "ntdll.dll" );
if (hmodNtDll) {
pfnVerSetConditionMask = (PFnVerSetConditionMask) 
GetProcAddress( hmodNtDll, "VerSetConditionMask");
if (pfnVerSetConditionMask) 
dwlConditionMask = (*pfnVerSetConditionMask)
(dwlConditionMask, VER_SUITENAME, VER_AND);
}
// Get a VerifyVersionInfo pointer.
hmodK32 = GetModuleHandleA( "KERNEL32.DLL" );
if (hmodK32 != NULL) {
pfnVerifyVersionInfoA = (PFnVerifyVersionInfoA)GetProcAddress( 
hmodK32, "VerifyVersionInfoA") ;
if (pfnVerifyVersionInfoA != NULL) {
ZeroMemory(&osVersionInfo, sizeof(osVersionInfo));
osVersionInfo.dwOSVersionInfoSize = sizeof(osVersionInfo);
osVersionInfo.wSuiteMask = VER_SUITE_TERMINAL;4
 bResult = (*pfnVerifyVersionInfoA) (&osVersionInfo, 
 VER_SUITENAME, dwlConditionMask);
 }
 }
 }
 else  // This is Windows NT 4.0 or earlier.
 bResult = ValidateProductSuite( "Terminal Server" );
}
return bResult;
}
////////////////////////////////////////////////////////////
// ValidateProductSuite function
//
// Terminal Services detection code for systems running
// Windows NT 4.0 and earlier.
//
////////////////////////////////////////////////////////////
BOOL ValidateProductSuite (LPSTR SuiteName) {
BOOL fValidated = FALSE;
LONG lResult;
HKEY hKey = NULL;
DWORD dwType = 0;
DWORD dwSize = 0;
LPSTR lpszProductSuites = NULL;
LPSTR lpszSuite;
// Open the ProductOptions key.
lResult = RegOpenKeyA(
HKEY_LOCAL_MACHINE,
"System\\CurrentControlSet\\Control\\ProductOptions",
&hKey
);
if (lResult != ERROR_SUCCESS)
goto exit;
// Determine required size of ProductSuite buffer.
lResult = RegQueryValueExA( hKey, "ProductSuite", NULL, &dwType, NULL, &dwSize );
if (lResult != ERROR_SUCCESS || !dwSize)
goto exit;
// Allocate buffer.
lpszProductSuites = (LPSTR) LocalAlloc( LPTR, dwSize );
if (!lpszProductSuites)
goto exit;
// Retrieve array of product suite strings.
lResult = RegQueryValueExA( hKey, "ProductSuite", NULL, &dwType,
(LPBYTE) lpszProductSuites, &dwSize );
if (lResult != ERROR_SUCCESS || dwType != REG_MULTI_SZ)
goto exit;
// Search for suite name in array of strings.
lpszSuite = lpszProductSuites;
while (*lpszSuite) {
 if (lstrcmpA( lpszSuite, SuiteName ) == 0) {
 fValidated = TRUE;
 break;
}
lpszSuite += (lstrlenA( lpszSuite ) + 1);
}
exit:
if (lpszProductSuites)
LocalFree( lpszProductSuites );
if (hKey)
RegCloseKey( hKey );
return fValidated;
}

Terminal Services Virtual Channels

The RDP protocol provides multiplexed management of multiple virtual channels. A virtual channel is a session-oriented transmission connection that can be used by application layer code. Virtual channels are used to add functional enhancements to the client, independent of the RDP protocol. With virtual channel support, new features can be added without having to update the client or server software, or the RDP protocol.

Four major classes of users of virtual channels have been identified:

General kernel mode drivers, such as serial or printer drivers.
File system redirection (this is just a special case of a general kernel mode driver).
User mode applications, for example remote cut-and-paste.
Audio devices.

To use virtual channels, you must provide the server-side and client-side components of a virtual channels application. The server component can be a user-mode application or a kernel-mode driver. The client component must be a DLL. For descriptions of these components, see Virtual Channel Server Application and Virtual Channel Client DLL.

Virtual Channel Client DLL

The client component of a virtual channels application is a DLL that is loaded during the Terminal Services initialization on the client computer. The DLL must be registered on the client computer. For more information, see Virtual Channel Client Registration.

The client DLL must export a VirtualChannelEntry function, which Terminal Services calls during initialization. The VirtualChannelEntry entry point receives a pointer to a CHANNEL_ENTRY_POINTS structure. This structure contains pointers to the functions the client DLL calls to access virtual channels.

VirtualChannelInit	Registers the names of the virtual channels to be used by the client and provides a VirtualChannelInitEvent callback function through which Terminal Services notifies the client about events that affect the client connection.
VirtualChannelOpen	Opens the client end of a specified virtual channel and provides a VirtualChannelOpenEvent callback function through which Terminal Services notifies the client about events that affect the virtual channel.
VirtualChannelWrite	Writes data to a virtual channel. Terminal Services sends this data to the server end of the virtual channel. The server end calls the WTSVirtualChannelRead function to read the data.
VirtualChannelClose	Closes a virtual channel.

Your DLL's VirtualChannelEntry function must call the VirtualChannelInit function to initialize access to virtual channels. When you call VirtualChannelInit, you must pass a pointer to VirtualChannelInitEvent callback function. Terminal Services calls this callback function when initialization has been completed and again when a connection has been established with a Terminal Server.

After the Terminal Server connection is established (the CHANNEL_EVENT_CONNECTED notification), you can call the VirtualChannelOpen function to open the virtual channels registered by the VirtualChannelInit call. The VirtualChannelOpen call specifies a pointer to your VirtualChannelOpenEvent callback function.

After the VirtualChannelOpen call returns, you can call the VirtualChannelWrite function to write to the virtual channel. The write operation is asynchronous, so you must not free or reuse the buffer passed to VirtualChannelWrite until Terminal Services calls your VirtualChannelOpenEvent function to indicate that the write operation has been completed. When you call VirtualChannelWrite, you can pass a piece of user data that identifies the write operation. Terminal Services passes this user data back when it calls VirtualChannelOpenEvent to notify you that the operation has been completed. At the server end of the virtual channel, the server add-in calls the WTSVirtualChannelRead function to read the data.

Terminal Services also calls your VirtualChannelOpenEvent function when data is written to the virtual channel by the server component. The server component calls the WTSVirtualChannelWrite function to write data to the server end of the virtual channel.

The client and server components can write data blocks of any size to the virtual channel. Before sending the data, however, Terminal Services segments the data into chunks of CHANNEL_CHUNK_LENGTH bytes. Terminal Services calls your VirtualChannelOpenEvent function once for each chunk of data, rather than rebuilding the data into a block of the original size.

Each call to VirtualChannelOpenEvent indicates the size of the chunk, the total size written by the server, and whether the data constitutes the beginning, middle, or end of a block written by the server.

You can call the VirtualChannelClose function to close a channel. However, it is not necessary to call it because Terminal Services closes all channels automatically when the client disconnects from the server.

Virtual Channel Client Registration

You must store the name of the client DLL in the registry, or in Mstsc.ini on 16-bit client systems.

In the registry, add a subkey to one of the following locations.

HKEY_LOCAL_MACHINE \Software \Microsoft
\Terminal Server Client\Default\Addins
HKEY_LOCAL_MACHINE \Software \Microsoft
\Terminal Server Client\configuration name\Addins

Entries under the \Default\Addins key apply to all connections. Entries under the \configuration name\Addins key apply only to the configuration identified by configuration name. The subkey can have any name and it must have a REG_SZ value with the following form:

Name = DLLname

On 16-bit systems, the Mstsc.ini file contains an [Addins] section. Add a line to this section with the name of your add-in.

AddinName=

Create an [AddinName] section containing a single entry with the name of the DLL.

[AddinName]
Name = DLLname

Virtual Channel Server Application

The Terminal Server component of an application that uses virtual channels must be a user-mode application running in a client session. The server component must be registered on the Terminal Server. For more information, see Virtual Channel Server Registration.

For each registered server application, Terminal Services creates a set of event objects that are signaled when a client connects or disconnects. The names of these event objects use the following format:

Global\AddinName-SessionId-Connect
Global\AddinName-SessionId-Disconnect

AddinName is the name of the registry subkey under which the server application registered itself. SessionId is the session identifier of a client session.

A user-mode application on the Terminal Server can call the WTSVirtualChannelOpen function to open a handle to a virtual channel. The application can then use the handle in any of the following functions.

WTSVirtualChannelClose	Closes an open virtual channel handle.
WTSVirtualChannelPurgeInput	Purges all queued input data sent from the client to the server on a specific virtual channel.
WTSVirtualChannelPurgeOutput	Purges all queued output data sent from the server to the client on a specific virtual channel.
WTSVirtualChannelQuery	Queries data related to a virtual channel.
WTSVirtualChannelRead	Reads data from the server end of a virtual channel.
WTSVirtualChannelWrite	Writes data to the server end of a virtual channel.

Virtual Channel Server Registration

You must store the name of the virtual channel server application in the registry. Add a subkey under the following location.

HKEY_LOCAL_MACHINE \System \CurrentControlSet \Control
\TerminalServer\Addins\addin_key

The addin_key subkey can have any name. It must have a REG_SZ value that contains the symbolic name of the driver or program.

Name = ApplicationName

It must also have a REG_DWORD value that indicates the type of server application.

Type = ApplicationType

ApplicationType must be the following value.

Value	Meaning
0	User-mode application, session space.

Terminal Services User Configuration

The WTSQueryUserConfig and WTSSetUserConfig functions enable you to set and retrieve configuration information for a specified user account. The WTS_CONFIG_CLASS enumeration type defines the user configuration parameters.

Using Terminal Services API

Run-time Linking to Wtsapi32.dll

If your application will run in a non-Terminal Services environment, but you want to use the Terminal Services API to provide additional functionality in a Terminal Services environment, use run-time dynamic linking to link with Wtsapi32.dll. To do this, call the LoadLibrary function to load Wtsapi32.dll. If the LoadLibrary call fails, your program can run using its basic functionality. If LoadLibrary succeeds, you can call the GetProcAddress function to retrieve pointers to the Terminal Services functions you want to call.

If your application is intended only for a Terminal Services environment, run-time linking is not necessary. In this case, you can include Wtsapi32.h and link with Wtsapi32.lib. Then if your program starts up in a non-Terminal Services environment, it will exit because Wtsapi32.dll is not present.

Terminal Services API Reference

The following elements are used with the Terminal Services API:

Terminal Services API Functions
Terminal Services API Structures
Terminal Services API Enumeration Types

Terminal Services API Functions

The following functions are used with Terminal Services.

ProcessIdToSessionId

VirtualChannelClose
VirtualChannelEntry
VirtualChannelInit
VirtualChannelInitEvent
VirtualChannelOpen
VirtualChannelOpenEvent
VirtualChannelWrite
WTSCloseServer
WTSDisconnectSession
WTSEnumerateProcesses
WTSEnumerateSessions
WTSFreeMemory
WTSLogoffSession
WTSOpenServer
WTSQuerySessionInformation
WTSQueryUserConfig
WTSSendMessage
WTSSetUserConfig
WTSShutdownSystem
WTSTerminateProcess
WTSVirtualChannelClose
WTSVirtualChannelOpen
WTSVirtualChannelPurgeInput
WTSVirtualChannelPurgeOutput
WTSVirtualChannelQuery
WTSVirtualChannelRead
WTSVirtualChannelWrite
WTSWaitSystemEvent

ProcessIdToSessionId

The ProcessIdToSessionId function retrieves the Terminal Services session associated with a specified process.

BOOL ProcessIdToSessionId(
DWORD dwProcessId,
DWORD *pSessionId
);

Parameters

dwProcessId

Specifies a process identifier. Use the GetCurrentProcessId function to retrieve the process identifier for the current process.

pSessionId

Pointer to a DWORD variable that receives the session identifier of the Terminal Services session under which the specified process is running. A value of zero identifies the Terminal Server console session.

Return Values

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

If the calling process is not running in a Terminal Services environment, the value returned in pSessionId is zero.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in winbase.h.
Import Library: Use kernel32.lib.

See Also

WTSQuerySessionInformation

VirtualChannelClose

The VirtualChannelClose function closes the client end of a virtual channel.

Terminal Services provides a pointer to a VirtualChannelClose function in the CHANNEL_ENTRY_POINTS structure passed to your VirtualChannelEntry entry point.

UINT VirtualChannelClose ( 
DWORD openHandle
);

Parameters

openHandle

A handle that identifies the virtual channel. This is the handle returned in the pOpenHandle parameter of the VirtualChannelOpen function.

Return Values

If the function succeeds, the return value is CHANNEL_RC_OK.

If an error occurs, the function returns one of the following values.

Value	Meaning
CHANNEL_RC_BAD_CHANNEL_HANDLE	The openHandle handle is not valid.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.

See Also

VirtualChannelOpen

VirtualChannelEntry

The VirtualChannelEntry function is an application-defined entry point for the client-side DLL of an application that uses Terminal Services virtual channels. Terminal Services calls this entry point to pass a set of function pointers to the client DLL. The client calls these functions to work with virtual channels. Your VirtualChannelEntry implementation must call the VirtualChannelInit function to initialize access to virtual channels.

BOOL VCAPITYPE VirtualChannelEntry (
PCHANNEL_ENTRY_POINTS pEntryPoints
);

Parameters

pEntryPoints

Pointer to a CHANNEL_ENTRY_POINTS structure that contains pointers to the client-side virtual channel functions.

Return Values

Return TRUE if the function is successful.

Return FALSE if an error occurs. In this case, Terminal Services unloads your DLL.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.
Import Library: User-defined.

See Also

CHANNEL_ENTRY_POINTS, VirtualChannelInit

VirtualChannelInit

The VirtualChannelInit function initializes a client DLLs access to Terminal Services virtual channels. The client calls VirtualChannelInit to register the names of its virtual channels.

Terminal Services provides a pointer to a VirtualChannelInit function in the CHANNEL_ENTRY_POINTS structure passed to your VirtualChannelEntry entry point.

UINT VirtualChannelInit (
LPVOID *ppInitHandle,
PCHANNEL_DEF pChannel,
INT channelCount,
ULONG versionRequested,
PCHANNEL_INIT_EVENT_FN pChannelInitEventProc
);

Parameters

ppInitHandle

Pointer to a variable that receives a handle that identifies the client connection. Use this handle to identify the client in subsequent calls to the VirtualChannelOpen function.

pChannel

Pointer to an array of CHANNEL_DEF structures. Each structure contains the name and initialization options of a virtual channel that the client DLL will open. Note that the VirtualChannelInit call does not open these virtual channels; it only reserves the names for use by this application.

When VirtualChannelInit returns, the options member of each CHANNEL_DEF structure includes CHANNEL_OPTION_INITIALIZED flag if the channel was successfully initialized.

The maximum number of channels per client session is CHANNEL_MAX_COUNT.

channelCount

Specifies the number of entries in the pChannel array.

versionRequested

Specifies the level of virtual channel support. Set this parameter to VIRTUAL_CHANNEL_VERSION_WIN2000.

pChannelInitEventProc

Pointer to an application-defined VirtualChannelInitEvent function that Terminal Services calls to notify the client DLL of virtual channel events.

Return Values

If the function succeeds, the return value is CHANNEL_RC_OK.

If an error occurs, the function returns one of the following values.

Value	Meaning
CHANNEL_RC_ALREADY_INITIALIZED	The client has already been initialized.
CHANNEL_RC_ALREADY_CONNECTED	The client is already connected to a Terminal Server.
CHANNEL_RC_TOO_MANY_CHANNELS	The pChannel array has too many channels.
CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY	The VirtualChannelInit function was not called from within your VirtualChannelEntry function.

Remarks

You can call the VirtualChannelInit function only from your VirtualChannelEntry function. Calls to VirtualChannelInit at any other time fail.

When VirtualChannelInit returns successfully, Terminal Services has registered the requested channels. However, Terminal Services may not have completed other initialization. When all initialization is complete, Terminal Services calls your VirtualChannelInitEvent callback function with the CHANNEL_EVENT_INITIALIZED event.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.

See Also

CHANNEL_DEF, VirtualChannelEntry, VirtualChannelInitEvent

VirtualChannelInitEvent

The VirtualChannelInitEvent function is an application-defined callback function that Terminal Services calls to notify the client DLL of virtual channel events.

The CHANNEL_INIT_EVENT_FN type defines a pointer to this callback function. VirtualChannelInitEvent is a placeholder for the application-defined or library-defined function name.

VOID VCAPITYPE VirtualChannelInitEvent (
LPVOID pInitHandle,
UINT event,
LPVOID pData,
UINT dataLength
);

Parameters

pInitHandle

A handle that identifies the client connection. This is the same as the handle returned in the ppInitHandle parameter of the VirtualChannelInit function.

event

Indicates the event that caused the notification. This parameter can be one of the following values.

Value	Meaning
CHANNEL_EVENT_INITIALIZED	The Terminal Services client initialization has been completed. The pData parameter is NULL.
CHANNEL_EVENT_CONNECTED	A connection has been established with a Terminal Server that supports virtual channels. The pData parameter is a pointer to a null-terminated string with the name of the server.
CHANNEL_EVENT_V1_CONNECTED	A connection has been established with a Terminal Server that does not support virtual channels. The pData parameter is NULL.
CHANNEL_EVENT_DISCONNECTED	The connection to the Terminal Server has been disconnected. The pData parameter is NULL.
CHANNEL_EVENT_TERMINATED	The client has been terminated. The pData parameter is NULL.

pData

Pointer to additional data for the event. The type of data depends on the event, as described in the event flag descriptions.

dataLength

Specifies the size, in bytes, of the data in the pData buffer.

Return Values

This function has no return values.

Remarks

The client DLL uses the VirtualChannelInit function to register its VirtualChannelInitEvent function with Terminal Services.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.
Import Library: User-defined.

See Also

VirtualChannelInit

VirtualChannelOpen

The VirtualChannelOpen function opens the client end of a virtual channel.

Terminal Services provides a pointer to a VirtualChannelOpen function in the CHANNEL_ENTRY_POINTS structure passed to your VirtualChannelEntry entry point.

UINT VirtualChannelOpen (
  LPVOID pInitHandle,
  LPDWORD pOpenHandle,
  PCHAR pChannelName,
  PCHANNEL_OPEN_EVENT_FN pChannelOpenEventProc
);

Parameters

pInitHandle

A handle that identifies the client connection. This is the handle returned in the ppInitHandle parameter of the VirtualChannelInit function.

pOpenHandle

Pointer to a variable that receives a handle that identifies the open virtual channel in subsequent calls to the VirtualChannelWrite and VirtualChannelClose functions.

pChannelName

Pointer to a null-terminated string containing the name of the virtual channel to open. The name must have been registered when the client called the VirtualChannelInit function.

pChannelOpenEventProc

Pointer to an application-defined VirtualChannelOpenEvent function that Terminal Services calls to notify the client DLL of events for this virtual channel.

Return Values

If the function succeeds, the return value is CHANNEL_RC_OK.

If an error occurs, the function returns one of the following values.

Value	Meaning
CHANNEL_RC_NOT_INITIALIZED	The client connection has not been initialized by the VirtualChannelInit function.
CHANNEL_RC_NOT_CONNECTED	The client has not connected to a Terminal Server.
CHANNEL_RC_BAD_CHANNEL_NAME	The pChannelName name is not valid.
CHANNEL_RC_BAD_INIT_HANDLE	The pInitHandle handle is not valid.

Remarks

The client DLL cannot call this function until the client has established a connection with a Terminal Server. Your VirtualChannelInitEvent function receives a CHANNEL_EVENT_CONNECTED notification when a Terminal Server connection is established.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.

See Also

VirtualChannelClose, VirtualChannelInit, VirtualChannelInitEvent, VirtualChannelOpenEvent, VirtualChannelWrite

VirtualChannelOpenEvent

The VirtualChannelOpenEvent function is an application-defined callback function that Terminal Services calls to notify the client DLL of events for a specific virtual channel.

The CHANNEL_OPEN_EVENT_FN type defines a pointer to this callback function. VirtualChannelOpenEvent is a placeholder for the application-defined or library-defined function name.

VOID VCAPITYPE VirtualChannelOpenEvent (
  DWORD openHandle,
  UINT event,
  LPVOID pData,
  UINT32 dataLength,
  UINT32 totalLength,
  UINT32 dataFlags
);

Parameters

openHandle

A handle that identifies the virtual channel. This is the same as the handle returned in the pOpenHandle parameter of the VirtualChannelOpen function.

event

Indicates the event that caused the notification. This parameter can be one of the following values.

Value	Meaning
CHANNEL_EVENT_DATA_RECEIVED	The virtual channel received data from the server end. pData is a pointer to a chunk of the data. dataLength indicates the size of this chunk. totalLength indicates the total size of the data written by the server.
CHANNEL_EVENT_WRITE_COMPLETE	A write operation started by a VirtualChannelWrite call has been completed. pData is the value specified in the pUserData parameter of VirtualChannelWrite.
CHANNEL_EVENT_WRITE_CANCELLED	A write operation started by a VirtualChannelWrite call has been cancelled. pData is the value specified in the pUserData parameter of VirtualChannelWrite. A write operation is cancelled when the client session is disconnected. This notification enables you to free any memory associated with the write operation.

pData

Pointer to additional data for the event. The type of data depends on the event, as described in the event flag descriptions.

If event is CHANNEL_EVENT_DATA_RECEIVED, the data written by the server is broken into chunks of not more than CHANNEL_CHUNK_LENGTH bytes. The dataFlags parameter indicates whether the current chunk is at the beginning, middle, or end of the block of data written by the server.

dataLength

Specifies the size, in bytes, of the data in the pData buffer.

totalLength

Specifies the total size, in bytes, of the data written by a single write operation to the server end of the virtual channel.

dataFlags

Flags that provide information about the chunk of data being received in a CHANNEL_EVENT_DATA_RECEIVED event. This parameter can be a combination of the following values.

Value	Meaning
CHANNEL_FLAG_FIRST	The chunk is the beginning of the data written by a single write operation at the server end.
CHANNEL_FLAG_LAST	The chunk is the end of the data written by a single write operation at the server end.
CHANNEL_FLAG_ONLY	Combines the CHANNEL_FLAG_FIRST and CHANNEL_FLAG_LAST values. The chunk contains all the data from a single write operation at the server end.
CHANNEL_FLAG_MIDDLE	This is the default. The chunk is in the middle of a block of data written by a single write operation at the server end.

Return Values

This function has no return values.

Remarks

The client DLL uses the VirtualChannelOpen function to register a VirtualChannelOpenEvent function for a specific virtual channel.

You can use the same VirtualChannelOpenEvent function for multiple calls to VirtualChannelOpen.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.
Import Library: User-defined.

See Also

VirtualChannelOpen

VirtualChannelWrite

The VirtualChannelWrite function sends data from the client end of a virtual channel to a partner application on the server end.

Terminal Services provides a pointer to a VirtualChannelWrite function in the CHANNEL_ENTRY_POINTS structure passed to your VirtualChannelEntry entry point.

UINT VirtualChannelWrite (
  DWORD openHandle,
  LPVOID pData,
  UINT dataLength,
  LPVOID pUserData
);

Parameters

openHandle

A handle that identifies the virtual channel. This is the handle returned in the pOpenHandle parameter of the VirtualChannelOpen function.

pData

Pointer to a buffer containing the data to write.

dataLength

Specifies the number of bytes of the data in the pData buffer to write.

pUserData

An application-defined value. This value is passed to your VirtualChannelOpenEvent function when the write operation is completed or cancelled.

Return Values

If the function succeeds, the return value is CHANNEL_RC_OK.

If an error occurs, the function returns one of the following values.

Value	Meaning
CHANNEL_RC_NOT_INITIALIZED	The client connection has not been initialized by the VirtualChannelInit function.
CHANNEL_RC_NOT_CONNECTED	The client has not connected to a Terminal Server.
CHANNEL_RC_BAD_CHANNEL_HANDLE	The openHandle handle is not valid.

Remarks

The VirtualChannelWrite function is asynchronous. When the write operation has been completed, your VirtualChannelOpenEvent function receives a CHANNEL_EVENT_WRITE_COMPLETE notification. Until that notification is received, the caller must not free or reuse the pData buffer passed to VirtualChannelWrite.

The value specified for the pUserData parameter is passed to your VirtualChannelOpenEvent function when the write operation is completed or cancelled. You can use this data to identify the write operation.

The server add-in at the server end of the virtual channel calls the WTSVirtualChannelRead function to read the data written by a VirtualChannelWrite call.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.

See Also

VirtualChannelOpen, VirtualChannelOpenEvent, WTSVirtualChannelRead

WTSCloseServer

The WTSCloseServer function closes an open handle to a Terminal Server.

VOID WTSCloseServer(
HANDLE hServer
);

Parameters

hServer

Handle to a Terminal Server opened by a call to the WTSOpenServer function.

Do not specify WTS_CURRENT_SERVER_HANDLE for this parameter.

Return Values

This function has no return values.

Remarks

Call the WTSCloseServer function as part of your program's clean-up to close all server handles opened using the WTSOpenServer function.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSOpenServer

WTSDisconnectSession

The WTSDisconnectSession function 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.

BOOL WTSDisconnectSession(
HANDLE hServer,
DWORD SessionId,
BOOL bWait
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

SessionId

A Terminal Services session identifier. To indicate the current session, specify WTS_CURRENT_SESSION. You can use the WTSEnumerateSessions function to retrieve the identifiers of all sessions on a specified Terminal Server.

bWait

Indicates whether the operation is synchronous. Specify TRUE to wait for the operation to complete, or FALSE to return immediately.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSEnumerateSessions

WTSEnumerateProcesses

The WTSEnumerateProcesses function returns information about the active processes on a specified Terminal Server.

BOOL WTSEnumerateProcesses(
HANDLE hServer,
DWORD Reserved,
DWORD Version,
PWTS_PROCESS_INFO *ppProcessInfo,
DWORD *pCount
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

Reserved

Reserved; must be zero.

Version

Specifies the version of the enumeration request. Must be 1.

ppProcessInfo

Pointer to a variable that receives a pointer to an array of WTS_PROCESS_INFO structures. Each structure in the array contains information about an active process on the specified Terminal Server. To free the returned buffer, call the WTSFreeMemory function.

pCount

Pointer to a variable that receives the number of WTS_PROCESS_INFO structures returned in the ppProcessInfo buffer.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTS_PROCESS_INFO

WTSEnumerateSessions

The WTSEnumerateSessions function returns a list of sessions on a specified Terminal Server.

BOOL WTSEnumerateSessions(
HANDLE hServer,
DWORD Reserved,
DWORD Version,
PWTS_SESSION_INFO *ppSessionInfo,
DWORD *pCount
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

Reserved

Reserved; must be zero.

Version

Specifies the version of the enumeration request. Must be 1.

ppSessionInfo

Pointer to a variable that receives a pointer to an array of WTS_SESSION_INFO structures. Each structure in the array contains information about a session on the specified Terminal Server. To free the returned buffer, call the WTSFreeMemory function.

pCount

Pointer to the variable that receives the number of WTS_SESSION_INFO structures returned in the ppSessionInfo buffer.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT. See Also

Terminal Services API Overview, Terminal Services API Functions, WTS_SESSION_INFO

WTSFreeMemory

The WTSFreeMemory function frees memory allocated by a Terminal Services function.

VOID WTSFreeMemory(
PVOID pMemory
);

Parameters

pMemory

Pointer to the memory to free.

Return Values

This function has no return values.

Remarks

Several Terminal Services functions allocate buffers to return information. Use the WTSFreeMemory function to free these buffers.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSEnumerateProcesses, WTSEnumerateSessions, WTSQuerySessionInformation, WTSQueryUserConfig, WTSVirtualChannelQuery

WTSLogoffSession

The WTSLogoffSession function logs off a specified Terminal Services session.

BOOL WTSLogoffSession(
HANDLE hServer,
DWORD SessionId,
BOOL bWait
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

SessionId

bWait

Indicates whether the operation is synchronous.

If bWait is TRUE, the function returns when the session is logged off.

If bWait is FALSE, the function returns immediately. To verify that the session has been logged off, specify the session identifier in a call to the WTSQuerySessionInformation function. WTSQuerySessionInformation returns zero if the session is logged off.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSEnumerateSessions, WTSQuerySessionInformation

WTSOpenServer

The WTSOpenServer function opens a handle to the specified Terminal Server.

HANDLE WTSOpenServer(
LPTSTR pServerName
);

Parameters

pServerName

Pointer to the NetBIOS name of the Terminal Server.

Return Values

If the function succeeds, the return value is a handle to the specified server.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When you are finished with the handle returned by WTSOpenServer, call the WTSCloseServer function to close it.

You do not need to open a handle for operations performed on the Terminal Server on which your application is running. Use the constant WTS_CURRENT_SERVER_HANDLE instead.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSCloseServer

WTSQuerySessionInformation

The WTSQuerySessionInformation function returns information about the specified session on the specified Terminal Server.

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

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

SessionId

WTSInfoClass

Specifies the type of information to retrieve from the specified session. 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.

Value	Data format
WTSInitialProgram	Pointer to a null-terminated string containing the name of the initial program that Terminal Services runs when the user logs on.
WTSApplicationName	Pointer to a null-terminated string containing the published name of the application the session is running. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSWorkingDirectory	Pointer to a null-terminated string containing the default directory used when launching the initial program.
WTSOEMId	Pointer to a null-terminated string.
WTSSessionId	Pointer to a ULONG containing the session identifier.
WTSUserName	Pointer to a null-terminated string containing the name of the user associated with the session.
WTSWinStationName	Pointer to a null-terminated string containing the name of the specified session.
WTSDomainName	Pointer to a null-terminated string that names the domain of the logged-on user.
WTSConnectState	Pointer to an INT that contains a value from the WTS_CONNECTSTATE_CLASS enumeration type to indicate the session's current connection state.
WTSClientBuildNumber	Pointer to a USHORT. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientName	Pointer to a null-terminated string containing the name of the client. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientDirectory	Pointer to a null-terminated string indicating the directory in which the client is installed. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientProductId	Pointer to a USHORT containing a client-specific product identifier. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientHardwareId	Pointer to a USHORT containing a client-specific hardware identifier. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientAddress	Pointer to a WTS_CLIENT_ADDRESS structure containing the network type and network address of the client. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientDisplay	Pointer to a WTS_CLIENT_DISPLAY structure containing information about the client's display. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.

ppBuffer

Pointer to a variable that receives a pointer to the requested information about the specified session. 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

Pointer to a variable that receives the size, in bytes, of the data returned in ppBuffer. If pBytesReturned is NULL, the byte count is not returned.

Return Values

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 determine whether your program is running on the Terminal Services console, specify WTS_CURRENT_SESSION for the SessionId parameter and WTSSessionId for the WTSInfoClass parameter. The session identifier returned in ppBuffer is zero for the Terminal Services console session.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTS_CLIENT_ADDRESS, WTS_CLIENT_DISPLAY, WTS_CONNECTSTATE_CLASS

WTSQueryUserConfig

The WTSQueryUserConfig function returns configuration information about the specified user on the specified server.

BOOL WTSQueryUserConfig(
LPTSTR pServerName,
LPTSTR pUserName,
WTS_CONFIG_CLASS WTSConfigClass,
LPTSTR *ppBuffer,
DWORD *pBytesReturned
);

Parameters

pServerName

Pointer to a null-terminated string containing the name of a domain controller or a Terminal Server. Specify WTS_CURRENT_SERVER_NAME to indicate the Terminal Server on which your application is running.

pUserName

Pointer to a null-terminated string containing the user name to query.

WTSConfigClass

Specifies the type of information to retrieve about the user. This parameter can be one of the values from the WTS_CONFIG_CLASS enumeration type. The documentation for WTS_CONFIG_CLASS describes the format of the data returned in ppBuffer for each of the information types.

ppBuffer

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

pBytesReturned

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

Return Values

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

The WTSQueryUserConfig and WTSSetUserConfig functions are passed a server name instead of a handle because user account information often resides on a domain controller. To set user configuration information, use the primary domain controller. You can call the NetGetDCName function to get the name of the primary domain controller. To query user configuration information, you can use the NetGetAnyDCName function to get the name of a primary or backup domain controller.

Windows 2000 or later: Any domain controller can set or query user configuration information. Use the DsGetDcName function to retrieve the name of a domain controller.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions

WTSSendMessage

The WTSSendMessage function displays a message box on the client desktop of a specified Terminal Services session.

BOOL WTSSendMessage(
HANDLE hServer,
DWORD SessionId,
LPTSTR pTitle,
DWORD TitleLength,
LPTSTR pMessage,
DWORD MessageLength,
DWORD Style,
DWORD Timeout,
DWORD *pResponse,
BOOL bWait
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

SessionId

pTitle

Pointer to a null-terminated string for the title bar of the message box.

TitleLength

Specifies the length, in bytes, of the title bar string.

pMessage

Pointer to a null-terminated string containing the message to display.

MessageLength

Specifies the length, in bytes, of the message string.

Style

Specifies a set of bit flags that determine the contents and behavior of the message box. This value is typically MB_OK. For a complete list of flags, see the uType parameter of the MessageBox function.

Timeout

If bWait is TRUE, Timeout specifies the time, in seconds, that the function waits for the user's response. If the user does not respond within the time-out interval, pResponse returns IDTIMEOUT. If bWait is FALSE, the Timeout parameter is ignored.

pResponse

Pointer to a variable that receives the user's response, which can be one of the following values.

Value	Meaning
IDABORT	Abort button was selected.
IDCANCEL	Cancel button was selected.
IDIGNORE	Ignore button was selected.
IDNO	No button was selected.
IDOK	OK button was selected.
IDRETRY	Retry button was selected.
IDYES	Yes button was selected.
IDASYNC	The bWait parameter was FALSE, so the function returned without waiting for a response.
IDTIMEOUT	The bWait parameter was TRUE and the time-out interval elapsed.

bWait

If TRUE, WTSSendMessage does not return until the user responds or the time-out interval elapses. If Timeout is zero, the function doesn't return until the user responds.

If FALSE, the function returns immediately and pResponse returns IDASYNC. Use this method for simple information messages (such as print job–notification messages) that do not need to return the user's response to the calling program.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions, MessageBox

WTSSetUserConfig

The WTSSetUserConfig function modifies configuration information for the specified user on the specified domain controller or Terminal Server.

BOOL WTSSetUserConfig(
LPTSTR pServerName,
LPTSTR pUserName,
WTS_CONFIG_CLASS WTSConfigClass,
LPTSTR pBuffer,
DWORD DataLength
);

Parameters

pServerName

Pointer to a null-terminated string containing the name of a domain controller or Terminal Server. Specify WTS_CURRENT_SERVER_NAME to indicate the Terminal Server on which your application is running.

pUserName

Pointer to a null-terminated string containing the name of the user whose configuration is being set.

WTSConfigClass

Specifies the type of information to set for the user. This parameter can be one of the values from the WTS_CONFIG_CLASS enumeration type. The documentation for WTS_CONFIG_CLASS describes the format of the data specified in ppBuffer for each of the information types.

pBuffer

Pointer to the data used to modify the specified user's configuration.

DataLength

Size, in bytes, of the pBuffer buffer.

Return Values

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

Windows 2000 or later: Any domain controller can set or query user configuration information. Use the DsGetDcName function to retrieve the name of a domain controller.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSQueryUserConfig

WTSShutdownSystem

The WTSShutdownSystem function 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. For more information about security privileges, see Privileges.

BOOL WTSShutdownSystem(
HANDLE hServer,
DWORD ShutdownFlag
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

ShutdownFlag

Indicates the type of shutdown. This parameter can be one of the following values.

Value	Meaning
WTS_WSD_LOGOFF	Forces all client sessions to log off and disables all further log ons. This flag does not log off the Terminal Services console session. Log ons are reenabled when the Terminal Server is restarted. Use this flag only on the Terminal Services console.
WTS_WSD_SHUTDOWN	Shuts down the system on the Terminal Server. This is equivalent to calling the ExitWindowsEx function with the EWX_SHUTDOWN flag. The calling process must have the SE_SHUTDOWN_NAME privilege enabled.
WTS_WSD_REBOOT	Shuts down and then restarts the system on the Terminal Server. This is equivalent to calling ExitWindowsEx with the EWX_REBOOT flag. The calling process must have the SE_SHUTDOWN_NAME privilege enabled.
WTS_WSD_FASTREBOOT	Restarts the system on the Terminal Server without shutting down. (See the warning in the following Remarks section.)
WTS_WSD_POWEROFF	Shuts down the system on the Terminal Server and, on computers that support software control of AC power, turns off the power. This is equivalent to calling ExitWindowsEx with the EWX_SHUTDOWN and EWX_POWEROFF flags. The calling process must have the SE_SHUTDOWN_NAME privilege enabled.

Return Values

When run on the server console, if the WTS_WSD_LOGOFF flag is used and the function succeeds, the return value is a nonzero value. If run on another session—or one of the other flags is used and the function succeeds—the server is shut down and the program terminates.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

A system shutdown terminates all users and active programs. The following steps occur during shutdown.

An exit command is issued to all active user applications.
If the application does not exit within a specific interval, the application is terminated.
After all the applications for a user terminate, the user is logged off.
After all users are logged off, an exit command is issued to all system services.
If the system service does not terminate within a specific interval, the service is terminated.
The file system cache is written to disk.
The disks are marked Read Only.
The Terminal Server displays the "System can be turned off" message, or the system is rebooted if the WTS_WSD_REBOOT flag is specified.

Warning: Because WTS_WSD_FASTREBOOT can cause severe data loss or file corruption, use it only if absolutely necessary. WTS_WSD_FASTREBOOT forces an immediate shutdown, skipping steps 1 through 5 above. Consequently, WTS_WSD_FASTREBOOT does not give applications an opportunity to save their work and clean up properly.

Because there can be many users and processes in a large multiuser configuration, large system configurations may take some time to shut down in an orderly fashion. It is important to allow the system to shut down completely.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, ExitWindowsEx

WTSTerminateProcess

The WTSTerminateProcess function terminates a specified process on a specified Terminal Server.

BOOL WTSTerminateProcess(
HANDLE hServer,
DWORD ProcessId,
DWORD ExitCode
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

ProcessId

Specifies the process identifier of the process to terminate.

ExitCode

Specifies the exit code for the terminated process.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions

WTSVirtualChannelClose

The WTSVirtualChannelClose function closes an open virtual channel handle.

BOOL WTSVirtualChannelClose(
HANDLE hChannelHandle
);

Parameter

hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSVirtualChannelOpen

WTSVirtualChannelOpen

The WTSVirtualChannelOpen function opens a handle to the server end of a specified virtual channel.

HANDLE WTSVirtualChannelOpen(
HANDLE hServer,
DWORD SessionId,
LPSTR pVirtualName
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

SessionId

pVirtualName

Pointer to a null-terminated string containing the virtual channel name. This is an ANSI string (even when UNICODE is defined) of seven characters, padded with spaces if necessary.

Return Values

If the function succeeds, the return value is a handle to the specified virtual channel.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSVirtualChannelClose

WTSVirtualChannelPurgeInput

The WTSVirtualChannelPurgeInput function purges all queued input data sent from the client to the server on a specified virtual channel.

BOOL WTSVirtualChannelPurgeInput(
HANDLE hChannelHandle
);

Parameter

hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSVirtualChannelPurgeOutput

WTSVirtualChannelPurgeOutput

The WTSVirtualChannelPurgeOutput function purges all queued output data sent from the server to the client on a specified virtual channel.

BOOL WTSVirtualChannelPurgeOutput(
HANDLE hChannelHandle
);

Parameter

hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSVirtualChannelPurgeInput

WTSVirtualChannelQuery

The WTSVirtualChannelQuery function returns data related to a virtual channel.

BOOL WTSVirtualChannelQuery(
HANDLE hChannelHandle,
WTS_VIRTUAL_CLASS WTSVirtualClass,
PVOID *ppBuffer,
DWORD *pBytesReturned
);

Parameters

hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

WTSVirtualClass

Type of information to request. Currently, the only defined value is WTSVirtualClientData, which returns virtual channel client module data.

ppBuffer

Pointer to the address of a variable to receive the data. To free the returned buffer, call the WTSFreeMemory function.

pBytesReturned

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

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions

WTSVirtualChannelRead

The WTSVirtualChannelRead function reads data from the server end of a virtual channel.

WTSVirtualChannelRead reads the data written by a VirtualChannelWrite call at the client end of the virtual channel.

BOOL WTSVirtualChannelRead(
HANDLE hChannelHandle,
ULONG TimeOut,
PCHAR Buffer,
ULONG BufferSize,
PULONG pBytesRead
);

Parameters

hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

TimeOut

Specifies the time-out, in milliseconds. If TimeOut is zero, WTSVirtualChannelRead returns immediately if there is no data to read. If TimeOut is INFINITE (defined in Winbase.h), the function waits indefinitely until there is data to read.

Buffer

Pointer to a buffer that receives a chunk of data read from the server end of the virtual channel. The maximum amount of data that the server can receive in a single WTSVirtualChannelRead call is CHANNEL_CHUNK_LENGTH bytes. If the client's VirtualChannelWrite call writes a larger block of data, the server must make multiple WTSVirtualChannelRead calls.

If the client set the CHANNEL_OPTION_SHOW_PROTOCOL option when it called VirtualChannelInit to initialize the virtual channel, the data chunk is preceded by a CHANNEL_PDU_HEADER structure. Otherwise, the buffer receives only the data written in the VirtualChannelWrite call.

BufferSize

Specifies the size, in bytes, of Buffer. If the client set the CHANNEL_OPTION_SHOW_PROTOCOL option, the buffer should be at least CHANNEL_PDU_LENGTH bytes. Otherwise, the buffer should be at least CHANNEL_CHUNK_LENGTH bytes.

pBytesRead

Pointer to a variable that receives the number of bytes read.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, CHANNEL_PDU_HEADER, VirtualChannelWrite, WTSVirtualChannelWrite

WTSVirtualChannelWrite

The WTSVirtualChannelWrite function writes data to the server end of a virtual channel.

BOOL WTSVirtualChannelWrite(
HANDLE hChannelHandle,
PCHAR Buffer,
ULONG Length,
PULONG pBytesWritten
);

Parameters

hChannelHandle

Handle to a virtual channel opened by the WTSVirtualChannelOpen function.

Buffer

Pointer to a buffer containing the data to write to the virtual channel.

Length

Specifies the size, in bytes, of the data to write.

pBytesWritten

Pointer to a variable that receives the number of bytes written.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSVirtualChannelRead

WTSWaitSystemEvent

The WTSWaitSystemEvent function waits for a Terminal Services event before returning to the caller.

BOOL WTSWaitSystemEvent(
HANDLE hServer,
DWORD EventMask,
DWORD *pEventFlags
);

Parameters

hServer

Handle to a Terminal Server. Specify a handle opened by the WTSOpenServer function, or specify WTS_CURRENT_SERVER_HANDLE to indicate the Terminal Server on which your application is running.

EventMask

Bit mask that specifies the set of events to wait for. This mask can be WTS_EVENT_FLUSH to cause all pending WTSWaitSystemEvent calls on the specified Terminal Server handle to return. Or, the mask can be a combination of the following values.

Value	Meaning
WTS_EVENT_CREATE	A new WinStation was created.
WTS_EVENT_DELETE	An existing WinStation was deleted.
WTS_EVENT_LOGON	A user logged on to the system from either the Terminal Services console or from a client WinStation.
WTS_EVENT_LOGOFF	A user logged off from either the Terminal Services console or from a client WinStation.
WTS_EVENT_CONNECT	A client connected to a WinStation.
WTS_EVENT_DISCONNECT	A client disconnected from a WinStation.
WTS_EVENT_RENAME	An existing WinStation was renamed.
WTS_EVENT_STATECHANGE	A WinStation's connection state changed. For a list of connection states, see the WTS_CONNECTSTATE_CLASS enumeration type.
WTS_EVENT_LICENSE	The Terminal Services's license state changed. This occurs when a license is added or deleted using License Manager.
WTS_EVENT_ALL	Wait for any event type.

pEventFlags

Pointer to a variable that receives a bit mask of the event or events that occurred. The returned mask can be a combination of the values from the previous table, or it can be WTS_EVENT_NONE if the wait terminated because of a WTSWaitSystemEvent call with the WTS_EVENT_FLUSH flag.

Return Values

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.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Import Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions

Terminal Services API Structures

The following functions are used with the Terminal Services API.

CHANNEL_DEF

CHANNEL_ENTRY_POINTS
WTS_CLIENT_ADDRESS
WTS_CLIENT_DISPLAY
WTS_PROCESS_INFO
WTS_SESSION_INFO

CHANNEL_DEF

The CHANNEL_DEF structure contains the name and options of a Terminal Services virtual channel. A client DLL uses this structure when it calls the VirtualChannelInit function to register a virtual channel name.

typedef struct tagCHANNEL_DEF {
    char            name[CHANNEL_NAME_LEN + 1];
    ULONG           options;
} CHANNEL_DEF, * PCHANNEL_DEF, * * PPCHANNEL_DEF;

Members

name

A null-terminated string containing the name of a virtual channel. Virtual channel names can contain from 1 to CHANNEL_NAME_LEN characters.

options

Specifies the options for this virtual channel. This member can be a combination of the following values.

Value	Meaning
CHANNEL_OPTION_INITIALIZED	Not used.
CHANNEL_OPTION_ENCRYPT_RDP	Encrypt according to RDP data encryption (that is, if RDP data is encrypted, do so for this channel, too).
CHANNEL_OPTION_ENCRYPT_SC	Encrypt Server to Client data (ignored if CHANNEL_OPTION_ENCRYPT_RDP is set).
CHANNEL_OPTION_ENCRYPT_CS	Encrypt Client to Server data (ignored if CHANNEL_OPTION_ENCRYPT_RDP is set).
CHANNEL_OPTION_PRI_HIGH	Send data at high priority (not recommended, as this may impact RDP performance.
CHANNEL_OPTION_PRI_MED	Send data at medium priority.
CHANNEL_OPTION_PRI_LOW	Send data at low priority.
CHANNEL_OPTION_COMPRESS_RDP	Compress data in this channel if RDP data compression is configured for this connection.
CHANNEL_OPTION_COMPRESS	Compress data in this channel, irrespective of RDP data compression (ignored if CHANNEL_OPTION_COMPRESS_RDP is set).
CHANNEL_OPTION_SHOW_PROTOCOL	Affects how data sent by a VirtualChannelWrite call is received at the server end. If this flag is set, each data block is preceded by a CHANNEL_PDU_HEADER structure. If this flag is not set, the data block includes only the data specified in the VirtualChannelWrite call.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in pchannel.h.

See Also

VirtualChannelInit

CHANNEL_ENTRY_POINTS

The CHANNEL_ENTRY_POINTS structure contains pointers to the functions called by a client-side DLL to access virtual channels. Terminal Services calls your VirtualChannelEntry function to fill in this structure.

typedef struct tagCHANNEL_ENTRY_POINTS
{
    DWORD cbSize;
    DWORD protocolVersion;
    PVIRTUALCHANNELINIT  pVirtualChannelInit;
    PVIRTUALCHANNELOPEN  pVirtualChannelOpen;
    PVIRTUALCHANNELCLOSE pVirtualChannelClose;
    PVIRTUALCHANNELWRITE pVirtualChannelWrite;
} CHANNEL_ENTRY_POINTS, FAR * PCHANNEL_ENTRY_POINTS;

Members

cbSize

Specifies the size, in bytes, of this structure.

protocolVersion

Specifies the protocol version. Terminal Services sets this member to VIRTUAL_CHANNEL_VERSION_WIN2000.

pVirtualChannelInit

Pointer to a VirtualChannelInit function.

pVirtualChannelOpen

Pointer to a VirtualChannelOpen function.

pVirtualChannelClose

Pointer to a VirtualChannelClose function.

pVirtualChannelWrite

Pointer to a VirtualChannelWrite function.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in cchannel.h.

See Also

VirtualChannelClose, VirtualChannelEntry, VirtualChannelInit, VirtualChannelOpen, VirtualChannelWrite

CHANNEL_PDU_HEADER

The CHANNEL_PDU_HEADER structure contains information about a data block being received by the server end of a virtual channel.

typedef struct tagCHANNEL_PDU_HEADER {
    UINT32    length;
    UINT32    flags;
} CHANNEL_PDU_HEADER, FAR * PCHANNEL_PDU_HEADER;

Members

length

Indicates the size, in bytes, of the data block, including this header.

flags

Flags that provide information about the data block. This parameter can be a combination of the following values.

Value	Meaning
CHANNEL_FLAG_FIRST	The chunk is the beginning of the data written by a single write operation.
CHANNEL_FLAG_LAST	The chunk is the end of the data written by a single write operation.
CHANNEL_FLAG_ONLY	Combines the CHANNEL_FLAG_FIRST and CHANNEL_FLAG_LAST values. The chunk contains all the data from a single write operation.
CHANNEL_FLAG_MIDDLE	This is the default. The chunk is in the middle of a block of data written by a single write operation.

Remarks

The CHANNEL_PDU_HEADER structure is used if the client DLL sets the CHANNEL_OPTION_SHOW_PROTOCOL option when it calls the VirtualChannelInit function to initialize the virtual channel. If this option is set, Terminal Services places a CHANNEL_PDU_HEADER structure at the beginning of each chunk of data read by a call to the WTSVirtualChannelRead function.

QuickInfo

Version: Requires RDP 5.0 client or later.

Header: Declared in pchannel.h.

See Also

VirtualChannelInit, VirtualChannelWrite, WTSVirtualChannelRead

WTS_CLIENT_ADDRESS

The WTS_CLIENT_ADDRESS structure contains the client network address of a Terminal Services session.

typedef struct _WTS_CLIENT_ADDRESS {
    DWORD AddressFamily;
    BYTE  Address[20];
} WTS_CLIENT_ADDRESS, * PWTS_CLIENT_ADDRESS;

Members

AddressFamily

Indicates the address family. This member can be AF_INET, AF_IPX, AF_NETBIOS, or AF_UNSPEC.

Address

Indicates the client network address.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.

See Also

Terminal Services API Overview, Terminal Services API Structures, WTSQuerySessionInformation

WTS_CLIENT_DISPLAY

The WTS_CLIENT_DISPLAY structure contains information about the display of a Terminal Services client.

typedef struct _WTS_CLIENT_DISPLAY {
    DWORD HorizontalResolution;
    DWORD VerticalResolution;
    DWORD ColorDepth;
} WTS_CLIENT_DISPLAY, * PWTS_CLIENT_DISPLAY;

Members

HorizontalResolution

Horizontal dimension, in pixels, of the client's display.

VerticalResolution

Vertical dimension, in pixels, of the client's display.

ColorDepth

Color depth of the client's display. This member can be one of the following values.

Value	Meaning
1	The display uses 4 bits per pixel for a maximum of 16 colors.
2	The display uses 8 bits per pixel for a maximum of 256 colors.
4	The display uses 16 bits per pixel for a maximum of 2^16 colors.
8	The display uses 3-byte RGB values for a maximum of 2^24 colors.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.

See Also

Terminal Services API Overview, Terminal Services API Structures, WTSQuerySessionInformation

WTS_PROCESS_INFO

The WTS_PROCESS_INFO structure contains information about a process running on a Terminal Server.

typedef struct _WTS_PROCESS_INFO {
    DWORD SessionId;
    DWORD ProcessId;
    LPTSTR pProcessName;
    PSID pUserSid;
} WTS_PROCESS_INFO, * PWTS_PROCESS_INFO;

Members

SessionId

The Terminal Services session identifier for the session associated with the process.

ProcessId

The process identifier that uniquely identifies the process on the Terminal Server.

pProcessName

Pointer to a null-terminated string containing the name of the executable file associated with the process.

pUserSid

Pointer to the user SID in the process's primary access token.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Terminal Services API Overview, Terminal Services API Structures, WTSEnumerateProcesses

WTS_SESSION_INFO

The WTS_SESSION_INFO structure contains information about a client session on a Terminal Server.

typedef struct _WTS_SESSION_INFO{
    DWORD SessionId;
    LPTSTR pWinStationName;
    WTS_CONNECTSTATE_CLASS State;
} WTS_SESSION_INFO, * PWTS_SESSION_INFO;

Members

SessionId

The session identifier of the session.

pWinStationName

Pointer to a null-terminated string containing the name of the WinStation for this session.

State

A value from the WTS_CONNECTSTATE_CLASS enumeration type indicating the session's current connection state.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Terminal Services API Overview, Terminal Services API Structures, WTSEnumerateSessions

Terminal Services API Enumeration Types

The following enumeration types are used with the Terminal Services API.

WTS_CONFIG_CLASS

WTS_CONNECTSTATE_CLASS
WTS_INFO_CLASS
WTS_VIRTUAL_CLASS

WTS_CONFIG_CLASS

The WTS_CONFIG_CLASS enumeration type contains values that indicate the type of user configuration information to set or retrieve in a call to the WTSQueryUserConfig and WTSSetUserConfig functions.

typedef enum _WTS_CONFIG_CLASS {
    WTSUserConfigInitialProgram,
    WTSUserConfigWorkingDirectory,
    WTSUserConfigfInheritInitialProgram,
    WTSUserConfigfAllowLogonTerminalServer,
    WTSUserConfigTimeoutSettingsConnections,
    WTSUserConfigTimeoutSettingsDisconnections,
    WTSUserConfigTimeoutSettingsIdle,
    WTSUserConfigfDeviceClientDrives,
    WTSUserConfigfDeviceClientPrinters,
    WTSUserConfigfDeviceClientDefaultPrinter,
    WTSUserConfigBrokenTimeoutSettings,
    WTSUserConfigReconnectSettings,
    WTSUserConfigModemCallbackSettings,
    WTSUserConfigModemCallbackPhoneNumber,
    WTSUserConfigShadowingSettings,
    WTSUserConfigTerminalServerProfilePath,
    WTSUserConfigTerminalServerHomeDir,
    WTSUserConfigTerminalServerHomeDirDrive,
    WTSUserConfigfTerminalServerRemoteHomeDir
} WTS_CONFIG_CLASS;

Enumerator Values

WTSUserConfigInitialProgram

A null-terminated string containing the path of the initial program that Terminal Services runs when the user logs on.

If the WTSUserConfigfInheritInitialProgram value is 1, the initial program can be any program specified by the client.

WTSUserConfigWorkingDirectory

A null-terminated string containing the path of the working directory for the initial program.

WTSUserConfigfInheritInitialProgram

A DWORD flag that indicates whether the client can specify the initial program.

Value	Meaning
0	The client cannot specify the initial program. The WTSUserConfigInitialProgram string indicates the initial program. If you specify a user's initial program, that's the only program they can run; Terminal Server logs off the user when the user exits that program.
1	The client can specify the initial program.

WTSUserConfigfAllowLogonTerminalServer

A DWORD flag that indicates whether the user account is permitted to log on to a Terminal Server.

Value	Meaning
0	The user cannot logon.
1	The user can logon.

WTSUserConfigTimeoutSettingsConnections

A DWORD that specifies the maximum connection duration, in minutes. One minute before the connection timeout interval expires, the user is notified of the pending disconnection. The user's session is disconnected or terminated depending on the WTSUserConfigBrokenTimeoutSettings value. Every time the user logs on, the timer is reset. A value of zero indicates the connection timer is disabled.

WTSUserConfigTimeoutSettingsDisconnections

A DWORD that specifies the maximum duration, in minutes, that a Terminal Server retains a disconnected session before the logon is terminated. A value of zero indicates the disconnection timer is disabled.

WTSUserConfigTimeoutSettingsIdle

A DWORD that specifies the maximum idle time, in minutes. If there is no keyboard or mouse activity for the specified interval, the user's session is disconnected or terminated depending on the WTSUserConfigBrokenTimeoutSettings value. A value of zero indicates the idle timer is disabled.

WTSUserConfigfDeviceClientDrives

Citrix ICA clients only: A DWORD flag that indicates whether the Terminal Server automatically reestablishes client drive mappings at logon.

Value	Meaning
0	The server does not automatically connect to previously mapped client drives.
1	The server automatically connects to previously mapped client drives at logon.

WTSUserConfigfDeviceClientPrinters

RDP 5.0 clients and Citrix ICA clients: A DWORD flag that indicates whether the Terminal Server automatically reestablishes client printer mappings at logon.

Value	Meaning
0	The server does not automatically connect to previously mapped client printers.
1	The server automatically connects to previously mapped client printers at logon.

WTSUserConfigfDeviceClientDefaultPrinter

RDP 5.0 clients and Citrix ICA clients: A DWORD flag that indicates whether the client printer is the default printer.

Value	Meaning
0	The client printer is not the default printer.
1	The client printer is the default printer.

WTSUserConfigBrokenTimeoutSettings

A DWORD flag that indicates what happens when the connection or idle timers expire or when a connection is lost due to a connection error.

Value	Meaning
0	The session is disconnected.
1	The session is terminated.

WTSUserConfigReconnectSettings

A DWORD flag that indicates how a disconnected session for this user can be reconnected.

Value	Meaning
0	The user can log on to any client computer to reconnect to a disconnected session. Note that sessions started at clients other than the system console cannot be connected to the system console, and sessions started at the system console cannot be disconnected.
1	The user can reconnect to a disconnected session by logging on to the client computer used to establish the disconnected session. If the user logs on from a different client computer, the user gets a new logon session.

WTSUserConfigModemCallbackSettings

Citrix ICA clients only: A DWORD value that indicates the configuration for dialup connections in which the Terminal Server hangs up and then calls back the client to establish the connection.

Value	Meaning
0	Callback connections are disabled.
1	The server prompts the user to enter a phone number and calls the user back at that phone number. You can use the WTSUserConfigModemCallbackPhoneNumber value to specify a default phone number.
2	The server automatically calls the user back at the phone number specified by the WTSUserConfigModemCallbackPhoneNumber value.

WTSUserConfigModemCallbackPhoneNumber

Citrix ICA clients only: A null-terminated string containing the phone number to use for callback connections.

WTSUserConfigShadowingSettings

RDP 5.0 clients and Citrix ICA clients: A DWORD flag that indicates whether the user session can be shadowed. Shadowing allows a user to remotely monitor the on-screen operations of another user.

Value	Meaning
0	The session cannot be shadowed.
1	The session can be shadowed.

WTSUserConfigTerminalServerProfilePath

A null-terminated string containing the path of the user's profile for Terminal Server logon.

WTSUserConfigTerminalServerHomeDir

A null-terminated string containing the path of the user's home directory for Terminal Server logon. This string can specify a local path or a UNC path (\\machine\share\path). See WTSUserConfigfTerminalServerRemoteHomeDir.

WTSUserConfigTerminalServerHomeDirDrive

A null-terminated string containing a drive letter to which the UNC path specified in the WTSUserConfigTerminalServerHomeDir string is mapped. See WTSUserConfigfTerminalServerRemoteHomeDir.

WTSUserConfigfTerminalServerRemoteHomeDir

A DWORD flag that indicates whether the user's home directory for Terminal Server logon is a local path or a mapped drive letter.

Value	Meaning
0	The WTSUserConfigTerminalServerHomeDir string contains the local path of the user's Terminal Server logon home directory.
1	The WTSUserConfigTerminalServerHomeDir string contains the UNC path of the user's Terminal Server logon home directory, and the WTSUserConfigTerminalServerHomeDirDrive string contains a drive letter to which the UNC path is mapped.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.

See Also

Terminal Services API Overview, Terminal Services API Enumeration Types, WTSQueryUserConfig, WTSSetUserConfig

WTS_CONNECTSTATE_CLASS

The WTS_CONNECTSTATE_CLASS enumeration type contains values that indicate the connection state of a Terminal Services session.

typedef enum _WTS_CONNECTSTATE_CLASS {
    WTSActive,
    WTSConnected,
    WTSConnectQuery,
    WTSShadow,
    WTSDisconnected,
    WTSIdle,
    WTSListen,
    WTSReset,
    WTSDown,
    WTSInit,
} WTS_CONNECTSTATE_CLASS;

Enumerator Values

WTSActive

A user is logged on to the WinStation.

WTSConnected

The WinStation is connected to the client.

WTSConnectQuery

The WinStation is in the process of connecting to the client.

WTSShadow

The WinStation is shadowing another WinStation.

WTSDisconnected

The WinStation is active but the client is disconnected.

WTSIdle

The WinStation is waiting for a client to connect.

WTSListen

The WinStation is listening for a connection.

WTSReset

The WinStation is being reset.

WTSDown

The WinStation is down due to an error.

WTSInit

The WinStation is initializing.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.

See Also

Terminal Services API Overview, Terminal Services API Enumeration Types, WTS_SESSION_INFO, WTSQuerySessionInformation, WTSWaitSystemEvent

WTS_INFO_CLASS

The WTS_INFO_CLASS enumeration type contains values that indicate the type of session information to retrieve in a call to the WTSQuerySessionInformation function.

typedef enum _WTS_INFO_CLASS {
    WTSInitialProgram,
    WTSApplicationName,
    WTSWorkingDirectory,
    WTSOEMId,
    WTSSessionId,
    WTSUserName,
    WTSWinStationName,
    WTSDomainName,
    WTSConnectState,
    WTSClientBuildNumber,
    WTSClientName,
    WTSClientDirectory,
    WTSClientProductId,
    WTSClientHardwareId,
    WTSClientAddress,
    WTSClientDisplay,
} WTS_INFO_CLASS;

Enumerator Values

WTSInitialProgram

The name of the initial program that Terminal Services runs when the user logs on.

WTSApplicationName

The published name of the application the session is running.

WTSWorkingDirectory

The default directory used when launching the initial program.

WTSOEMId

Not used.

WTSSessionId

The session identifier.

WTSUserName

The name of the user associated with the session.

WTSWinStationName

The name of the session.

WTSDomainName

The name of the domain to which the logged-on user belongs.

WTSConnectState

The session's current connection state.

WTSClientBuildNumber

Build number of the client.

WTSClientName

Name of the client.

WTSClientDirectory

The directory in which the client is installed.

WTSClientProductId

A client-specific product identifier.

WTSClientHardwareId

A client-specific hardware identifier.

WTSClientAddress

The network type and network address of the client.

WTSClientDisplay

Information about the display resolution of the client.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.

See Also

Terminal Services API Overview, Terminal Services API Enumeration Types, WTSQuerySessionInformation

WTS_VIRTUAL_CLASS

The WTS_VIRTUAL_CLASS enumeration type contains values that indicate the type of virtual channel information to retrieve in a call to the WTSVirtualChannelQuery function.

typedef enum _WTS_VIRTUAL_CLASS {
    WTSVirtualClientData,
} WTS_VIRTUAL_CLASS;

Enumerator Values

WTSVirtualClientData

Virtual channel client module data.

QuickInfo

Version: Requires Terminal Server Edition 4.0 SP4 or Windows 2000 or later.

Header: Declared in Wtsapi32.h.

See Also

Terminal Services API Overview, Terminal Services API Enumeration Types, WTSVirtualChannelQuery

For More Information

For the latest information about Windows NT Server 4.0, Terminal Server Edition, check out Microsoft TechNet or our World Wide Web site at https://www.microsoft.com/ntserver/ProductInfo/terminal/default.asp and the Windows NT Server Forum on the Microsoft Network (GO WORD: MSNTS).

Share via

Using and Understanding APIs for Terminal Server

On This Page

Abstract

Introduction

New API's exposed for Terminal Server Edition and Windows 2000 Server

About Terminal Services

Functions of Terminal Services API

Terminal Services Administration

Terminal Services Client/Server Support

Kernel Object Name Spaces

Detecting the Terminal Services Environment

Terminal Services Virtual Channels

Virtual Channel Client DLL

Virtual Channel Client Registration

Virtual Channel Server Application

Virtual Channel Server Registration

Terminal Services User Configuration

Using Terminal Services API

Run-time Linking to Wtsapi32.dll

Terminal Services API Reference

Terminal Services API Functions

VirtualChannelClose

VirtualChannelEntry

VirtualChannelInit

VirtualChannelInitEvent

VirtualChannelOpen

VirtualChannelOpenEvent

VirtualChannelWrite

WTSCloseServer

WTSDisconnectSession

WTSEnumerateProcesses

WTSEnumerateSessions

WTSFreeMemory

WTSLogoffSession

WTSOpenServer

WTSQuerySessionInformation

WTSQueryUserConfig

WTSSendMessage

WTSSetUserConfig

WTSShutdownSystem

WTSTerminateProcess

WTSVirtualChannelClose

WTSVirtualChannelOpen

WTSVirtualChannelPurgeInput

WTSVirtualChannelPurgeOutput

WTSVirtualChannelQuery

WTSVirtualChannelRead

WTSVirtualChannelWrite

WTSWaitSystemEvent

Terminal Services API Structures

CHANNEL_DEF

CHANNEL_ENTRY_POINTS

CHANNEL_PDU_HEADER

WTS_CLIENT_ADDRESS

WTS_CLIENT_DISPLAY

WTS_PROCESS_INFO

WTS_SESSION_INFO

Terminal Services API Enumeration Types

WTS_CONFIG_CLASS

WTS_CONNECTSTATE_CLASS

WTS_INFO_CLASS

WTS_VIRTUAL_CLASS

For More Information

Additional resources