Terminal Services

Purpose

Terminal Services enables Microsoft® Windows NT® 4.0 SP4 or Windows® 2000 to act as a terminal server for multiple, simultaneous client sessions. A user can connect to a terminal server by logging on to a Terminal Services client or a Terminal Services emulator.

Where Applicable

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, Macintosh, or UNIX client to connect to a terminal server to display Windows-based applications. This combination of Terminal Services clients provides access to 16-bit and 32-bit Windows-based applications from virtually any desktop.

Developer Audience

The Terminal Services API is designed for use by C/C++ programmers. Familiarity with client/server architecture is required.

Run-time Requirements

Applications that use the Terminal Services require Windows 2000, or Windows NT 4.0 SP4 with Terminal Server. For information on which operating systems or components are required to use a particular function, see the Requirements section of the documentation for the function.

Overview

General information about Terminal Services.

Programming Guidelines

Guidelines for developing applications that perform well in a Terminal Services environment.

Terminal Services API

This set of function calls into Wtsapi32.dll is useful to client/server applications and applications for Terminal Services administration.

Reference

Documentation of Terminal Services functions and structures.

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About Terminal Services

[This is preliminary documentation and subject to change.]

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, network resources, and so on. Each terminal session is independent, with the host operating system managing conflicts between multiple users contending for shared resources.

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. 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 terminal server. The Terminal Services client performs no local processing of application software. The terminal server transmits the graphical user interface to the client. The client transmits the user's input back to the server.

For more information, see the following topics:

  • Resources on a Terminal Server
  • Detecting the Terminal Services Environment
  • Detecting If Terminal Services is Installed
  • Terminal Services Programming Guidelines
  • Terminal Services API


Resources on a Terminal Server

In a Terminal Services environment, multiple users can log on simultaneously to a single terminal server. Consequently, the users are sharing the hardware and software resources of the terminal server, which can create the following areas of contention:

  • CPU time. Each user has his or her own desktop environment and can run whatever applications are available to that desktop. However, all applications run by all users are contending for the central CPU resources available on the terminal server. If one user runs a poorly written, CPU-intensive application, other users might experience a visible loss of performance.
  • Disk access. Users contend for access to applications and related application files. In addition, users contend for disk accesses by the server operating system, such as loading DLLs or swapping memory between the paging file and physical memory.
  • Random Access Memory (RAM). Users contend for RAM on the terminal server because the client computers do not have local RAM.
  • Network access. Network access is essential in a Terminal Services environment because all desktop activity—graphical output and mouse/keyboard input—flows over the network links between the client desktop and the server. In addition, the users' applications running on the terminal server contend for access to other network resources.
  • Server-side hardware components. Hardware components such as CD-ROMs, floppy disk drives, serial ports, and parallel ports are typically server-based, not client-based. Sharing these traditionally non-shared components creates new considerations for users and for applications that access these hardware components. For more information, see Peripheral Hardware.
  • Access to global objects and resources. In a Terminal Services environment, users do not run individual copies of Windows NT/Windows 2000—some of the core components are cloned, but the remaining components are shared among the users. Thus, users are competing for access to the registry, the paging file, system services, and other global objects and resources.

Many of the preceding points of contention can be mitigated by sizing the terminal server with sufficient CPU, memory, and disk resources to handle the client demand. For example, a multiple processor configuration can maximize CPU availability. Memory availability can be maximized by installing extra physical memory. Finally, disk access performance can be maximized by configuring multiple SCSI channels and distributing your operating system and application loads across different physical drives. Properly configuring a terminal server is a critical element of perceived application performance.

Although hardware sizing is an important part of creating a scalable Terminal Services environment, the software considerations are equally important. In fact, fine-tuning an application often can do a lot to reduce resource competition and improve perceived application performance. For more information, see Terminal Services Programming Guidelines.


Detecting the Terminal Services Environment

To optimize performance, it is good practice for applications to detect whether they are running in a Terminal Services client session. For example, when an application is running on a remote session, it should eliminate unnecessary graphic effects, as described in Graphic Effects. If the user is running the application in a console session (directly on the terminal), it is not necessary for the application to optimize its behavior.

Windows 2000 or later: The following code sample shows a function that returns TRUE if the application is running in a remote session and FALSE if the application is running on the console. It works only on Windows 2000.

BOOL IsRemoteSession(void)
{
   return GetSystemMetrics( SM_REMOTESESSION );
}


Detecting If Terminal Services is Installed

Different techniques must be used to detect whether Terminal Services is installed, depending on the following requirements:

  • The application runs only on Microsoft® Windows 2000.
  • The application must be binary-compatible with earlier versions of Windows.

Applications designed for Windows 2000 can use the VerifyVersionInfo function to detect whether Terminal Services is installed. The following code sample shows a function that returns a nonzero value if Terminal Services is installed. 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 earlier versions of Windows, call the IsTerminalServicesEnabled function from the following sample code to detect Terminal Services. On a Windows 2000 system, this code dynamically links to the VerifyVersionInfo and VerSetConditionMask functions, 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>

/* -------------------------------------------------------------
   Note that the ValidateProductSuite and IsTerminalServices
   functions use ANSI versions of Win32 functions to maintain
   compatibility with Windows 95/98.
   ------------------------------------------------------------- */

BOOL ValidateProductSuite (LPSTR lpszSuiteToValidate);

BOOL IsTerminalServicesEnabled( VOID )
{
  BOOL    bResult = FALSE;
  DWORD   dwVersion;
  OSVERSIONINFOEXA osVersion;
  DWORDLONG dwlCondition = 0;
  HMODULE hmodK32 = NULL;
  HMODULE hmodNtDll = NULL;
  typedef ULONGLONG (WINAPI *PFnVerSetCondition) (ULONGLONG, ULONG, UCHAR);
  typedef BOOL (WINAPI *PFnVerifyVersionA) (POSVERSIONINFOEXA, DWORD, DWORDLONG);
  PFnVerSetCondition pfnVerSetCondition;
  PFnVerifyVersionA pfnVerifyVersionA;

  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.

      hmodNtDll = GetModuleHandleA( "ntdll.dll" );
      if (hmodNtDll)
      {
        pfnVerSetCondition = (PFnVerSetCondition) GetProcAddress(
            hmodNtDll, "VerSetConditionMask");
        if (pfnVerSetCondition != NULL)
        {
          dwlCondition = (*pfnVerSetCondition) (dwlCondition,
              VER_SUITENAME, VER_AND);

          // Get a VerifyVersionInfo pointer.

          hmodK32 = GetModuleHandleA( "KERNEL32.DLL" );
          if (hmodK32 != NULL)
          {
            pfnVerifyVersionA = (PFnVerifyVersionA) GetProcAddress(
               hmodK32, "VerifyVersionInfoA") ;
            if (pfnVerifyVersionA != NULL)
            {
              ZeroMemory(&osVersion, sizeof(osVersion));
              osVersion.dwOSVersionInfoSize = sizeof(osVersion);
              osVersion.wSuiteMask = VER_SUITE_TERMINAL;
              bResult = (*pfnVerifyVersionA) (&osVersion,
                  VER_SUITENAME, dwlCondition);
            }
          }
        }
      }
    }
    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 lpszSuiteToValidate)
{
  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, lpszSuiteToValidate ) == 0)
      {
          fValidated = TRUE;
          break;
      }
      lpszSuite += (lstrlenA( lpszSuite ) + 1);
  }

exit:
  if (lpszProductSuites)
      LocalFree( lpszProductSuites );

  if (hKey)
      RegCloseKey( hKey );

  return fValidated;
}


Terminal Services Programming Guidelines

Most existing 16-bit or 32-bit Windows-based applications run "as is" in a Terminal Services environment. However, some applications perform well in a Terminal Services environment; others do not perform as well. These topics provide guidelines for developing applications that perform well in a Terminal Services environment.

  • Building a Terminal-Services-Aware Application
  • Application Setup in a Terminal Services Environment
  • Storing User-Specific Information
  • Kernel Object Name Spaces
  • IP Addresses and Computer Names
  • Client/Server Applications
  • Graphic Effects
  • Peripheral Hardware
  • Background Tasks
  • Thread Usage
  • Other Guidelines for Terminal Services
  • Legacy Applications in a Terminal Services Environment

Many of these guidelines are good programming practices that will benefit applications running in either a Terminal Services or a traditional Windows NT/Windows 2000 environment. However, some of the sections recommend optimizations, such as limiting graphic effects, that you would want only when your application is running under Terminal Services. For sample code that illustrates how to detect a Terminal Services environment, see Detecting the Terminal Services Environment.

Note Following these guidelines does not limit or compromise an application's ability to function in the traditional Windows NT/Windows 2000 environment—applications optimized for Terminal Services work well in both environments.


Building a Terminal-Services Aware Application

Platform SDK: Terminal Services

Building a Terminal-Services – Aware Application

[This is preliminary documentation and subject to change.]

You can run legacy applications in a Terminal Services environment. When the terminal server loads an application that is not Terminal-Services – aware, it also loads a DLL that contains compatibility code. If your application is Terminal-Services – aware, you can avoid the overhead of loading this extra DLL and running the compatibility code.

To indicate that your application is Terminal-Services – aware, set the IMAGE_DLLCHARACTERISTICS_TERMINAL_SERVER_AWARE flag in the optional header. If you are writing an application that meets the following criteria, it can set the IMAGE_DLLCHARACTERISTIC_TERMINAL_SERVER_AWARE flag:

  • The application does not use .ini files. (For more information, see Legacy Applications in a Terminal Services Environment.)
  • The application does not write to HKEY_CURRENT_USER during setup. (For more information, see Storing User-Specific Information.)


Application Setup in a Terminal Services Environment

The automated setup procedure for many existing applications assumes that the application is being installed for a single user. In a multi-user Terminal Services environment, this assumption can create the following problems:

  • If the setup procedure updates the registry and desktop environment for just one user, additional users must reinstall the entire package or an administrator must manually copy information from the registry and desktop of one user to the other users.
  • With some setup procedures, you can customize the application at installation time by excluding features or components. If the initial installer excludes part of the application, additional users must reinstall the application to get the excluded features.

To avoid these problems, setup procedures should use the following guidelines when installing an application on a terminal server:

  • Install applications into the default user environment common to all users.
  • Support user-specific customization through the use of user profiles. To do this, create an administrative template file so an administrator can easily configure the registry to indicate the features available to each user. Then, at run time, the application can enable or disable features depending on the settings in the current user's registry hives.


Storing User-Specific Information

In a Terminal Services environment, applications should store user-specific information in user-specific locations, separately from global information that applies to all users. This rule applies to information stored in the registry, as well as information stored in files. In general, do not assume that one computer is equivalent to one user.

Store user-specific registry information under the HKEY_CURRENT_USER registry key. Terminal Services loads the current user's personal registry hive into HKEY_CURRENT_USER when the user logs on. Of course, Terminal Services manages the registry to ensure that each of the logged on clients detects the correct user hive under HKEY_CURRENT_USER.

In contrast, all users share the HKEY_LOCAL_MACHINE hive. Use HKEY_LOCAL_MACHINE to store computer-specific information, not user-specific information.

Store user preference files or other user-specific files in the user's home directory or in a user-specified directory. This consideration applies to temporary files used to store interim information (such as cached data) or to pass data on to another application. User-specific temporary files must also be stored on a per-user basis.

You can use the SHGetSpecialFolderLocation function with the CSIDL_PERSONAL flag to get the location of the user's personal files directory. You can also use the GetWindowsDirectory function to retrieve the path of the Windows directory. In a Terminal Services environment, the Windows directory is guaranteed to be private for each user. Do not store user-specific files under the system directory (for example, WINNT) or program directory (for example, Program Files).


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 Win32 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" );

Win32 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 Win32 service or the console session. For example, a client/server application might use a mutex object for synchronization. The server component running as a Win32 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 "Local", "Global" and "Session" prefixes are reserved for system use and should not be used as names for kernel objects. These keywords are case sensitive. On Windows 2000 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 (\).


IP Addresses and Computer Names

Multiple users can be logged on simultaneously to a terminal server. Consequently, it is not safe to assume that the computer name or the IP address assigned to the computer are associated with a single user. This differs from a traditional Windows NT/Windows 2000 system, in which only one user is logged on at a time.

Applications that use the computer name or IP address for licensing or as a means of identifying an iteration of the application on the network will not work properly in a Terminal Services environment because the server's computer name or IP address can be associated with many users.

In a Terminal Services environment, each client terminal or terminal emulator has a separate IP address and computer name. To retrieve the IP address and computer name of a client, call the WTSQuerySessionInformation function. Other Win32 calls for retrieving these network addresses and computer names retrieve the name and address of the terminal server. For example, the GetComputerNameEx function returns the computer name of the terminal server.


Client/Server Applications

Client/server applications in a Terminal Services environment must be able to handle multiple clients connecting from the same computer. If your application is composed of a server component (such as a Win32 service) and client components that connect to the server component, make sure that the server component can differentiate between multiple clients residing on the same system. To accomplish this, clients should establish communication with the server component through a well-defined global interface (for example, RPC or named pipes). The server and client should negotiate a different communication channel for each user session.

This same client/server consideration applies to client applications running in a Terminal Services environment that must establish connections to server components over the network. In this case, the client/server connection should use protocols that easily support this type of operation, such as TCP/IP where a different socket connection can be used for each client application. Applications should not assume that a single system connection is equivalent to a single user session.

Prompts for user input are another potential source of problems for client/server applications in which the server component is a Win32 service. For example, if a Win32 service calls the MessageBox function, the message box is displayed on the desktop of the terminal server, not on the client desktop. To display a message on a client desktop, the service can call the WtsSendMessage function. Alternatively, the service can request input from the client application, and the client can display the user interface and send the resulting input back to the service.


Graphic Effects

A terminal server relies on the network to transmit all input and output to its client terminals. Consequently, applications that make excessive use of graphic effects can affect performance for all Terminal Services clients by slowing down the network. In addition, the slower transmission speed over a network might cause these special effects to appear less pleasing than they would be in a local video environment.

In particular, applications should disable or minimize the use of the following features when running in a Terminal Services environment as a remote session:

  • Splash screens—graphical product or company information displayed while an application is starting. Transmitting a splash screen to a Terminal Services client consumes extra network bandwidth and forces the user to wait before accessing the application.
  • Animations, which consume both CPU time and network bandwidth.
  • Direct input or output to the video display. If you need to read bits from the screen, maintain a separate, off-screen copy of the video buffer. Similarly, if you need to do elaborate screen output—for example, overlaying several images to arrive at a final composite screen—do that work in an off-screen buffer, and then send the results to the actual video buffer.


Peripheral Hardware

To a Terminal Services client, the terminal server is the local computer. Consequently, devices such as disk drives and printers attached to the server appear as local devices to a client. In contrast, drives and printers attached to a client terminal appear to be remote devices. To access a device attached to a client terminal, you must use the UNC name of the client share or printer, just as you would any other remote share or printer.

The initial release of Terminal Services does not support applications that send output directly to serial, parallel, and sound ports attached to the client terminal. In other words, the serial, parallel, and sound ports attached to the client terminal are not treated as local ports. However, you can use the built-in redirectors to do the appropriate "net share" and "net use" commands to share these devices.


Background Tasks

Background tasks—tasks performed when an application's message loop is idle—provide a mechanism for handling low-priority tasks in a single-user environment. In a Terminal Services environment, however, one user's background task competes for CPU cycles with another user's foreground tasks. When multiple users are running both foreground and background tasks, the CPU demands are much higher than when all users are running only foreground tasks. To maximize CPU availability for all users, either disable background tasks when running in a Terminal Services environment or create efficient background tasks that are not resource-intensive.


Thread Usage

Threads provide a convenient way of allowing an application to maximize its usage of CPU resources in a system, especially in a multiple processor configuration. In a Terminal Services environment, however, multiple users can be running multi-threaded applications, and all of the threads for all of the users compete for the central CPU resources of that system. With this in mind, you should tune and balance application thread usage for a multi-user, multiprocessor Terminal Services environment.


Other Guidelines for Terminal Services

When you are developing applications to run in a Terminal Services environment, follow these guidelines:

  • Lock files and databases while making changes to prevent other users from make simultaneous changes to the same data.
  • Check your application for memory leaks and resolve any problems. Of course this is good advice for any application, but in a Terminal Services environment an application can be run multiple times by multiple users, thus rapidly magnifying the effect of a memory leak.
  • Use the MFC library whenever possible. The MFC library has a long list of tried-and-true classes for performing a wide variety of tasks. Most of these classes work well in a Terminal Services environment—usually much better than re-engineered solutions. A good example is the class that provides context-sensitive help text—help text that appears on-screen when the mouse pointer hovers over a button or menu item. If an application uses the MFC implementation to provide this feature, it will work reasonably well on the desktop system. But if the application implements this feature using dialog boxes or an alternate approach, the final result might not function well in a Terminal Services environment.


Legacy Applications in a Terminal Services Environment

The Windows NT Server/Windows 2000 Server operating environment has specific requirements for hosting MS-DOS®-based and 16-bit Windows-based applications. These requirements also apply to a Terminal Services environment. Any MS-DOS-based or 16-bit Windows-based application that does not run under Windows NT Server/Windows 2000 Server will not run under Terminal Services either. Terminal Services is, however, more sensitive to ill-behaved legacy applications than the traditional Windows NT Server/Windows 2000 Server because a single ill-behaved application can affect all of the users on the Terminal Services system.

Predicting which legacy applications will work well in a Terminal Services environment and which will not is difficult. In most cases, the only real way to determine a specific application's feasibility is to test the application in a Terminal Services environment. However, there are some application behaviors and origins that typically create problems in a Terminal Services environment:

  • MS-DOS-based applications that cycle on device input. MS-DOS-based applications that tightly loop for keyboard input, mouse activity, or other device input operations are often too CPU-bound to run effectively in a Terminal Services environment.
  • FoxPro® for MS-DOS-based applications. These applications often do not run well in a Terminal Services environment because they tend to be CPU interrupt-intensive and drain processor resources away from other user sessions.
  • MS-DOS-based print applications. Many MS-DOS-based applications use print techniques that are not compatible with a Terminal Services environment. However, 16-bit Windows-based applications that use the standard Windows printing functions work correctly.
  • MS-DOS and 16-bit Windows-based applications that internally mount NetWare drives. Programmatic NetWare drive mapping operations do not work under Terminal Services. In contrast, drive mapping using UNC names works correctly.
  • 16-bit Windows applications that directly access .ini files. Older Windows applications that directly access .ini files instead of using the standard functions might not work if multiple users simultaneously access an .ini file. Terminal Services handles the standard functions properly for a multi-user environment.


About the Terminal Services Advanced Client

With the release of the Terminal Services Advanced Client (TSAC) as a ValueAdd component on Microsoft® Windows® 2000 Server, Service Pack 1, Terminal Services technology is extended to the Web. The Terminal Services client-side application only needs Microsoft Internet Explorer, a connection to the World Wide Web, and appropriate access rights to use TSAC functionality.

For more information about implementing and using the TSAC, including redistribution, refer the TSAC Frequently Asked Questions web page.

Download the TSAC control from the TSAC web package dowload page, or refer to the main TSAC web page

The following topics are discussed in this section:

  • Implementing Scriptable Virtual Channels Using the Terminal Services Advanced Client
  • Embedding the ActiveX Control in a Web Page
  • Accessing Restricted Security Zones
  • Downloading and Using the ActiveX Client Control
  • Disabling Terminal Service Features
  • Sample Web Pages Included with the Terminal Services Advanced Client
  • Using the ActiveX Client Control with Virtual Channels
  • Terminal Services ActiveX Client Control Interfaces and Methods


Implementing Scriptable Virtual Channels Using the Terminal Services Advanced Client

Prior to the release of the Terminal Services Advanced Client, implementing virtual channel applications on the client side required developers to create and register a client Dynamic Link Library (DLL). This DLL was loaded into memory on the client computer at the time the Terminal Services client program was run. This method is still supported, and instructions for installing and registering the virtual channel client DLL are provided in the documentation included with the TSAC. However, a much simpler and more efficient method exists. With the TSAC, all client-side virtual channel operations can be scripted, considerably reducing the administrative overhead for deployment.

The following procedure outlines the steps for implementing scriptable virtual channels with the TSAC. The examples were written in Microsoft® Visual Basic® Scripting Edition and assume that the Terminal Services Microsoft ActiveX® Client Control is named "MsTsc".

To create and deploy scriptable virtual channels

  1. Deploy the server side of the application and make sure it is running on the Terminal Services server. For information about deploying virtual channels applications on the server, refer to Virtual Channel Server Application.
  2. In your client script, call IMsTscAx::CreateVirtualChannel, passing a string that contains a comma-separated list of virtual channel names.

    For example:

    MsTsc.CreateVirtualChannels("mychan1,mychan2")

    Refer to Virtual Channel Client Registration for information on virtual channel naming restrictions.

  3. Call IMsTscax::Connect to create your Terminal Services connection.

    For example:

    MsTsc.connect
  4. Use the IMsTscAx::SendOnVirtualChannel method to send data to the server, passing a string that contains the virtual channel name and a second string containing the data to be passed.

    For example:

    MsTsc.SendOnVirtualChannel("mychan1","hello from the client")
  5. Receive data from the server on the IMsTscAxEvents::OnChannelReceivedData event.

    For example:

    Sub MsTsc.OnChannelReceivedData(chanName,data)
Msgbox("received data:" &data& "on virtual channel:" &chanName)
End sub


Embedding the ActiveX Control in a Web Page

You can embed the Terminal Services ActiveX Client Control in a Web page by inserting the HTML <OBJECT> tag, as in the following example.

<OBJECT language="vbscript" ID="MsTscControl">
    CLASSID="CLSID: 1fb464c8-09bb-4017-a2f5-eb742f04392f"
    WIDTH="400"
    HEIGHT="300"
    CODEBASE = "path\mstscax.cab#Version a, b, c, d,">
    <PARAM NAME  = property1 value = prroperty1value>
    <PARAM NAME = property2 value = property2value>
...
<\OBJECT>

The value that the WIDTH keyword is set to is the width, in pixels, of the Terminal Services session displayed on the Web page. The value that the HEIGHT keyword is set to is the height, in pixels, of the Terminal Services session. The value that the CODEBASE keyword is set to is the location of the file containing the TSAC code. The name of this file is Mstscax.cab, and it's located in the directory you installed the ActiveX Client Control and sample pages in. The default value of this keyword is C:\Inetpub\Wwwroot\Tsweb. The value the PARAMNAME keyword is set to is one or more of the parameters supported in Msrdp.ocx.

Note that the ActiveX Client Control Object parameters are not listed in this document. To view them, open Msrdp.ocx in a tool such as Oleview.exe or the Visual Basic Object Browser. Msrdp.ocx is located in Mstscax.cab. Refer to the implementation of the OBJECT tag in the sample connection page (Connect.asp) for examples of some common parameters.


Accessing Restricted Security Zones

For security reasons, some properties of the Terminal Services ActiveX Client Control object are restricted to specific Internet Explorer security zones. This means that, when a user browsing the Web accesses the page and the page is in a higher security zone than the computer they are browsing the Web with, these properties are disabled. These restricted TSAC properties are contained in the IMsTscSecuredSettings interface and are available in the following Internet Explorer security zones:

  • My Computer
  • Local Intranet
  • Trusted Sites

They are disabled in these zones:

  • Internet
  • Restricted Sites

If you call these restricted properties within your Terminal Services Web application, you should call IMsTscAx::get_SecuredSettings and IMsTscAx::get_SecuredSettingsEnabled to access the Secured Settings properties:

The properties the IMsTscSecuredSettings interface accesses are the following:

  • StartProgram This property specifies the program that will be started upon connection.
  • WorkDir The property specifies the working directory of the program specified in StartProgram.
  • FullScreen The property specifies whether the state of the control upon connection will be in full-screen or windowed mode. If the value of this property is TRUE, the connection will be opened in full-screen mode. Although the use of the FullScreen property is restricted to the Internet Explorer security zones listed earlier, a user can always change to full-screen mode after connection by pressing CTRL+ALT+BREAK.

The following script launches Microsoft Notepad upon connection. Run this script before calling the IMsTscAx::Connect method.

if MsTsc.SecuredSettingsEnabled then
    MsTsc.SecuredSettings.StartProgram = "notepad.exe"
else
    msgbox "Cannot access secured setting (startprogram) in the current browser zone"
end if

If the Terminal Services control is not hosted in a web browser — for example, if it is hosted in a Visual Basic application — then the IMsTscSecuredSettings interface is always available.


Downloading and Using the ActiveX Client Control

When a Web surfer accesses a Web page that contains the embedded Terminal Services ActiveX Client Control, the following happens:

  1. If necessary, Internet Explorer version 4.0 or later initiates a download of the .cab file pointed to by the CODEBASE parameter of the OBJECT tag. This happens under the following conditions:
    • The computer that accessed the Web page doesn't have an installation of the full TSAC with Web support.
    • The installed version of the .cab file on the client computer is older than the version on the Web page.
  2. After downloading the .cab file, Internet Explorer decompresses it and installs the ActiveX Client Control in its default location for downloaded controls on the target computer.
  3. The TSAC opens in the Web page. The Windows logon screen appears in a configuration depending on the parameters passed and the settings of the Terminal Services server to which you are trying to connect.


Disabling Terminal Service Features

For enhanced security, you might choose to disable Terminal Services features such as clipboard redirection and printer redirection for clients that connect to Terminal Services servers using the ActiveX Client Control.

To disable Terminal Services features

  1. Edit the registry of the client computer and add the following keys:
    • HKLM\Software\Microsoft\Terminal Server\DisableClipRedirection
    • HKLM\Software\Microsoft\Terminal Server\DisablePrinterRedirection
  2. Set the value of both keys to DWORD 1.


Sample Web Pages Included With the Terminal Services Advanced Client

When you install the ActiveX Client Control component of the TSAC, three sample Web pages are placed in the directory where TSAC is installed. These pages can be modified or used as they are.

The sample Web pages should be installed on a Web server running Windows NT 4.0 Server or later and Internet Information Server 4.0 or later. Also, the browser on the client computer should be Internet Explorer version 4.0 or later.

The names of the sample pages included with the TSAC are the following:

  • Default.htm
  • Connect.asp
  • ManyServers.htm


Default.htm

Default.htm is a default logon page that collects Terminal Services server connection information from the user. This page contains a required field, into which the user specifies the name of the Terminal Services server to be connected to, and optional fields for screen size and user logon information (user name and domain). Along with Connect.asp it collects user data and passes it to the ActiveX Client Control (Msrdp.ocx) to initiate a Terminal Services server session. The steps of the process are the following:

  1. The user enters the name of the Terminal Services server in the appropriate field.
    • The user may also specify a screen size for the connection. If no screen size is specified, the session opens in full-screen mode if the user is in a trusted security zone.
    • The user may also supply automatic logon information (user name, domain) for the Terminal server session.
  2. When the user clicks the Connect button, Default.htm constructs a URL that it passes to Connect.asp. This URL contains the user-supplied information as parameters.
  3. If necessary, Internet Explorer downloads the .cab file containing the ActiveX control and installs it on the user's computer.

The Terminal Services server session opens either in window or full screen mode.

For security reasons, some options that are available in the Terminal Services Connection Manager are restricted in the ActiveX Client Control to certain Internet Explorer security zones. Refer to Accessing Restricted Security Zones for more information.

The console appears at the specified size in the browser window or, if the session opens in the default full-screen mode, the browser controls and borders disappear and the Terminal Services console expands to the size of the user's screen. As with the full TSAC, the user can toggle between full screen and window mode by pressing CTRL+ALT+BREAK.


Connect.asp

Connect.asp is the page that contains the ActiveX Client Control, which hosts the session on the Terminal Services server. By design, Connect.asp does not run standalone. It must be called with parameters, such as those passed by Default.htm. When the user supplies connection information in Default.htm and then clicks the Connect button, the user-supplied information is embedded in a URL, such as the following:

http://MyWebServer/tsweb/connect.asp?Server=MyTSServer&rW=800&rH=600&

When this page opens for the first time in Internet Explorer, a dialog box appears giving the user the option of downloading the Msrdp.ocx ActiveX control. This occurs only under the following conditions:

  • The computer that accessed the Web page does not have the full TSAC with Web support installed.
  • The installed version of the .cab file on the client computer is older than the version on the Connect.asp page.

After users reach this page, they can create a shortcut to it by specifying it as a favorite URL in Internet Explorer. The Favorites shortcut retains all of the information the user previously supplied for the Terminal Services connection, making it easy to reconnect.

The size of the Terminal server console that appears in Connect.asp is the size that the user specified in Default.htm. To change the screen size, the user must disconnect from the Terminal Services session, return to Default.htm and edit the connection information. If no screen size was specified, the console opens in the browser window in the default full-screen mode. At this resolution, the Internet Explorer toolbars and window frames disappear, and the Terminal Services server console expands to match the full dimensions of the user's screen. As with the standard Terminal Services client, the user can toggle between full-screen and window mode by pressing CTRL+ALT+BREAK.


Manyservers.htm

Manyservers.htm is a page that hosts four Terminal Server connections in a single page. It allows a server administrator to manage many servers by displaying all of the server consoles in a single screen. A server administrator could customize this page to make it even more useful. For instance, an administrator could use DHTML or page redirection to start new connections after an interval.

Connections on this page are not made until the user clicks on the console. If the user does not click on the displayed console after a specified period of time the session times out. Two minutes is the default time period.

By default, the server name for all of the Terminal Services Web connections on this sample page can be set by using the edit control that appears at the top of the page when the page is opened in the browser. When the user types a server name in this box and then clicks the Connect button, all four instances of the ActiveX client control create a connection to the specified server.

This default behavior can be altered. For example, to specify a different server for each instance of the control, open the page in Notepad or in an HTML text editor and add the Server parameter to each of the embedded <OBJECT> tags, as follows:

<OBJECT language="vbscript" ID=" MsTscControl">
    CLASSID="CLSID: 1fb464c8-09bb-4017-a2f5-eb742f04392f "
    WIDTH="400"
    HEIGHT="300"
    CODEBASE = "path\mstscax.cab#Version a, b, c, d">
    <PARAM NAME  = server value = MyServer>
<\OBJECT>

Where MyServer is the name of the Terminal server to which you want the ActiveX Client Control to connect.

Refer to Accessing Restricted Security Zones for information on specifying a program to run upon connection.


Using the ActiveX Client Control with Virtual Channels

Virtual channels are software extensions that can be used to add functional enhancements to a Terminal Services application. Examples of functional enhancements might include: support for special types of hardware, audio, or other additions to the core functionality provided by the Terminal Services Remote Desktop Protocol (RDP). A virtual channel application has two parts, a client-side component and a server-side component. The server-side component is an executable program running on the Terminal Services server. The client-side component is a DLL that must be loaded into memory on the client computer when the Terminal Services client program is run.

If you have enabled a virtual channels application in your Terminal Services deployment, you can make this application available to client computers that access the Terminal Services server by means of the ActiveX Client Control.

To make a virtual channel application available

  1. Deploy the server-side component of the application and make sure it is running on the Terminal Services server. In the connection page of the Terminal Services Web application running on your Web server, access the PluginDlls property of the IMsTscAdvancedSettings interface to specify the name of your virtual channel DLL. If you have more than one plugin, specify a comma-delimited list of DLL names. For instance, if your virtual channel plug-in is named "MyPlugin.dll", use the following code:
    MsTsc.AdvancedSettings.PluginDlls = "myplugin.dll"

    Use the following code if you have two virtual channel DLLs. In this example, the DLL file names are "MyPlugin.dll" and "Vdriver.dll":

    MsTsc.AdvancedSettings.PluginDlls = "myplugin.dll,Vdriver.dll"

    For security reasons, the PluginDlls property only accepts a named list of virtual channel DLLs. The control returns an error if any form of file system or UNC path is specified.

  2. Ensure that the client-side component DLL of the virtual channels application is installed in the %windir%\system32 directory.

Note By default, the ActiveX Client Control loads virtual channel client DLLs from the %windir%\system32 directory. It is possible for an administrator to change this default client plugin DLL directory. To do so, edit the HKLM\Software\Microsoft\Terminal Server Client\vdllpath registry key on the client computer. This directory path cannot be specified in the UNC format.

For example, in the Connect.asp sample connection page provided with the TSAC, you can edit the window_onload() subroutine as follows:

<script language="vbscript" >
<!--
sub window_onLoad()
MsTsc.Server       =      "<%Response.WriteRequest.QueryString("Server")%>"
MsTsc.Domain       =      "<%Response.WriteRequest.QueryString("Domain")%>"
MsTsc.UserName     =      "<%Response.WriteRequest.QueryString("UserName")%>"
MsTsc.AdvancedSettings.PluginDlls="MyPlugin.dll"
MsTsc.Connect()
end sub
-->
</script>


Terminal Services ActiveX Client Control Interfaces and Methods

The Terminal Services ActiveX Client Control contains the following scriptable interfaces.

  • IMsTscAdvancedSettings Interface
  • IMsTscAx Interface
  • IMsTscAxEvents Interface
  • IMsTscSecuredSettings Interface

In addition, the terminal services ActiveX control includes one interface — IMsTscNonScriptable — that can only be accessed directly through the vtable.


IMsTscAdvancedSettings Interface

The following methods are included in the IMsTscAdvancedSettings interface.

  • put_Compress
  • get_Compress
  • put_BitmapPeristence
  • get_BitmapPeristence
  • put_PluginDlls
  • put_ContainerHandledFullScreen
  • get_ContainerHandledFullScreen
  • put_DisableRdpdr
  • get_DisableRdpdr
  • put_IconFile
  • put_IconIndex


IMsTscAdvancedSettings::get_BitmapPeristence

Retrieves the value of the BitmapPeristence property, which determines whether bitmap caching is enabled or disabled. Note the misspelling of the method and its parameter in the released version of the control.

HRESULT get_BitmapPeristence (
  long* pBitmapPeristence
);

Parameters

pBitmapPeristence
[out] Receives the value of the BitmapPeristence property. The value is 1 if the property is enabled, and 0 if it is disabled.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::put_BitmapPeristence


IMsTscAdvancedSettings::get_Compress

Retrieves the value of the Compression property, which determines whether compression is enabled.

HRESULT get_Compress (
  long* pCompress
);

Parameters

pCompress
[out] Receives the value of the Compression property. The value is 1 if compression is enabled, and 0 otherwise.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::put_Compress


IMsTscAdvancedSettings::get_ContainerHandledFullScreen

Retrieves the value of the ContainerHandledFullScreen property, which determines whether container-handled, full-screen mode is enabled or disabled.

HRESULT get_ContainerHandledFullScreen (
  BOOL* pContainerHandledFullScreen
);

Parameters

pContainerHandledFullScreen
[out] Receives the value of the ContainerHandledFullScreen mode property. The value is 1 if the mode is enabled, and 0 otherwise.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::put_ContainerHandledFullScreen


IMsTscAdvancedSettings::get_DisableRdpdr

Retrieves the value of the DisableRdpdr property, which determines whether printer and clipboard redirection is enabled or disabled.

HRESULT get_DisableRdpdr (
  BOOL* pDisableRdpdr
);

Parameters

pDisableRdpdr
[in] Receives the value of the DisableRdpdr property. The value is 1 if the DisableRdpdr property is enabled, and 0 otherwise.

Return Value

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::put_DisableRdpdr


IMsTscAdvancedSettings::put_BitmapPeristence

Sets the value of the BitmapPeristence property, which enables or disables bitmap caching. Note the misspelling of the method and its parameter in the released version of the control.

HRESULT put_BitmapPeristence (
  long bitmapPeristence
);

Parameters

bitmapPeristence
[in] The value the BitmapPeristence property is to be set to. Bitmap caching is disabled if set to 0, and it is enabled if set to any other value.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::get_BitmapPeristence


IMsTscAdvancedSettings::put_Compress

Sets the value of the Compression property, which enables or disables compression.

HRESULT put_Compress (
  long compress
);

Parameters

compress
[in] The value the Compression property is to be set to. Compression is disabled if set to 0 and enabled if set to any other value.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::get_Compress


IMsTscAdvancedSettings::put_ContainerHandledFullScreen

Sets the ContainerHandledFullScreen property, which determines whether the container-handled full screen mode is enabled or disabled.

HRESULT put_ContainerHandledFullScreen (
  BOOL containerHandledFullScreen
);

Parameters

containerHandledFullScreen
[in] The value this method sets the ContainerHandledFullScreen property to. If the value is TRUE, the container-handled full screen mode is enabled, and is disabled if set to any other value.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

When this mode is enabled, the current container processes the switch into and out of FullScreen mode. This method should be used only if the current container needs extensive control over FullScreen mode behavior. When this property is set, the control does not enter or leave full-screen mode in response to the full-screen mode shortcut key combination (CTRL+ALT+BREAK); instead, the OnRequestGoFullScreen and OnRequestLeaveFullScreen events are called. See the IMsTscAxEvents interface for more information about these events.

Most container applications will not need to use container-handled full screen mode.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::get_ContainerHandledFullScreen


IMsTscAdvancedSettings::put_DisableRdpdr

Sets the value of the DisableRdpdr property, which enables or disables the internal client-side component that controls printer and clipboard redirection.

HRESULT put_DisableRdpdr (
  BOOL disableRdpdr
);

Parameters

disableRdpdr
[in] The value this method sets the DisableRdpdr property to. The value is TRUE when redirection is disabled, and FALSE when redirection is enabled.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

TSAC printer and clipboard redirection is a built in component of the ActiveX control. This component was located in Rdpdr.dll for the Windows 2000 version of the TSAC client.

This property should also be used if you are loading an alternate Rdpdr.dll file with functionality different from the default version. Refer to IMsTscAdvancedSettings::put_PluginDlls and Using the ActiveX Client Control With Virtual Channels for more information on loading virtual channel client DLLs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings::get_DisableRdpdr


IMsTscAdvancedSettings::put_IconFile

Sets the value of the IconFile property. The value of this property specifies the file containing icon data that will be accessed when displaying the client in full-screen mode.

HRESULT put_IconFile (
  BSTR IconFile
);

Parameters

IconFile
[in] Fully qualified path of an IconFile file or to a file containing icon data, such as a DLL file.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The file extension of an IconFile file is ".ico".

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAdvancedSettings::put_PluginDlls

Sets the value of the PluginDlls property. The value of the property specifies the names of virtual channel client DLLs to be loaded. Virtual channel client DLLs are also referred to as plugin DLLs.

HRESULT put_PluginDlls (
  BSTR pluginList
);

Parameters

pluginList
[in] The value this method sets the PluginDlls property to. This is a comma-separated list of the names of the virtual channel client DLLs to be loaded.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

For security reasons, if the control is hosted in a web page the PluginDlls property only accepts a named list of virtual channel client DLLs. The control returns an error if a filesystem or UNC path is specified.

Virtual channel client DLLs that will be accessed from a Web page must be installed in the \winnt\system32 directory, as the TSAC control will only access DLL files in that location. If the control is not hosted in a Web page, this security restriction does not exist and full paths may be used to access and load virtual channel client DLLs located anywhere on the filesystem.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAdvancedSettings::put_IconIndex

Sets the value of the IconIndex property, which specifies the index of the icon within the current IconFile file. An IconFile file contains icon data. Refer to IMsTscAdvancedSettings::put_IconFile for more information on icon files and indices.

HRESULT put_IconIndex (
  LONG IconIndex
);

Parameters

IconIndex
[in] Specifies the index of an icon within the current IconFile file.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx Interface

The IMsTscAx interface contains the following methods:

  • get_AdvancedSettings
  • get_CipherStrength
  • get_Connected
  • get_ConnectingText
  • get_DesktopHeight
  • get_DesktopWidth
  • get_DisconnectedText
  • get_Domain
  • get_HorizontalScrollBarVisible
  • get_SecuredSettings
  • get_SecuredSettingsEnabled
  • get_Server
  • put_ConnectingText
  • put_DesktopHeight
  • put_DesktopWidth
  • put_Domain
  • put_DisconnectedText
  • put_FullScreenTitle
  • put_StartConnected
  • put_UserName
  • Connect
  • Disconnect
  • CreateVirtualChannel
  • SendOnVirtualChannel


IMsTscAx::get_AdvancedSettings

Retrieves an instance of the IMsTscAdvancedSettings interface.

HRESULT get_AdvancedSettings (
  IMsTscAdvancedSettings** ppAdvancedSettings
);

Parameters

ppAdvancedSettings
[out] Address of the current control's IMsTscAdvancedSettings interface.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAdvancedSettings


IMsTscAx::get_CipherStrength

Retrieves the value of the CipherStrength property, which specifies the maximum encryption strength of the current control.

HRESULT get_CipherStrength(
  LONG* pCipherStrength
);

Parameters

pCipherStrength
[out] The value of the CipherStrength property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

For the TSAC, the cipher strength is always 128 because the TSAC control supports encryption up to and including 128 bits. The 128-bit control can still connect to 56 bit encryption Terminal Service servers.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::get_Connected

Retrieves the value of the Connected property, which specifies the connection state of the current control.

HRESULT get_Connected(
  short* pConnected
);

Parameters

pConnected
[out] The value of the Connected property. The value of this parameter is 1 if the control is in the connected state, or 0 otherwise.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The preferred way to determine the control's connection state is to respond to the connection events in IMsTscAxEvents.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAx::get_ConnectingText

Retrieves the value of the ConnectingText property, which specifies the text that is displayed when the control enters the connected state.

HRESULT get_ConnectingText(
  BSTR* pConnectingText
);

Parameters

pConnectingText
[out] The value of the ConnectingText property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::put_ConnectingText


IMsTscAx::get_DesktopHeight

Retrieves the value of the DesktopHeight property, which specifies the height of the current remote desktop in pixels.

HRESULT get_DesktopHeight(
  LONG* pDesktopHeight
);

Parameters

pDesktopHeight
[out] The value of the DesktopHeight property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::put_DesktopHeight


IMsTscAx::get_DesktopWidth

Retrieves the value of the DesktopWidth property, which is the current remote desktop width in pixels.

HRESULT get_DesktopWidth(
  LONG* pDesktopWidth
);

Parameters

pDesktopWidth
[out] The value of the DesktopWidth property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::put_DesktopWidth


IMsTscAx::get_DisconnectedText

Retrieves the value of the DisconnectedText property, which specifies the text that is displayed when the current control enters the disconnected state.

HRESULT get_DisconnectedText(
  BSTR* pDisconnectedText
);

Parameters

pDisconnectedText
[in] The value of the DisconnectedText property. The default value of this property is an zero-length string.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::put_DisconnectedText


IMsTscAx::get_Domain

Retrieves the value of the Domain property, which specifies the domain the current control is connected to.

HRESULT get_Domain(
  BSTR* pDomain
);

Parameters

pDomain
[out] The value of the Domain property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::put_Domain


IMsTscAx::get_HorizontalScrollBarVisible

Retrieves a Boolean value that indicates whether or not the control has displayed a horizontal scroll bar.

HRESULT get_HorizontalScrollBarVisible(
  BOOL* pSBVisible
);

Parameters

pSBVisible
[out] Specifies whether the horizontal bar is visible in the current control. The value of this parameter is TRUE if the horizontal scroll bar is visible, and FALSE otherwise.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The control automatically displays a horizontal scroll bar if the width of the control is less than the desktop width.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::get_SecuredSettings

Retrieves the address of the current control's IMsTscSecuredSettings interface.

HRESULT get_SecuredSettings (
  IMsTscSecuredSettings** ppSecuredSettings
);

Parameters

ppSecuredSettings
[out] Address of the current control's IMsTscSecuredSettings interface.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

If the control is hosted in a Web page and the current Internet Explorer security zone does not permit the retrieval of the interface address, this method returns E_FAIL.

Refer to IMsTscAx::get_SecuredSettingsEnabled for restrictions on the availability of the IMsTscSecuredSettings interface.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings


IMsTscAx::get_SecuredSettingsEnabled

Retrieves a value indicating whether the IMsTscSecuredSettings interface is available—that is, if the Web page containing the control is currently in one of the allowed Internet Explorer security zones.

HRESULT get_SecuredSettingsEnabled(
  BOOL* pSecuredSettingsEnabled
);

Parameters

pSecuredSettingsEnabled
[in] The indication of whether the IMscSecuredSettings interface is available. The value of this parameter is TRUE if it is available, and FALSE if it is not.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Use this method to query whether or not the IMscSecuredSettings interface is available before calling the IMsTscAx::get_SecuredSettings method.

Refer to Accessing Restricted Security Zones a list of restricted Security Zones.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings


IMsTscAx::get_Server

Retrieves the value of the Server property, which specifies the Terminal Services server the current control is connected to.

HRESULT get_Server(
  BSTR* pServer
);

Parameters

pServer
[out] The value of the Server property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::get_StartConnected

Retrieves the value of the StartConnected property, which specifies whether the connection process of the current control has started.

HRESULT get_StartConnected(
  BOOL* pStartConnected
);

Parameters

pStartConnected
[out] The value of the StartConnected property. The default value of this parameter is FALSE. The value of this parameter is TRUE if the connection process has started, and FALSE otherwise.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::get_UserName

Retrieves the value of the Username property, which specifies the name of the user initiating the control's connection.

HRESULT get_UserName(
  BSTR* pUserName
);

Parameters

pUserName
[out] The value of the UserName property.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::get_Version

Retrieves the version number of the current control.

HRESULT get_Version(
  BSTR* pVersion
);

Parameters

pVersion
[out] The version number of the current control.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The pVersion parameter buffer must be deallocated after use by calling SysFreeString.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::get_VerticalScrollBarVisible

Retrieves a value that indicates whether the control displays a vertical scroll bar.

HRESULT get_VerticalScrollBarVisible(
  BOOL* pSBVisible
);

Parameters

pSBVisible
[out] The value indicating whether the veritical scroll bar is visible. The value of this parameter is TRUE if the vertical scroll bar is visible, and FALSE if it is not.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The control automatically displays a vertical scroll bar if the height of the current control is less than the height of the desktop.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::put_ConnectingText

Sets the value of the ConnectingText property, which is text that appears centered in the control while the control is connecting.

HRESULT put_ConnectingText(
  BSTR ConnectingText
);

Parameters

ConnectingText
[out] The value the ConnectingText property is to be set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

An example of connection text is "Connecting to server …".

Setting the ConnectingText property is optional. If it is not set, the control appears blank before a connection is established.

This property can be set only if the control is not in the connected state. It returns E_FAIL if it is called when the control is connected. You can check if the control is connected by calling IMsTscAx::get_Connected.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_ConnectingText


IMsTscAx::put_DisconnectedText

Sets the value of the DisconnectedText property, which is text that appears centered in the control before a connection is terminated.

HRESULT put_DisconnectedText(
  BSTR DisconnectedText
);

Parameters

DisconnectedText
[in] The value the DisconnectText property is to be set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Setting the DisconnectedText property is optional. If it is not specified the control appears blank before a connection is established.

This property can be set only if the control is not in the connected state. The method returns E_FAIL if it is called after the control is connected. You can check if the control is connected by calling the IMsTscAx::get_Connected method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_DisconnectedText


IMsTscAx::put_DesktopHeight

Sets the value of the DesktopHeight property, which is the current control's initial remote desktop height in pixels.

HRESULT put_DesktopHeight(
  LONG desktopHeight
);

Parameters

DesktopHeight
[in] The value the DesktopHeight property is to be set to. The minimum value is 200 pixels, and the maximum value is 1200 pixels.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Setting the DesktopHeight property is optional, but it must be set before the Connect method is called. If a desktop height is not specified, the desktop height is set to the height of the control.

After a connection is established, any changes to the control's height do not change the height of the remote desktop. Instead, the control displays scroll bars or centers the remote desktop as appropriate.

This property can be set only if the control is not in the connected state. It returns E_FAIL if it is called when the control is connected. You can check for the connected state by using the IMsTscAx::get_Connected method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_DesktopHeight


IMsTscAx::put_DesktopWidth

Sets the value of the DesktopWidth property, which specifies the current control's width, in pixels, on the initial remote desktop.

HRESULT put_DesktopWidth(
  LONG desktopWidth
);

Parameters

desktopWidth
[in] The value the DesktopWidth property is set to. The minimum value is 200 pixels, and the maximum value is 1,600 pixels. The value must be a multiple of 4 pixels. If the value is not a multiple of 4 pixels, the control automatically sets the desktop width to the nearest multiple of 4 pixels.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Setting the DesktopWidth property is optional, but it must be set before the Connect method is called. If a desktop width is not specified, the desktop width is set to the width of the control. After a connection is established, any changes to the control's width do not change the width of the remote desktop. Instead, the control brings up scroll bars or centers the remote desktop, as appropriate.

This property can be set only if the control is not in the connected state. It returns E_FAIL if it is called when the control is connected. You can check for the connected state by using the IMsTscAx::get_Connected method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_DesktopWidth


IMsTscAx::put_Domain

Sets the value of the Domain property, which specifies the domain to which the current user logs on.

HRESULT put_Domain(
  BSTR Domain
);

Parameters

Domain
[in] The value the Domain property is set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Setting the Domain property is optional. If it is not set, the user can choose a domain when the Windows Logon dialog box appears during the connection.

This property can be set only if the control is not in the connected state. It returns E_FAIL if it is called when the control is connected. You can check for the connected state by calling the IMsTscAx::get_Connected method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_Domain


IMsTscAx::put_FullScreenTitle

Sets the value of the FullScreenTitle property, which specifies the window title displayed when the control is in FullScreen mode.

HRESULT put_FullScreenTitle(
  BSTR fullScreenTitle
);

Parameters

fullScreenTitle
[in] The value the FullScreenTitle property is set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

This property is used to set the title of the control's window when the connection is opened in full-screen mode. Do not use this property for container-handled full-screen mode. When the IMsTscAdvancedSettings::put_ContainerHandledFullScreen method is called, the container window displays the window title.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::put_Server

Sets the value of the Server property, which is the name of the server to be connected to.

HRESULT put_Server(
  BSTR Server
);

Parameters

Server
[in] The value the Server property is set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The value of this property can be a DNS name or IP address.

This property must be set before the IMsTscAx::Connect method is called. It is the only property that must be set before connecting.

This property can be set only if the control is not in the connected state. This property returns E_FAIL if it is called when the control is connected. You can check for the connected state by using the IMsTscAx::get_Connected method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_Server


IMsTscAx::put_StartConnected

Sets the value of the StartConnected property, which specifies whether the control will establish the Terminal Services server connection immediately upon startup.

HRESULT put_StartConnected(
  BOOL startConnected
);

Parameters

StartConnected
[in] The value of the StartConnected property. The value is TRUE if the control will connect immediately on startup, or FALSE if the control will not.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

This property is most useful when the control properties are set in the parameter list of an <OBJECT> tag, rather than through script calls.

This property can be used only if the server name is also specified using the server property. This parameter has to be set before the control starts up—for example, by including it in the parameter list of an <OBJECT> tag when using the control from a Web page.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_StartConnected


IMsTscAx::put_UserName

Sets the value of the UserName property, which specifies the user name logon credential.

HRESULT put_UserName(
  BSTR UserName
);

Parameters

UserName
[in] The value the UserName property is set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Setting the UserName property is optional. If it is not specified, the user can provide a username when the Windows Logon dialog box appears during connection.

This property can be set only if the control is not in the connected state. It returns E_FAIL if it is called when the control is connected. You can check for the connected state by calling the IMsTscAx::get_Connected method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::get_UserName


IMsTscAx::Connect

Initiates a connection using the properties currently set on the control. .

HRESULT Connect (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

The only required property is the server name. Refer to IMsTscAx::put_Server.

The control connects asynchronously, so a return from a Connect call indicates only that the connection has been initiated successfully, not that it has been completed. You should respond to events on the IMsTscAxEvents interface to determine when the control has successfully connected (or has been disconnected.

This method returns E_FAIL if it is called while the control is already connected or in the connecting state.

After Connect has been called, most of the control properties can no longer be set until the control is back in the disconnected state.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::Disconnect


IMsTscAx::Disconnect

Disconnects the active connection

HRESULT Disconnect (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

This method returns a failure error value if it is called when the control is not connected.

It is also possible to disconnect the control by closing its main window. For example, if the control is hosted in a Web page, it is not necessary to call this method before leaving the page; the closing of the control triggers a disconnection.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAx::Connect


IMsTscAx::CreateVirtualChannel

Creates a client-side virtual channel object for each specified virtual channel name.

HRESULT CreateVirtualChannels (
  BSTR channelNameList
);

Parameters

channelNameList
[in] A comma-separated list of valid virtual channel names.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

This method should be called before IMsTscAx::Connect.

Refer to Virtual Channel Client Registration for information about virtual channel naming restrictions.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscAx::SendOnVirtualChannel

Sends data to the Terminal Services server over a virtual channel that has been previously created with the IMsTscAx::CreateVirtualChannel method.

HRESULT SendOnVirtualChannel (
  BSTR channelName,
  BSTR dataToSend
);

Parameters

channelName
[in] The virtual channel name that was specified in the call to IMsTscAx::CreateVirtualChannel.
DataToSend
[in] The data in BSTR form to be sent over the virtual channel. This data is not restricted to only null-terminated strings.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Virtual Channel Client Registration for information about virtual channel naming restrictions.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods


IMsTscSecuredSettings Interface

The following methods are included in the IMsTscSecuredSettings interface:

  • get_FullScreen
  • get_StartProgram
  • get_WorkDir
  • put_FullScreen
  • put_StartProgram
  • put_WorkDir


IMsTscSecuredSettings::get_FullScreen

Retrieves the value of the FullScreen property, which specifies the full screen state of the client control.

HRESULT get_FullScreen(
  BOOL* pFullScreen
);

Parameters

pFullScreen
[out] The value the FullScreen property is set to. The value is TRUE if the control is in full-screen mode, or FALSE if it is not.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Accessing Restricted Security Zones for information about this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings::put_FullScreen


IMsTscSecuredSettings::get_StartProgram

Retrieves the value of the StartProgram property, which specifies the program to be started on the remote server upon connection.

HRESULT get_StartProgram(
  BSTR* pStartProgram
);

Parameters

pStartProgram
[out] The value the StartProgram property is set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Accessing Restricted Security Zones for information about this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings::put_StartProgram


IMsTscSecuredSettings::get_WorkDir

Retrieves the WorkDir property, which specifies the working directory of the start program.

HRESULT get_WorkDir(
  BSTR* pWorkDir
);

Parameters

pWorkDir
[out] The value the WorkDir property is set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Accessing Restricted Security Zones for information about this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings::put_WorkDir


IMsTscSecuredSettings::put_FullScreen

Sets the value of the FullScreen property, which specifies whether the client control is in full-screen or windowed mode.

HRESULT put_FullScreen(
  BOOL FullScreen
);

Parameters

FullScreen
[in] The value the FullScreen property is to be set to. The value is TRUE if the control is in full-screen mode, and FALSE if it is in windowed mode.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Note that although the use of the FullScreen property is restricted to the allowed Internet Explorer security zones, a user can always change to full-screen mode after the connection has been established by pressing CTRL+ALT+BREAK.

Refer to Accessing Restricted Security Zones for information about this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings::get_FullScreen


IMsTscSecuredSettings::put_StartProgram

Sets the value of the StartProgram property, which specifies the program to be started on the Terminal Services server upon connection.

HRESULT put_StartProgram(
  BSTR startProgram
);

Parameters

startProgram
[in] The value the StartProgram property is to be set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Accessing Restricted Security Zones for information about this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings::get_StartProgram


IMsTscSecuredSettings::put_WorkDir

Sets the value of the WorkDir property, which specifies the current working directory of the start program specified by the value of the StartProgram property.

HRESULT put_WorkDir(
  BSTR workDir
);

Parameters

WorkDir
[in] The value the WorkDir property is to be set to.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Accessing Restricted Security Zones for information about this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscSecuredSettings::get_WorkDir


IMsTscAxEvents Interface

The following methods are included in the IMsTscAxEvents interface:

  • OnChannelReceivedData
  • OnConnected
  • OnConnecting
  • OnDisconnected
  • OnEnterFullScreenMode
  • OnFatalError
  • OnLeaveFullScreenMode
  • OnLoginComplete
  • OnRemoteDesktopSizeChange
  • OnRequestGoFullScreen
  • OnRequestLeaveFullScreen
  • OnWarning


IMsTscAxEvents::OnChannelReceivedData

Called when the client receives data on a scriptable virtual channel.

HRESULT OnChannelReceivedData(
  BSTR chanName,
  BSTR data
);

Parameters

chanName
[in] The name of the virtual channel on which data was received. This name matches one of the channels created by the call to IMsTscAx::CreateVirtualChannel.
data
[out] The data received on the scriptable virtual channel.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Refer to Implementing Scriptable Virtual Channels using the Terminal Services Advanced Client for more information about this event.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnConnected

Called when the client control is in the process of establishing a connection with a Terminal Services server.

HRESULT OnConnected (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Implement this method in your event sink to receive notification that the control has established a connection with a Terminal Services server.

Refer to the IMsTscAxEvents::OnLoginComplete event for more information on calling this method.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents.


IMsTscAxEvents::OnConnecting

Called when the client control begins connecting to a server in response to a call to IMsTscAx::Connect.

HRESULT OnConnecting (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Implement this method in your event sink to receive notification that the control has begun connecting.

Example

The following example illustrates how to handle this event with Visual Basic Scripting code. The assumption in this example is that your control object is named "MsTsc".

Sub MsTsc.OnConnecting()
    Msgbox("Connecting")
End sub

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnDisconnected

Called when the client control has been disconnected from the terminal server.

HRESULT OnDisconnected(
  long disconnectReason
);

Parameters

DisconnectReason
[in] Specifies the reason for the disconnection. The following is a list of error codes.
Value | Meaning
1 | Local disconnection. This is not an error code.
2 | Remote disconnection by user. This is not an error code.
3 | Remote disconnection by server. This is not an error code.
260 | DNS name lookup failure.
262 | Out of memory.
264 | Connection timed out.
516 | WinSock socket connect failure.
518 | Out of memory.
520 | Host not found error.
772 | WinSock send call failure.
774 | Out of memory.
776 | Invalid IP address specified.
1028 | WinSock recv call failure.
1030 | Invalid Security Data.
1032 | Internal error.
1286 | Invalid encryption method specified.
1288 | DNS lookup failed.
1540 | GetHostByName call failed.
1542 | Invalid server security data.
1544 | Internal timer error.
1796 | Timeout occurred.
1798 | Failed to unpack server certificate.
2052 | Bad IP address specified.
2054 | Internal security error.
2308 | Socket closed.
2310 | Internal security error.
2566 | Internal security error.
2822 | Encryption error.
3078 | Decryption error.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnEnterFullScreenMode

Called when the client enters full-screen mode. For example, this event is called when the user presses the full-screen mode shortcut key combination (CTRL + ALT + BREAK).

HRESULT OnEnterFullScreenMode (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnFatalError

Called when the client control encounters a fatal error.

HRESULT OnFatalError(
  long errorCode
);

Parameters

errorCode
[in] Indicates the error code.
Value | Meaning
0 | An unknown error has occurred.
1 | Internal error code 1.
2 | Out of memory.
3 | Window creation error.
4 | Internal error code 2.
5 | Internal error code 3. This is an invalid state.
100 | Winsock initialization error.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

In response to this event, the container displays an error message and shuts down.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnLeaveFullScreenMode

Called when the client leaves full-screen mode. For example, this event is called when the user presses the full-screen mode shortcut key combination (CTRL + ALT + BREAK).

HRESULT OnLeaveFullScreenMode(VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnLoginComplete

Called when the client control has successfully logged on to a terminal server, following the display of the Windows Logon dialog box.

HRESULT OnLoginComplete (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

Implement this method in your event sink to receive notification that the control has completed logon.

Example

The following example illustrates how to handle this event with Visual Basic Scripting code. The assumption in this example is that your control object is named "MsTsc".

Sub MsTsc.OnLoginComplete()
    Msgbox("Login has completed")
End sub

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnRemoteDesktopSizeChange

Called to indicate the size of the client control on the remote desktop has changed in response to a client control operation.

HRESULT OnRemoteDesktopSizeChange(
  long width,
  long height
);

Parameters

width
[in] Width, in pixels, of the resized remote desktop.
height
[in] Height, in pixels, of the resized remote desktop.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

This event allows the container to determine if it must resize itself in response to a client control operation, which could result in a larger viewable desktop size. Note that the control will automatically adjust scroll bars for the new session size.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnRequestGoFullScreen

Called when the client requests to switch to full-screen mode and the IMsTscAdvancedSettings::put_ContainerHandledFullScreen method is called.

HRESULT OnRequestGoFullScreen (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

In container-handled full-screen mode, the container should enter standard full-screen mode in response to this event.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnRequestLeaveFullScreen

Called when the client requests to leave full-screen mode and the IMsTscAdvancedSettings::put_ContainerHandledFullScreen method has been called.

HRESULT OnRequestLeaveFullScreen (VOID);

Parameters

This method has no parameters.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Remarks

In container-handled full-screen mode, the container should leave standard full-screen mode in response to this event.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


IMsTscAxEvents::OnWarning

Called when the client control encounters a non-fatal error condition.

HRESULT OnWarning(
  long warningCode
);

Parameters

warningCode
[in] The error code.
Value | Meaning
1 | Bitmap cache is corrupt.

Return Values

Return S_OK if successful.

Return a nonzero error code if an error occurs.

Requirements

Version: Requires TSAC control.

See Also

Terminal Services API Overview, Terminal Services ActiveX Client Control Interfaces and Methods, IMsTscAxEvents


Terminal Services Shortcut Keys

The following is a list of the Terminal Service Shortcut Keys.

Shortcut key | Description
ALT+PAGE UP | Switches between programs from left to right.
ALT+PAGE DOWN | Switches between programs for right to left.
ALT+INSERT | Cycles through the programs in the order they were started.
ALT+HOME | Displays the Start menu.
CTRL+ALT+BREAK | Switches the client between windowed and full screen mode.
CTRL+ALT+END | Brings up the Windows 2000 Security dialog box.
ALT+DELETE | Displays the Windows menu.
CTRL+ALT+MINUS SIGN (-) | Places a snapshot of the active window, within the client, on the Terminal server clipboard (provides the same functionality as pressing PRINT SCREEN on the local computer).
CTRL+ALT+PLUS SIGN (+) | Places a snapshot of the entire client windows area on the Terminal server clipboard (provides the same functionality as pressing ALT+PRINT SCREEN on the local computer).

Note that on an NEC98, the following shortcut keys are different:

  • CTRL+ALT+BREAK is replaced by F12.
  • CTRL+ALT+END is replaced by 15.


About the Terminal Services WMI Provider

The Terminal Services Advanced Client (TSAC) extends current Terminal Services functionality to Web pages. With TSAC, all client-side virtual channel operations can be initiated by a Microsoft® Visual Basic® script, considerably reducing the time necessary for deployment of Terminal Services clients.

The provider DLL is loaded by the Windows Management process (winmgmt.exe) when a client makes a request to the server. Administration is possible using the provider methods. The provider is registered as both an instance and a method provider.

The Terminal Services WMI provider has been implemented as a dynamic provider derived from the Win32_Service base class, inheriting all of its properties and methods, and an in-process dynamic link library.

  • Terminal Services WMI Provider Reference


Terminal Services WMI Provider Reference

The following topics are covered in this section.

  • Terminal Services WMI Provider Classes
  • Terminal Services WMI Provider Methods
  • Mapping of WTS API Functions to Terminal Services WMI Provider Methods
  • Terminal Services WMI Provider Error Codes


Terminal Services WMI Provider Classes

The Terminal Services WMI provider uses the following CIM classes:

  • Win32_Session
  • Win32_SystemSessions
  • Win32_Terminal
  • Win32_TerminalService
  • Win32_TerminalServiceSetting
  • Win32_TerminalServiceToSetting
  • Win32_TerminalTerminalSetting
  • Win32_TSAccount
  • Win32_TSClientSetting
  • Win32_TSEnvironmentSetting
  • Win32_TSGeneralSetting
  • Win32_TSLogonSetting
  • Win32_TSNetworkAdapterSetting
  • Win32_TSNetworkAdapterListSetting
  • Win32_TSPermissionsSetting
  • Win32_TSRemoteControlSetting
  • Win32_TSSessionDirectory
  • Win32_TSSessionDirectorySetting
  • Win32_TSSessionSetting


Win32_Session

The Win32_Session class represents the Terminal Services sessions on a Win32 system.

Class Win32_Session : CIM_LogicalElement
{
   uint32 SessionID;
   string ApplicationName;
   uint32 ConnectionState;
   string UserIDName;
   string Domain;
};

Properties

SessionID
Data type: uint32
Access type: Read-only

The unique identifier of the session.

ApplicationName
Data type: string
Access type: Read-only

The name of the startup application. This is the application executed immediately after the logon process is complete.

ConnectionState
Data type: uint32
Access type: Read-only

The connection state of the session.
Value | Meaning
Active | The session is active. It has been connected and data is being transferred between the server and client.
Connected | The session is connected from the server.
ConnectQuery | The session is in the process of connecting to the server.
Disconnected | This session is disconnected from the server.
Shadow | This session is shadowing another Terminal Services session. In this state, all actions performed by the shadowed session are observed by this session.
Idle | The session is idle. It has been connected but data is not currently being transferred between the server and client.
Listen | The session is waiting for a carrier.
Down | The session has detected a disconnection from the server.
Reset | The session is being reset.
Init | The session is being initialized.

UserIDName
Data type: string
Access type: Read-only

The unique identifier of the user initiating the session.

Domain
Data type: string
Access type: Read-only

The name of the domain to which the Terminal Services server belongs.

Methods

This following table lists the methods of Win32_Session.

Method | Description
Connect | Not currently implemented.
Disconnect | Disconnects the session, saves the state, and does not log off the user. Upon reconnection, the saved state is restored.
SendMessage | Sends the specified message text in the session.
Reset | The state is saved and the user is not logged off. Upon reconnection, the saved state is restored.
RemoteControl | Not currently implemented.
Logoff | Logs off the user. Upon reconnection, the saved state is not restored.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_SystemSessions

The Win32_SystemSessions class represents an association between an instantiation of the Win32_ComputerSystem class and a session running on the system specified by the Win32_ComputerSystem class..

Class Win32_SystemSessions : CIM_Component
{
   Win32_ComputerSystem * GroupComponent;
   Win32_Session * PartComponent;
};

Properties

GroupComponent
Data type: Win32_ComputerSystem
Access type: Read-only

Information regarding the computer system upon which the current session is running.

PartComponent
Data type: Win32_Session
Access type: Read-only

Information regarding the session running on the terminal.

Methods

This class has no methods.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_ComputerSystem, Win32_Session


Win32_Terminal

The Win32_Terminal class represents an association between a TerminalSetting and its configuration setting groups. Examples of these setting groups include General, Logon, Session, Environment, Remote Control, Client, Network Adapter, and Permission.

Class Win32_Terminal : Win32_Service
{
   string * TerminalName;
   uint32 fEnableTerminal;
};

Properties

TerminalName
Data type: uint32
Access type: Read-only

The name of the terminal.

fEnableTerminal
Data type: uint32
Access type: Read-only

Indicates whether the specified terminal is disabled or enabled.

Methods

This following table lists the methods of Win32_Terminal.

Method | Description
Enable | Disables and enables the terminal.
Rename | Renames the terminal.

Remarks

Win32_Terminal is associated with Win32_TerminalSetting as the Element property of the Win32_TerminalTerminalSetting association.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_Terminal, Win32_TerminalServiceSetting, Win32_TerminalTerminalSetting


Win32_TerminalService

The Win32_TerminalService class represents the Element property of the Win32_TerminalServiceToSetting association.

Class Win32_TerminalService : Win32_Service
{
   uint32 TotalSessions;
   uint32 DisconnectedSessions;
   uint32 EstimatedScreenCapacity;
   string ResourceConstraint;
};

Properties

TotalSessions
Data type: uint32
Access type: Read-only

The total number of sessions on the current server. This includes both connected and disconnected sessions.

DisconnectedSessions
Data type: uint32
Access type: Read-only

The number of disconnected sessions on the current server. These sessions may still be actively consuming server resources, however they currently have no network connection with a client.

EstimatedScreenCapacity
Data type: uint32
Access type: Read-only

The number of estimated additional sessions the current server can support based on available system resources.

ResourceConstraint
Data type: string
Access type: Read-only

The primary system resource constraint effecting the number of estimated additional sessions.
Value | Meaning
Paged Pool | The paged pool is the primary resource constraint.
Non-Paged Pool | The non-paged pool is the primary resource constraint.
System PTEs | Available system page table entries are the primary resource constraint.
Available Memory | Available memory is the primary resource constraint.

Methods

This class has no methods.

Remarks

Win32_TerminalServiceSetting is associated to Win32_TerminalService as the Setting property of the Win32_TerminalServiceToSetting association.

Win32_TSSessionDirectory is associated to Win32_TerminalService as the Setting property of the Win32_TSSessionDirectorySetting association.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_Service, Win32_TerminalServiceToSetting


Win32_TerminalServiceSetting

The Win32_TerminalServiceSetting class defines the configuration for the TerminalServerSetting property. This includes capabilities such as Terminal Server mode, Licensing, Active Desktop, Permissions Capability, Deletion of Temporary Folders, and Temporary Folders-Per-Session.

Class Win32_TerminalServiceSetting : CIM_Setting
{
   uint32 TerminalServerMode;
   uint32 LicensingType;
   uint32 ActiveDesktop;
   uint32 PermissionCompatibility;
   uint32 DeleteTemporaryFolders;
   uint32 UseTempFoldersPerSession;
   string Logons;
};

Properties

TerminalServerMode
Data type: uint32
Access type: Read-only

The Terminal Server operating mode of the Terminal Services service. This mode controls the licensing policies that are applicable as well as whether application-compatibility features are enabled.
Value | Meaning
Application Server | The server operates as an application server.
Remote Administration | The session is administered remotely.
Personal Terminal Server | The server operates as a Personal Terminal Services server.

LicensingType
Data type: uint32
Access type: Read-only

Selects the licensing type among the types available for the specified server mode.
Value | Meaning
None | No licensing regime is in effect.
Per Seat | A per-seat licensing regime is in effect.
Per User | A per-user licensing regime is in effect.
Concurrent | A concurrent licensing regime is in effect. The regime is supported in Windows 2000.
ICL | An Internet Connector Licensing (ICL) licensing regime is in effect. This regime is supported in Whistler.

ActiveDesktop
Data type: uint32
Access type: Read-Write

Indicates whether Active Desktop is allowed in each user session.
Value | Meaning
FALSE | Active Desktop is not allowed in each user session.
TRUE | Active Desktop is allowed in each user session.

PermissionCapatibility
Data type: uint32
Access type: Read-Write

Indicates compatibility with Windows NT 4.0 or Windows 2000.
Value | Meaning
NT4-TSE | Windows NT-style permissions are in effect.
Windows2000 | Windows 2000-style permission are in effect.

DeleteTemporaryFolders
Data type: uint32
Access type: Read-Write

Disables and enables deletion of temporary directories on exit.
Value | Meaning
FALSE | Deletion of temporary directories are disabled.
TRUE | Deletion of temporary directories are enabled.

UseTempFoldersPerSession
Data type: uint32
Access type: Read-Write

Specifies whether temporary directories are created and deleted on a per-session basis.
Value | Meaning
FALSE | Temporary directories are not created and deleted for each session. One is created for the first session and never deleted.
TRUE | Temporary directories are created and deleted for each session.

Logons
Data type: string
Access type: Read-Write

Indicates whether new sessions are allowed. This setting will not affect existing settings. This property is specific to Whistler.
Value | Meaning
Disabled | New sessions are not allowed.
Enabled | New sessions are allowed.

Methods

This following table lists the methods of Win32_TerminalServiceSetting.

Method | Description
ChangeMode | Configures the licensing type based on the Terminal Service server mode.

Remarks

Win32_TerminalServiceSetting is associated to Win32_TerminalService as the Setting property of the Win32_TerminalServiceToSetting association.

Win32_TerminalSetting is associated to Win32_Terminal as the Setting property of the Win32_TerminalTerminalSetting association.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods. Win32_TerminalServiceSetting, Win32_TerminalService, Win32_TerminalServiceToSetting, Win32_TerminalSetting, Win32_Terminal, Win32_TerminalTerminalSetting


Win32_TerminalServiceToSetting

The Win32_TerminalServiceToSetting class represents an association between a Win32_TerminalService and Win32_TerminalServiceSetting property that includes Terminal Server mode, Licensing, Active Desktop, Permissions Capability, Deletion of Temporary Folders and Temporary Folders-Per-Session.

Class Win32_TerminalServiceToSetting : CIM_Setting
{
   Win32_TerminalService * Element;
   Win32_TerminalServiceSetting * Setting;
};

Properties

Element
Data type: Win32_TerminalService
Access type: Read-only

Represents the instantiation of Win32_TerminalService that can be configured with the Settings member.

Setting
Data type: Win32_TerminalServiceSetting
Access type: Read-only

Represents the Terminal Service configuration settings that can be applied to the associated Terminal Services server.

Methods

This class has no methods.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_TerminalService, Win32_TerminalServiceSetting


Win32_TerminalTerminalSetting

The Win32_TerminalTerminalSetting represents an association between a terminal and its configuration settings.

Class Win32_TerminalTerminalSetting : CIM_Setting
{
   Win32_Terminal * Element;
   Win32_TerminalSetting * Setting;

};

Properties

Element
Data type: Win32_Terminal
Access type: Read-only

Represents the terminal that can be configured through the Setting member.

Setting
Data type: Win32_TerminalSetting
Access type: Read-only

Represents the settings that can be applied to the specified terminal.

Methods

This class has no methods.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider,Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_TSAccount

The Win32_TSAccount class represents an association between in instantiation of Win32_Terminal and its configuration settings.

Class Win32_TSAccount : Win32_Service
{
   string * AccountName;
   uint32 PermissionsAllowed;
   uint32 PermissionsDenied;
   uint32 AuditSuccess;
   uint32 AuditFail;
   string SID;
};

Properties

AccountName
Data type: string
Access type: Read-only

The current name of the account. The domain name is included.

PermissionsAllowed
Data type: uint32
Access type: Read-only

Specifies the Terminal Server-specific permissions allowed for the account. The value of this property is a bitmask, which can be set to one or more of the following values:
Value | Meaning
WINSTATION_QUERY | This account can query for the existence of sessions.
WINSTATION_SET | This account can set session properties.
WINSTATION_RESET | This account can reset session properties.
WINSTATION_VIRTUAL | This account is a virtual account.
WINSTATION_SHADOW | This account can shadow other sessions.
WINSTATION_LOGON | This account can log on a Terminal Services server.
WINSTATION_LOGOFF | This account can log off a Terminal Services server.
WINSTATION_MSG | This account can send messages to other sessions.
WINSTATION_CONNECT | This account can connect to a Terminal Services server.
WINSTATION_DISCONNECT | This account can disconnect from a Terminal Services server.

PermissionsDenied
Data type: uint32
Access type: Read-only

Specifies the Terminal Server-specific permissions disallowed for the account. The value of this property is a bitmask, which can be set to one or more of the values of the PermissionsAllowed property.

AuditSuccess
Data type: uint32
Access type: Read-only

Specifies the Terminal Server-specific permissions that are audited for a success condition. The value of this property is a bitmask, which can be set to one or more of the values of the PermissionsAllowed property.

AuditFail
Data type: uint32
Access type: Read-only

Specifies the Terminal Server-specific permissions that are audited for a failure condition. The value of this property is a bitmask, which can be set to one or more of the values of the PermissionsAllowed property.

SID
Data type: uint32
Access type: Read-only

Specified the security identifier (SID) of the account.

Methods

This following table lists the methods of Win32_TSAccount.

Method | Description
Delete | Deletes the specified user, group, or computer name.
ModifyAuditPermissions | Changes the granularity of the set of audit permissions of the specified account.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_TSClientSetting

The Win32_TSClientSetting class defines the configuration settings for Win32_Terminal.

Class Win32_TSClientSetting : CIM_TerminalSetting
{
   uint32 ConnectionPolicy;
   uint32 ConnectClientDrivesAtLogon;
   uint32 ConnectPrinterAtLogon;
   uint32 DefaultToClientPrinter;
   uint32 WindowsPrinterMapping;
   uint32 LPTPortMapping;
   uint32 COMPortMapping;
   uint32 DriveMapping;
   uint32 AudioMapping;
   uint32 ClipboardMapping;
};

Properties

ConnectionPolicy
Data type: uint32
Access type: Read-Write

The policy the server uses to retrieve the user connection settings.
Value | Meaning
Per User | The user's connection settings are in effect.
Server Override | The user's connection settings are overridden by the server.

ConnectClientDrivesAtLogon
Data type: uint32
Access type: Read-only

Specifies whether the client's drives will be automatically connected during the logon process.
Value | Meaning
FALSE | Drives will not be automatically connected.
TRUE | Drives will be automatically connected.

ConnectPrinterAtLogon
Data type: uint32
Access type: Read-only

Specifies whether all mapped local printers of the client will be automatically connected during the logon process.
Value | Meaning
FALSE | Local printers will not be automatically connected.
TRUE | Local printers will be automatically connected.

DefaultToClientPrinter
Data type: uint32
Access type: Read-only

Specifies whether print jobs will be automatically sent the client's local printer.
Value | Meaning
FALSE | Print jobs will not be automatically sent to the client's local printer.
TRUE | Print jobs will be automatically sent to the client's local printer.

WindowsPrinterMapping
Data type: uint32
Access type: Read-Write

Specifies whether the client window's printer mapping is disabled or enabled.
Value | Meaning
FALSE | Printer mapping is disabled.
TRUE | Printer mapping is enabled.

LPTPortMapping
Data type: uint32
Access type: Read-Write

Specifies whether the LPT port mapping is disabled or enabled.
Value | Meaning
FALSE | LPT port mapping is disabled.
TRUE | LPT port mapping is enabled.

COMPortMapping
Data type: uint32
Access type: Read-Write

Specifies whether the COM port mapping is disabled or enabled.
Value | Meaning
FALSE | COM port mapping is disabled.
TRUE | COM port mapping is enabled.

DriveMapping
Data type: uint32
Access type: Read-Write

Specifies whether drive mapping is disabled or enabled.
Value | Meaning
FALSE | Drive mapping is disabled.
TRUE | Drive mapping is enabled.

AudioMapping
Data type: uint32
Access type: Read-Write

Specifies whether audio mapping is disabled or enabled.
Value | Meaning
FALSE | Audio mapping is disabled.
TRUE | Audio mapping is enabled.

ClipboardMapping
Data type: uint32
Access type: Read-Write

Specifies whether clipboard mapping is disabled or enabled.
Value | Meaning
FALSE | Clipboard mapping is disabled.
TRUE | Clipboard mapping is enabled.

Methods

This following table lists the methods of Win32_TSClientSetting.

Method | Description
ConnectSettings | Sets the ClientConnectDrivesAtLogon, ConnectPrinterAtLogon, and DefaultPrinterToClient properties of this class.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_Service, Win32_TerminalServiceToSetting


Win32_TSEnvironmentSetting

The Win32_TSEnvironmentSetting class defines the configuration settings in Win32_Terminal.

Class Win32_TSEnvironmentSetting : CIM_TerminalSetting
{
   uint32 InitialProgramPolicy;
   string InitialProgramPath;
   string StartIn;
   uint32 ClientWallpaper;
};

Properties

InitialProgramPolicy
Data type: uint32
Access type: Read-Write

The policy the server uses to determine the startup program path and file name, and the name of the folder it is located in.
Value | Meaning
Per User | The user's startup program settings are in effect.
Server Override | The user's startup program settings are overridden by the server.

InitialProgramPath
Data type: string
Access type: Read-only

The name and the path of the program the user will run immediately after logging on to the Terminal Server.

StartIn
Data type: string
Access type: Read-only

The path of the working directory of the program the user will run immediately after logging on to the Terminal Server.

ClientWallpaper
Data type: uint32
Access type: Read-Write

Specifies whether the wallpaper image is displayed on the client. Not displaying the wallpaper image can save system resources by decreasing the time required to repaint the screen.
Value | Meaning
FALSE | The wallpaper image is not displayed on the client.
TRUE | The wallpaper image is displayed on the client.

Methods

This following table lists the methods of Win32_TSEnvironmentSetting.

Method | Description
InitialProgram | Sets the startup program properties included in this class.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_TSGeneralSetting

The Win32_TSGeneralSetting class represents the general settings of the terminal.

Class Win32_TSGeneralSetting : CIM_TerminalSetting
{
   string TerminalProtocol;
   string Transport;
   string Comment;
   uint32 WindowsAuthentication;
   uint32 EncryptionLevel;
};

Properties

TerminalProtocol
Data type: string
Access type: Read-only

The name of the session layer protocol.

Transport
Data type: string
Access type: Read-only

The type of transport used in the connection.

Comment
Data type: string
Access type: Read-Write

Descriptive name of the combination of session layer and transport protocol.

WindowsAuthentication
Data type: uint32
Access type: Read-Write

Specifies whether the connection defaults to the standard Windows authentication process if another authentication package has been installed on the system.
Value | Meaning
FALSE | Defaults to the standard Windows authentication process.
TRUE | Does not default to the standard Windows authentication process.

EncryptionLevel
Data type: uint32
Access type: Read-only

The encryption level.
Value | Meaning
Low | Low level of encryption. Only the data sent from the client to the server is protected by the encryption method based on the server's standard key strength. Data sent from the server to the client is not protected.
Medium | Medium level of encryption. All data sent between the server and the client is protected by the encryption method based on the server's standard key strength.
High | High level of encryption. All data sent between the server and the client is protected by the encryption method based on the server's standard key strength.

Methods

This class has no methods.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_TSLogonSetting

The Win32_TSLogonSetting class defines the configuration for a Win32_Terminal and its configuration settings.

Class Win32_TSLogonSetting : CIM_TerminalSetting
{
   uint32 ClientLogonInfoPolicy;
   uint32 PromptForPassword;
   string UserName;
   uint32 Password;
   string Domain;
};

Properties

ClientLogonInfoPolicy
Data type: uint32
Access type: Read-Write

The policy the server uses to determine connection settings.
Value | Meaning
Per User | Individual user connection settings are in effect.
Server Override | Individual user connection settings are overridden by the server.

PromptForPassword
Data type: uint32
Access type: Read-Write

Specifies whether the user is always prompted for a password while logging into the server.
Value | Meaning
FALSE | The user is not prompted for a password.
TRUE | The user is prompted for a password.

UserName
Data type: string
Access type: Read-only

The user's user name logon authentication credential.

Password
Data type: uint32
Access type: Read-only

The user's password logon authentication credential.

Domain
Data type: string
Access type: Read-only

The user's domain logon authentication credential. This is the domain in which the user's computer resides.

Methods

This following table lists the methods of Win32_TSLogonSetting.

Method | Description
ExplicitLogon | Sets the UserName, Password, and Domain authentication credentials.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_Service, Win32_TerminalServiceToSetting


Win32_TSNetworkAdapterSetting

The Win32_TSNetworkAdapterSetting class defines the configuration settings of the Win32_Terminal class.

Class Win32_TSNetworkAdapterSetting : CIM_TerminalSetting
{
   uint32 LANAdapterID;
   uint32 MaximumConnections;
   uint32 LANAdapterName;
};

Properties

LANAdapterID
Data type: uint32
Access type: Read-only

The SettingID value of the LAN adapter to be set. This value is in Win32_NetworkAdapterConfiguration. The value 0 denotes all LAN adapters.

MaximumConnections
Data type: uint32
Access type: Read-Write

The maximum number of connections allocated. The value MAXINT denotes an unlimited number of connections.

LANAdapterName
Data type: uint32
Access type: Read-only

The Description value of the LAN adapter to be set. This value is in Win32_NetworkAdapterConfiguration. The value 0 denotes all LAN adapters.

Methods

This following table lists the methods of Win32_TSClientSetting.

Method | Description
SelectAllLANAdapters | Selects all LAN adapters.
SelectLANAdapterID | Specifies the identifier of the LAN adapter to be set.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_TSNetworkAdapterListSetting

The Win32_TSNetworkAdapterListSetting class lists the network adapters on the terminal protocol and transport method specified as keys in Win32_Terminal based.

Class Win32_TSNetworkAdapterListSetting : CIM_TerminalSetting
{
   string * TerminalProtocol;
   string * Transport;
   uint32 NetworkAdapterID;
   uint32 Description;
};

Properties

TerminalProtocol
Data type: string
Access type: Read-only

The name of the session layer protocol used in the connection.

Transport
Data type: string
Access type: Read-only

The transport method used in the connection.

NetworkAdapterID
Data type: uint32
Access type: Read-only

The GUID of the network adapter to be set.

Description
Data type: uint32
Access type: Read-only

The display name of the LAN adapter to be set.

Methods

This class has no methods.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Win32_TSPermissionsSetting

The Win32_TSPermissionsSettings class represents an association between Win32_Terminal and its configuration settings in Win32_TSAccount.

Class Win32_TSPermissionsSetting : Win32_TerminalSetting
{
   Win32_Terminal * Element;
   Win32_TSAccount * Setting;

Properties

Element
Data type: Win32_Terminal
Access type: Read-only

The total number of session on the current server. This includes both connected and disconnected sessions.

Setting
Data type: Win32_TSAccount
Access type: Read-only

The number of disconnected sessions on the current server. These sessions may still be actively consuming server resources, however they currently have no network connection with a client.

Methods

This following table lists the methods of Win32_TSPermissionsSetting.

Method | Description
AddAccount | Adds an account to the terminal with the permission set specified in the value of the PermissionPreSet property.
RestoreDefaults | Restores the default values of the properties in this class.

Remarks

Win32_Terminal is associated to Win32_TSAccount as the Element property of the Win32_TSPermissionsSetting association.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_Terminal, Win32_TSAccount


Win32_TSRemoteControlSetting

The Win32_TSRemoteControlSetting class defines the configuration settings for the Win32_Terminal class.

Class Win32_TSRemoteControlSetting : CIM_TerminalSetting
{
   sint32 RemoteControlPolicy;
   uint32 RequireUserPermission;
   uint32 LevelofControl;
};

Properties

RemoteControlPolicy
Data type: sint32
Access type: Read-Write

The policy the server uses to retrieve the remote control settings.
Value | Meaning
Per User | The user's remote control settings are in effect.
Server Override | The user's remote control are overridden by the server.

RequireUserPermission
Data type: uint32
Access type: Read-only

Specifies whether the user's permission is required to remotely control the session.
Value | Meaning
FALSE | The user's permission is not required.
TRUE | The user's permission is required.

LevelofControl
Data type: uint32
Access type: Read-Write

Specifies whether the user's session can be only viewed or interacted with using a keyboard and mouse.
Value | Meaning
View | The session can viewed only.
Interact | The session can viewed and interacted with.

Methods

This following table lists the methods of Win32_TSRemoteControlSetting.

Method | Description
RemoteControl | Sets the RequireUserPermission and LevelofControl properties of this class.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_Service, Win32_TerminalServiceToSetting


Win32_TSSessionDirectory

The Win32_TSSessionDirectory class defines the configuration settings for the Win32_TSSessionDirectorySetting class. These settings include Session Directory Store and Cluster Name.

Class Win32_TSSessionDirectory : CIM_Setting
{
   string SessionDirectoryLocation;
   string SessionDirectoryClusterName;
   string SessionDirectoryActive;
};

Properties

SessionDirectoryLocation
Data type: string
Access type: Read-only

The name of the SQL server database.

SessionDirectoryClusterName
Data type: string
Access type: Read-only

The virtual IP address of the cluster.

SessionDirectoryActive
Data type: string
Access type: Read-only

Disables and enables the participation of Terminal Services in the Session Directory.
Value | Meaning
0 | Terminal Services participation in the Session Directory is disabled.
1 | Terminal Services participation in the Session Directory is enabled.

Methods

This following table lists the methods of Win32_TSSessionDirectory.

Method | Description
SetPolicyProperty | Initiates Server Override mode. The server overrides the user's policy settings.
SetSessionDirectoryActive | Disables and enables the Session Directory.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_TSSessionDirectorySetting


Win32_TSSessionDirectorySetting

The Win32_TSSessionDirectorySetting represents an association between an instantiation of Win32_TerminalService and an instantiation of Win32_TSSessionDirectory that includes Terminal Service Session Directory location, Cluster Name, and SessionDirectoryActive properties.

Class Win32_TSSessionDirectorySetting : CIM_ElementSetting
{
   Win32_TerminalService * Element;
   Win32_TSSessionDirectory * Setting
}

Properties

Element
Data type: Win32_TerminalService
Access type: Read-only

Represents the Win32_TerminalService that can be configured with the Settings member.

Setting
Data type: Win32_TSSessionDirectory
Access type: Read-only

Represents the Terminal Service Session Directory settings that can be applied to the associated Terminal Server.

Methods

This class has no methods.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods, Win32_TerminalService, Win32_TSSessionDirectory


Win32_TSSessionSetting

The Win32_TSSessionSetting class defines configuration settings for Win32_Terminal.

Class Win32_TSSessionSetting : CIM_TerminalSetting
{
   uint32 TimeLimitPolicy;
   uint32 ActiveSessionLimit;
   uint32 DisconnectedSessionLimit;
   uint32 IdleSessionLimit;
   uint32 BrokenConnectionPolicy;
   uint32 BrokenConnectionAction;
   uint32 ReconnectionPolicy
}

Properties

TimeLimitPolicy
Data type: uint32
Access type: Read-Write

The policy the server uses to determine time limits for user sessions.

ActiveSessionLimit
Data type: uint32
Access type: Read-only

The maximum amount of time, in minutes, allocated to Active Session. A value of 0 specifies an infinite amount of time.

DisconnectedSessionLimit
Data type: uint32
Access type: Read-only

The time interval after which a disconnected session is terminated. A value of 0 specifies an infinite amount of time.

IdleSessionLimit
Data type: uint32
Access type: Read-only

The time interval after which an idle session is terminated. A value of 0 specifies an infinite amount of time.

BrokenConnectionPolicy
Data type: uint32
Access type: Read-Write

The policy the server uses to determine that a connection has been broken due to network loss or time limits.
Value | Meaning
Per User | The user's disconnection policy settings are in effect.
Server Override | The user's disconnection policy settings are overridden by the server.

BrokenConnectionAction
Data type: uint32
Access type: Read-only

The action the server takes on the session when it is determined that a connection has been broken due to network loss or time limits.
Value | Meaning
Disconnect | The user is disconnected form the session.
Terminate | The session is permanently deleted from the server.

ReconnectionPolicy
Data type: uint32
Access type: Read-Write

Indicates which client will be used in order to reconnect to a disconnected session.
Value | Meaning
Any client | Any client will be used to reconnect.
Previous client | The previous client used in a connection will be used to reconnect.b

Methods

This following table lists the methods of Win32_TSSessionSetting.

Method | Description
BrokenConnection | Sets the broken connection properties included in this class.
TimeLimit | Sets the time limit properties included in this class.

Requirements

Version: Requires Windows 2000 or later.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Terminal Services WMI Provider Methods

The following are the methods defined in the Terminal Services WMI provider.

  • SetPolicyProperty Method in Class Win32_TSSessionDirectory
  • SetSessionDirectoryActive Method in Class Win32_TSSessionDirectory
  • ChangeMode Method in Class Win32_TerminalServiceSetting
  • Enable Method in Class Win32_Terminal
  • Rename Method in Class Win32_Terminal
  • ExplicitLogon Method in Class Win32_TSLogonSetting
  • TimeLimit Method in Class Win32_TSSessionSetting
  • BrokenConnection Method in Class Win32_TSSessionSetting
  • InitialProgram Method in Class Win32_TSEnvironmentSetting
  • RemoteControl Method in Class Win32_TSRemoteControlSetting
  • ConnectSettings Method in Class Win32_TSClientSetting
  • SelectLANAdapterID Method in Class Win32_TSNetworkAdapterSetting
  • SelectAllLANAdapters Method in Class Win32_TSNetworkAdapterSetting
  • AddAccount Method in Class Win32_TSPermissionsSetting
  • RestoreDefaults Method in Class Win32_TSPermissionsSetting
  • Delete Method in Class Win32_TSAccount
  • ModifyPermissions Method in Class Win32_TSAccount
  • ModifyAuditPermissions Method in Class Win32_TSAccount
  • Disconnect Method in Class Win32_Session
  • Logoff Method in Class Win32_Session
  • SendMessage Method in Class Win32_Session
  • Reset Method in Class Win32_Session


SetPolicyProperty Method in Class Win32_TSSessionDirectory

The SetPolicyProperty method sets the value of the specified Session Directory Service policy.

uint32 SetPolicyProperty (
  string PolicyPropertyName,
  string Value
);

Parameters

PolicyPropertyName
[in] The specified Session Directory Service policy property.
Value | Meaning
SessionDirectoryLocation | The value of the SessionDirectoryLocation property is to be set.
SessionDirectoryClusterName | The value of the SessionDirectoryClusterName property is to be set.
SessionDirectoryActive | The value of the SessionDirectoryActive property is to be set.

Value
[in] The value the specified Session Directory Service policy property is to be set to.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


SetSessionDirectoryActive Method in Class Win32_TSSessionDirectory

The SetSessionDirectoryActive method disables or enables the Session Directory Service.

uint32 SetSessionDirectoryActive (
  uint32 SessionDirectoryActive
);

Parameters

SessionDirectoryActive
[in] Flag disabling or enabling the Session Directory Service.
Value | Meaning
FALSE | Disable the Session Directory Service.
TRUE | Enable the Session Directory Service.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


ChangeMode Method in Class Win32_TerminalServiceSetting

The ChangeMode method set the server mode and licensing type of the current Terminal Services server.

uint32 ChangeMode (
  uint32 TerminalServerMode,
  uint32 LicensingType
);

Parameters

TerminalServerMode
[in] The Terminal Services mode to be set.
Value | Meaning
Application Server | The server operates as an application server.
Remote Administration | The session is administered remotely.
Personal Terminal Server | The server operates as a Personal Terminal Services server.

LicensingType
[in] The licensing type policy to be set.
Value | Meaning
None | No licensing regime is in effect.
Per Seat | A per-seat licensing regime is in effect.
Per User | A per-user licensing regime is in effect.
Concurrent | A concurrent licensing regime is in effect. The regime is supported in Windows 2000.
ICL | An Internet Connector Licensing (ICL) licensing regime is in effect. This regime is supported in Whistler.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Enable Method in Class Win32_Terminal

The Enable method disables and enables the terminal

uint32 Enable (
  uint32 fEnableTerminal
);

Parameters

fEnableTerminal
[in] Flag that disables and enables the terminal.
Value | Meaning
Disable | The terminal is disabled.
Enable | The terminal is enabled.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Rename Method in Class Win32_Terminal

The Rename method renames the terminal.

uint32 Rename (
  string NewTerminalName
);

Parameters

NewTerminalName
[in] The new name of the terminal.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


ExplicitLogon Method in Class Win32_TSLogonSetting

The ExplicitLogon method.

uint32 ExplicitLogon (
  uint32 UserName,
  uint32 Password,
  uint32 Domain
);

Parameters

UserName
[in] The user name logon credential.
Password
[in] The password logon credential.
Domain
[in] The domain logon credential.

Return Values

Returns Success on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


TimeLimit Method in Class Win32_TSSessionSetting

The TimeLimit method specifies the maximum time allocated to the specified session limit type.

uint32 TimeLimit (
  uint32 SessionLimitType,
  uint32 Value
);

Parameters

SessionLimitType
[in] The specified session limit type.
Value | Meaning
ActiveSessionLimit | The value of the ActiveSessionLimit session limit property is to be set.
DisconnectedSessionLimit | The value of the DisconnectedSessionLimit session limit property is to be set.
IdleSessionLimit | The value of the IdleSessionLimit session limit property is to be set.

Value
[in] The value of the specified session limit type to be set.

Return Values

Returns Success on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


BrokenConnection Method in Class Win32_TSSessionSetting

The BrokenConnection method determines the action to be taken by the server if the session time limit is reached or the connection is broken.

uint32 BrokenConnection (
  string BrokenConnectionAction
);

Parameters

BrokenConnectionAction
[in] The action of be taken.
Value | Meaning
Disconnect | The user is disconnected by from the session.
Terminate | The session is permanently deleted from the server.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


InitialProgram Method in Class Win32_TSEnvironmentSetting

The InitialProgram method specifies the name, working directory, and path of the program to be started immediately after logon.

uint32 InitProgram (
  string InitProgramPath,
  string StartIn
);

Parameters

InitProgramPath
[in] The path of the startup program.
StartIn
[in] The working directory of the startup program.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


RemoteControl Method in Class Win32_TSRemoteControlSetting

The RemoteControl method specifies whether the user's permission is required to remotely control the session and whether the session is viewed only or viewed and controlled through a keyboard and mouse.

uint32 RemoteControl (
  uint32 RequireUserPermission,
  uint32 LevelOfControl
);

Parameters

RequireUserPermission
[in] Specifies whether the user's permission is required to remotely control the session.
Value | Meaning
False | The user's permission is not required.
True | The user's permission is required.

LevelOfControl
[in] Specifies whether the session will be viewed only or viewed and controlled through a keyboard and mouse.
Value | Meaning
View | The session will be viewed only.
Interact | The session will be viewed and controlled through a keyboard and mouse.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


ConnectSettings Method in Class Win32_TSClientSetting

The ConnectSettings method specifies the session settings that apply to the connection and logon process.

uint32 ConnectSettings (
  uint32 ClientConnectDrivesAtLogon,
  uint32 ConnectPrinterAtLogon,
  uint32 DefaultPrinterToClient
);

Parameters

ClientConnectDrivesAtLogon
[in] Specifies whether the client's drives will be automatically connected during the logon procedure.
Value | Meaning
False | The client's drives will not be automatically connected.
True | The client's drives will be automatically connected.

ConnectPrinterAtLogon
[in] Specifies whether all mapped local client printers will be automatically connected during the logon procedure.
Value | Meaning
False | All mapped local printers will not be automatically connected.
True | All mapped local printers will be automatically connected.

DefaultPrinterToClient
[in] Specifies whether print jobs will be automatically sent to the client's local printer.
Value | Meaning
False | Print jobs will not be automatically sent.
True | Print jobs will be automatically sent.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


SelectLANAdapterID Method in Class Win32_TSNetworkAdapterSetting

The SelectLANAdapterID method specifies the identifier of the LAN adapter to be set.

uint32 SelectLANAdapterID (
  uint32 LANAdapterID
);

Parameters

LANAdapterID
[in] The identifier of the LAN adapter to be set.

Return Values

Returns 0 if the specified GUID is valid, and returns a WMI error code if the GUID is invalid. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


SelectAllLANAdapters Method in Class Win32_TSNetworkAdapterSetting

The SelectAllLANAdapters method selects all LAN adapters.

uint32 SelectAllLANAdapters ( );

Parameters

This method has no parameters.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


AddAccount Method in Class Win32_TSPermissionsSetting

The AddAccount method prepares to add an account to the terminal with the specified permission set.

uint32 AddAccount (
  string AccountName,
  uint32 PermissionPreSet
);

Parameters

AccountName
[in] The name of the account to be added to the terminal.
PermissionPreSet
[in] The set of permissions to be associated with the specified account. The value of this parameter is a bitmap, and any or all of the following values may be selected.
Value | Meaning
Guest | The guest permission bit.
User | The user permission bit.
Full | The full permission bit.
Custom | The custom permission bit.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


RestoreDefaults Method in Class Win32_TSPermissionsSetting

The RestoreDefaults method restores the default permission set values of the session.

uint32 RestoreDefaults ( );

Parameters

This method has no parameters.

Return Values

Returns Success on success, otherwise Failure.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Delete Method in Class Win32_TSAccount

The Delete method deletes the specified user, group, or computer.

uint32 Delete ( );

Parameters

This method has no parameters.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


ModifyPermissions Method in Class Win32_TSAccount

The ModifyPermissions method prepares to set a more granular permission set to the specified account.

uint32 ModifyPermissions (
  uint32 PermissionMask,
  boolean Allow
);

Parameters

PermissionMask
[in] The set of permissions to be associated with the specified account. The value of this parameter is a bitmap, and any or all of the following values may be selected.
Value | Meaning
Guest | The guest permission bit.
User | The user permission bit.
Full | The full permission bit.
Custom | The custom permission bit.

Allow
[in] Specifies if the permission set specified by the value of the PermissionMask parameter is allowed or denied.
Value | Meaning
Allow | The specified permission set is allowed.
Deny | The specified permission set is denied.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


ModifyAuditPermissions Method in Class Win32_TSAccount

The ModifyAuditPermissions method prepares to set a more granular set of audit permissions to the specified account.

uint32 ModifyAuditPermissions (
  uint32 PermissionMask,
  boolean Success
);

Parameters

PermissionMask
[in] The set of permissions to be associated with the specified account. The value of this parameter is a bitmap, and any or all of the following values may be selected.
Value | Meaning
Guest | The guest permission bit.
User | The user permission bit.
Full | The full permission bit.
Custom | The custom permission bit.

Success
[in] Specifies if the permission set specified by the value of the PermissionMask parameter is allowed or denied.
Value | Meaning
Allow | The specified permission set is allowed.
Deny | The specified permission set is denied.

Return Values

Returns 0 on success, otherwise returns a WMI error code. Refer to Terminal Services WMI Provider Error Codes for a list of these values.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Disconnect Method in Class Win32_Session

The Disconnect method saves the session state and does not log off the user. Upon reconnection, the saved state is restored.

uint32 Disconnect ( );

Parameters

This method has no parameters.

Return Values

Returns Success on success, otherwise Failure.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Logoff Method in Class Win32_Session

The Logoff method logs off the specified user. Upon reconnection, the previous state is not restored.

uint32 Logoff ( );

Parameters

This method has no parameters.

Return Values

Returns Success on success, otherwise Failure.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


SendMessage Method in Class Win32_Session

The SendMessage method sends the specified message to other sessions.

uint32 SendMessage (
  string Text
);

Parameters

Text
[in] The message text to be sent.

Return Values

Returns Success on success, otherwise Failure.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Reset Method in Class Win32_Session

The Reset method saves the session state and does not log off the user. Upon reconnection, the saved state is restored.

uint32 Reset ( );

Parameters

This method has no parameters.

Return Values

Returns Success on success, otherwise Failure.

See Also

About the Terminal Services WMI Provider, Terminal Services WMI Provider Classes, Terminal Services WMI Provider Methods


Mapping of WTS API Functions to Terminal Services WMI Provider Methods

The following table lists the WMI provider implementation of the corresponding WTS API functionality.

WTS API function name | WMI provider implementation
WTSShutdownSystem | The Reboot, Shutdown. Win32_Shutdown of the Win32_OperatingSystem class.
WTSQuerySessionInformation | The instance variables of Win32_Session.
WTSEnumerateSession | An enumeration of Win32_Session objects.
WTSDisConnectSession | The Disconnect method of the Win32_Session class.
WTSLogoffSession | The Logoff method of the Win32_Session class.
WTSEnumerateProcesses | An enumeration of Win32_Process objects.
WTSTerminateProcess | The Terminate method of the Win32_Process class.
WTSSendMessage | The SendMessage method of the Win32_Session class.

Note that there is no WMI provider alternative for WTSQueryUserConfig and WTSSetUserConfig. ADSI provides the alternate functionality.


Terminal Services WMI Provider Error Codes

The following table lists the WMI errors returned by the WMI provider.

WMI Error Name | Description
WBEM_E_FAILED | The method call failed.
WBEM_E_NOT_FOUND | The object could not be found.
WBEM_E_PROVIDER_FAILURE | The provider has failed at some time other than during initialization.
WBEM_E_TYPE_MISMATCH | The type mismatch has occurred.
WBEM_E_OUT_OF_MEMORY | There was not enough memory for the operation.
WBEM_E_INVALID_PARAMETER | One of the parameters to the call is not correct.
WBEM_E_NOT_AVAILABLE | The resource, typically a remote server, is not currently available.
WBEM_E_NOT_SUPPORTED | The feature or operation is not supported.
WBEM_E_INVALID_NAMESPACE | The specified namespace could not be found.
WBEM_E_INVALID_OBJECT | The specified instance is not valid.
WBEM_E_INITIALIZATION_FAILURE | A component, such as a provider, failed to initialize for internal reasons. This error is returned when the CfgBkEnd backend interface is not initialized.
WBEM_E_INVALID_OPERATION | The requested operation is not valid. This error usually applies to invalid attempts to delete classes or properties. This error is returned on an attempt to modify a server-override property through group policy control.
WBEM_E_INVALID_QUERY | The query was not syntactically valid.
WBEM_E_INVALID_QUERY_TYPE | The requested query language is not supported.
WBEM_E_ALREADY_EXISTS | In a put operation, the wbemChangeFlagCreateOnly flag was specified, but the instance already exists.
WBEM_E_INVALID_SYNTAX | Reserved for future use.
WBEM_E_READ_ONLY | The property that you are attempting to modify is read-only.
WBEM_E_PROVIDER_NOT_CAPABLE | The provider cannot perform the requested operation. This would include a query that is too complex, retrieving an instance, creating a class, updating a class, deleting a class, or enumerating a class.
WBEM_E_ILLEGAL_NULL | A value of Nothing was specified for a property that may not be Nothing, such as one that is marked by a Key, Indexed, or Not_Null qualifier.
WBEM_E_VALUE_OUT_OF_RANGE | The request was made with an out-of-range value, or is incompatable with the type.
WBEM_E_INVALID_METHOD | The requested method is not available.
WBEM_E_INVALID_METHOD_PARAMETERS | The parameters provided for the method are invalid.
WBEM_E_INVALID_OBJECT_PATH | The specified object path was invalid.


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 terminal servers in a domain or enumerating and managing sessions and processes on a terminal server.
  • Enhancing client/server applications in a Terminal Services environment.
  • Using Terminal Services virtual channels to communicate between client and server components of an application.
  • Setting and retrieving Terminal-Services-specific user configuration information.


About Terminal Services API

Most Win32®-based 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 do 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 Run-time Linking to Wtsapi32.dll.

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 terminal servers in a domain or enumerating and managing sessions and processes on a terminal server.
  • Enhancing client/server applications in a Terminal Services environment.
  • Using Terminal Services virtual channels to communicate between client and server components of an application.
  • Setting and retrieving Terminal-Services-specific user configuration information.


Terminal Services Administration

The Terminal Services API enables you to enumerate and manage terminal servers, client sessions, and processes.

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.

Function | Operation
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 an 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 the identifier of its Terminal Services session. 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 a 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. The server application can also create two events to monitor client connection to and disconnection from a session. However, it must be registered on the terminal server to do this. Refer to Monitoring Session Connections and Disconnections for more information.

Processes spawned from multiple sessions can send data to and receive data from each other through the use of shared memory blocks. This is done by calling CreateFileMapping. If you do this, keep in mind that shared memory cannot be used in situations where the following conditions exist:

  • All of the processes using the shared memory block were not spawned by one session.
  • All of the sessions share the same user authentication credential.


Monitoring Session Connections and Disconnections

For the service-side application to monitor session connections and disconnections, you must register it with Terminal Services in the following manner. First, 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

The subkey can have any name. It must have a REG_SZ value, Name, that contains the symbolic name of the application.

Name = AddinName

The maximum length of both the subkey and the value of Name is 99 characters.

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

Type = AddinType

AddinType must be the following value.

Value | Meaning
3 | User-mode application, session space.

Registration of the server application takes effect only in sessions created after the registration was performed.

For each registered server application, Terminal Services will signal a set of event objects when a client connects or disconnects from the session. Each virtual channel plug-in must register itself and create the notification events by calling CreateEvent. The names of these event objects adhere to the following format.

Note This format is new for Whistler.

AddinName-Reconnect

AddinName-Disconnect

AddinName is the string specified in the Name value of the registry subkey under which the server application is registered. Creating these events under a session causes them to be created in a special per-session event directory. The event directory provides added security by preventing applications in other sessions from modifying the state of these events.

The event-object name format used in Windows 2000 is still supported in Whistler for backward compatibility. It is recommended that you use the newer Whistler format, as it is more secure.

The Windows 2000 event format is:

Global\AddinName-SessionId-Reconnect

Global\AddinName-SessionId-Disconnect

AddinName is the string specified in the Name value of the registry subkey under which the server application is registered. SessionId is the session identifier of a client session.


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.

Function | Description
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 the 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.

A DLL can specify one or more virtual channels as remote control persistent. A remote control persistent virtual channel is not closed when a remote control connects or disconnects for the session connected to the client. Data will continue to be transmitted and received through this channel. Virtual channels that the DLL does not specify as remote control persistent will close in this scenario.

Remote control persistent virtual channels are specified during the call to VirtualChannelInit. Refer to the reference page for VirtualChannelInit for specific information about this.

After the connection is established, 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_CURRENT_USER\Software\Microsoft
\Terminal Server Client\Default\Addins

HKEY_CURRENT_USER\Software\Microsoft
\Terminal Server Client\connection\Addins

Entries under the \Default\Addins key apply to all connections. Entries under the \connection\Addins key apply only to the connection identified by connection. Connections can be created and managed using Connection Manager.

The subkey can be given any name. It must contain a REG_SZ or REG_EXPAND_SZ value and may optionally contain a REG_DWORD value. The syntax of the REG_SZ or REG_EXPAND_SZ value is the following:

Name = DLLname

If Name is a REG_EXPAND_SZ value, it can contain unexpanded environment variables that are expanded at runtime.

The value of DLLname can be a fully-qualified path. If DLLname does not contain a path, the standard DLL search strategy is used. For more information, see the Remarks section for LoadLibrary.

The syntax of the REG_DWORD value is the following:

RemoteControlPersistent = flag

The value of flag is either 1 or 0, with 0 being the default value If set to 1, the addin will not be notified if the remote control is started or stopped. If set to 0, these events will be signaled for the addin respectively as connections and disconnections.

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 after the line containing "AddinName=". This section will contain a single entry with the name of the DLL, in the following manner.

[AddinName]
Name = DLLname

Addins cannot be registered on a per-connection basis in 16-bit versions of Windows. They always apply to all connections.


Virtual Channel Server Application

The component of an application that uses virtual channels must be a user-mode application running in a client session on the terminal server.

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

Function | Description
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.
WTSVirtualChannelRead | Reads data from the server end of a virtual channel.
WTSVirtualChannelWrite | Writes data to the server end of a virtual channel.


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


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.

For information about determining whether your application is running in a Terminal Services environment, see Detecting the Terminal Services Environment.


Terminal Services API Reference

The following elements are used with the Terminal Services API:

  • Terminal Services API Functions
  • Terminal Services API Messages
  • Terminal Services API Structures
  • Terminal Services API Enumeration Types


Terminal Services API Functions

The following functions are used with Terminal Services.

Function | Description
ProcessIdToSessionId | Retrieves the Terminal Services session associated with a specified process.
VirtualChannelClose | Closes the client end of a virtual channel.
VirtualChannelEntry | An application-defined entry point for the client-side DLL of an application that uses Terminal Services virtual channels.
VirtualChannelInit | Initializes a client DLLs access to Terminal Services virtual channels.
VirtualChannelInitEvent | An application-defined callback function that Terminal Services calls to notify the client DLL of virtual channel events.
VirtualChannelOpen | Opens the client end of a virtual channel.
VirtualChannelOpenEvent | An application-defined callback function that Terminal Services calls to notify the client DLL of events for a specific virtual channel.
VirtualChannelWrite | Sends data from the client end of a virtual channel to a partner application on the server end.
WTSCloseServer | Closes an open handle to a terminal server.
WTSDisconnectSession | Disconnects the logged-on user from the specified Terminal Services session without closing the session.
WTSEnumerateProcesses | Retrieves information about the active processes on a specified terminal server.
WTSEnumerateSessions | Retrieves a list of sessions on a specified terminal server.
WTSFreeMemory | Frees memory allocated by a Terminal Services function.
WTSGetActiveConsoleSessionId | Retrieves the Terminal Services session currently attached to the physical console.
WTSLogoffSession | Logs off a specified Terminal Services session.
WTSOpenServer | Opens a handle to the specified terminal server.
WTSQuerySessionInformation | Retrieves session information for the specified session on the specified terminal server.
WTSQueryUserConfig | Retrieves configuration information for the specified user on the specified domain controller or terminal server.
WTSRegisterSessionNotification | Registers the specified window to receive session change notifications.
WTSSendMessage | Displays a message box on the client desktop of a specified Terminal Services session.
WTSSetUserConfig | Modifies configuration information for the specified user on the specified domain controller or terminal server.
WTSShutdownSystem | Shuts down (and optionally reboots) the specified terminal server.
WTSTerminateProcess | Terminates the specified process on the specified terminal server.
WTSUnRegisterSessionNotification | Unregisters the specified window from receiving session change notifications.
WTSVirtualChannelClose | Closes an open virtual channel handle.
WTSVirtualChannelOpen | Opens a handle to the server end of a specified virtual channel.
WTSVirtualChannelPurgeInput | Purges all queued input data sent from the client to the server on a specified virtual channel.
WTSVirtualChannelPurgeOutput | Purges all queued output data sent from the server to the client on a specified virtual channel.
WTSVirtualChannelRead | Reads data from the server end of a virtual channel.
WTSVirtualChannelWrite | Writes data to the server end of a virtual channel.
WTSWaitSystemEvent | Waits for a Terminal Services event before returning to the caller.


ProcessIdToSessionId

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

BOOL ProcessIdToSessionId(
  DWORD dwProcessId,
  DWORD *pSessionId
);

Parameters

dwProcessId
[in] Specifies a process identifier. Use the GetCurrentProcessId function to retrieve the process identifier for the current process.
pSessionId
[out] Pointer to a variable that receives the 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in] Handle to 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 parameter is not valid.
CHANNEL_RC_NOT_OPEN | The channel is not open.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in] Pointer to a CHANNEL_ENTRY_POINTS structure that contains pointers to the client-side virtual channel functions.

This pointer is no longer valid after the VirtualChannelEntry function returns. You must make a copy of this structure in extension-allocated memory for later use.

Return Values

Return TRUE if the function is successful.

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

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in] 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
[in/out] 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.
channelCount
[in] Specifies the number of entries in the pChannel array.
versionRequested
[in] Specifies the level of virtual channel support. Set this parameter to VIRTUAL_CHANNEL_VERSION_WIN2000.
pChannelInitEventProc
[in] 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_CONNECTED | The client is already connected to a terminal server.
CHANNEL_RC_BAD_CHANNEL | The pChannel parameter is incorrect or one of the channel names is syntactically incorrect.
CHANNEL_RC_BAD_INIT_HANDLE | The ppInitHandle parameter is incorrect.
CHANNEL_RC_BAD_PROC | The pChannelInitEventProc parameter is incorrect.
CHANNEL_RC_NOT_IN_VIRTUALCHANNELENTRY | The VirtualChannelInit function was not called from within your VirtualChannelEntry function.
CHANNEL_RC_TOO_MANY_CHANNELS | The pChannel array has more channels than can be registered. Therefore, none of the channels were registered. The maximum number of channels allowed per client is CHANNEL_MAX_COUNT.

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.

You should not make assumptions about the number of available virtual channels before calling this function, because the system and other plug-ins may have reserved virtual channels. Therefore, you should always check for a CHANNEL_RC_TOO_MANY_CHANNELS return code after calling this function.

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

The maximum number of channels per client session is CHANNEL_MAX_COUNT.

Whistler: A client plug-in can declare a channel as remote control persistent. This is done by specifying CHANNEL_OPTION_REMOTE_CONTROL_PERSISTENT in a CHANNEL_DEF structure pointed to by the pChannel parameter. For more information on remote control persistent channels, refer to Virtual Channel Client DLL.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in ]Handle to the client connection. This is the same as the handle returned in the ppInitHandle parameter of the VirtualChannelInit function.
event
[in] Indicates the event that caused the notification. This parameter can be one of the following values.
Value | Meaning
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_DISCONNECTED | The connection to the terminal server has been disconnected. The pData parameter is NULL.
CHANNEL_EVENT_INITIALIZED | The Terminal Services client initialization has been completed. The pData parameter is NULL.
CHANNEL_EVENT_TERMINATED | The client has been terminated. The pData parameter is NULL.
CHANNEL_EVENT_V1_CONNECTED | A connection has been established with a terminal server that does not support virtual channels. The pData parameter is NULL.

pData
[in] Pointer to additional data for the event. The type of data depends on the event, as described in the event descriptions.
dataLength
[in] Specifies the size, in bytes, of the data in the pData buffer.

Return Values

This function does not return a value.

Remarks

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

This function is reentrant on a per handle basis. It may be called while it is executing, but not on the same handle more than once.

This function is called only after VirtualChannelEntry has completed.

CHANNEL_EVENT_CONNECTED and CHANNEL_EVENT_DISCONNECTED event notifications will not be sent if the connection is transferred to another session. A server-side tool such as tscon can be used to do this. However, the server-side plug-in administering the session the connection is transferred to will receive a reconnection notification. Refer to Monitoring Session Connections and Disconnections for more information on reconnection notifications.

If the user-mode plug-in must be notified that it has been reconnected; for example, it must reset state, then the server-side plug-in should send a notification message to the client. This notification should use the protocol that the plug-ins use to communicate with each other.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in] Handle to the client connection. This is the handle returned in the ppInitHandle parameter of the VirtualChannelInit function.
pOpenHandle
[out] Pointer to a variable that receives a handle that identifies the open virtual channel in subsequent calls to the VirtualChannelWrite and VirtualChannelClose functions.
pChannelName
[in] 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
[in] 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_ALREADY_OPEN | The channel is already open.
CHANNEL_RC_BAD_CHANNEL_HANDLE | The pOpenHandle parameter is not valid.
CHANNEL_RC_BAD_INIT_HANDLE | The pInitHandle parameter is not valid.
CHANNEL_RC_BAD_PROC | The pChannelOpenEventProc parameter is not valid.
CHANNEL_RC_NOT_CONNECTED | The client has not connected to a terminal server.
CHANNEL_RC_UNKNOWN_CHANNEL_NAME | The channel name specified by the pChannelName parameter is not registered by the client DLL or is otherwise invalid.

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.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in] Handle to the virtual channel. This is the same as the handle returned in the pOpenHandle parameter of the VirtualChannelOpen function.
event
[in] 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_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.

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.

pData
[in] Pointer to additional data for the event. The type of data depends on the event, as described in the event 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
[in] Specifies the size, in bytes, of the data in the pData buffer.
totalLength
[in] Specifies the total size, in bytes, of the data written by a single write operation to the server end of the virtual channel.
dataFlags
[in] Provides information about the chunk of data being received in a CHANNEL_EVENT_DATA_RECEIVED event. The following bit flags will be set. Do not make direct comparisons using the '==' operator; use the methods described in the following table to compare the corresponding flag value.
Value Meaning
CHANNEL_FLAG_FIRST The chunk is the beginning of the data written by a single write operation.

Use bitwise comparisons when comparing this flag.
CHANNEL_FLAG_LAST The chunk is the end of the data written by a single write operation.

Use bitwise comparisons when comparing this flag.
CHANNEL_FLAG_MIDDLE This is the default. The chunk is in the middle of a block of data written by a single write operation.

Do not use bitwise comparisons to compare this flag value directly. Instead, use bitwise comparisons to determine that the flag value is not CHANNEL_FLAG_FIRST or CHANNEL_FLAG_LAST. This is done by using the following comparison: Result = !(flags & CHANNEL_FLAG_FIRST) && !(flags & CHANNEL_FLAG_LAST).
CHANNEL_FLAG_ONLY Combines the CHANNEL_FLAG_FIRST and CHANNEL_FLAG_LAST values. The chunk contains all the data from a single write operation.

Use bitwise comparisons when comparing this flag.

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.

This function can be called with a different event type while it is executing. For example, it might be called with CHANNEL_EVENT_WRITE_COMPLETE or CHANNEL_EVENT_WRITE_CANCELLED while it is processing the CHANNEL_EVENT_DATA_RECEIVED event. Note that this function will not be called with the same type it is currently processing.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, 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
[in] Handle to the virtual channel. This is the handle returned in the pOpenHandle parameter of the VirtualChannelOpen function.
pData
[in] Pointer to a buffer containing the data to write.
dataLength
[in] Specifies the number of bytes of the data in the pData buffer to write.
pUserData
[in] 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_BAD_CHANNEL_HANDLE | The openHandle parameter is not valid.
CHANNEL_RC_NO_MEMORY | Indicates an out-of-memory condition.
CHANNEL_RC_NOT_CONNECTED | The client has not connected to a terminal server.
CHANNEL_RC_NULL_DATA | The pData parameter is not valid.
CHANNEL_RC_ZERO_LENGTH | The dataLength parameter is zero.

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.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Functions, VirtualChannelOpen, VirtualChannelOpenEvent, WTSVirtualChannelRead


WTSCloseServer

The WTSCloseServer function closes an open handle to a terminal server.

VOID WTSCloseServer(
  HANDLE hServer
);

Parameters

hServer
[in] 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 does not return a value.

Remarks

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

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
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
[in] 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
[in] A Terminal Services session identifier. To indicate the current session, specify WTS_CURRENT_SESSION. To retrieve the identifiers of all sessions on a specified terminal server, use the WTSEnumerateSessions function.

To be able to disconnect another user's session, you need to have the Disconnect permission. To modify permissions on a session, use the Terminal Services Configuration administrative tool.

bWait
[in] 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.

Remarks

Note that you cannot disconnect the console session.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSEnumerateSessions


WTSEnumerateProcesses

The WTSEnumerateProcesses function retrieves 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
[in] 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
[in] Specifies the version of the enumeration request. Must be 1.
ppProcessInfo
[out] 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
[out] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTS_PROCESS_INFO


WTSEnumerateSessions

The WTSEnumerateSessions function retrieves 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
[in] 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
[in] Specifies the version of the enumeration request. Must be 1.
ppSessionInfo
[out] 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.

To be able to enumerate a session, you need to have the Query Information permission. To modify permissions on a session, use the Terminal Services Configuration administrative tool.

pCount
[out] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

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
[in] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

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


WTSGetActiveConsoleSessionId

The WTSGetActiveConsoleSessionId function retrieves the Terminal Services session currently attached to the physical console. The physical console is the monitor, keyboard, and mouse.

DWORD WTSGetActiveConsoleSessionId (VOID);

Parameters

This function has no parameters.

Return Values

The session identifier of the session attached to the console. If there is no session attached to the console; for example, if the console session is in the process of being attached or detached, this function returns 0xFFFFFFFF.

Remarks

The session identifier returned by this function is the identifier of the current console session. To monitor the state of the current console session, use the WTSRegisterSessionNotification function.

Requirements

Version: Requires Whistler.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, ProcessIdToSessionId, WM_WTSSESSION_CHANGE, WTSQuerySessionInformation, WTSRegisterSessionNotification


WTSLogoffSession

The WTSLogoffSession function logs off a specified Terminal Services session.

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

Parameters

hServer
[in] 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
[in] 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.

To be able to log off another user's session, you need to have the Reset permission. To modify permissions on a session, use the Terminal Services Configuration administrative tool.

bWait
[in] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
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
[in] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSCloseServer


WTSQuerySessionInformation

The WTSQuerySessionInformation function retrieves session information for the specified session on the specified terminal server.

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

Parameters

hServer
[in] 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
[in] 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.

To be able to query information for another user's session, you need to have the Query Information permission. To modify permissions on a session, use the Terminal Services Configuration administrative tool.

WTSInfoClass
[in] Specifies the type of information to retrieve. This parameter can be one of the values from the WTS_INFO_CLASS enumeration type. The following table shows the format of the data returned in ppBuffer for each of the information types.
Value | Data format of ppBuffer
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.
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.

Note that the first byte of the IP address returned in the ppBuffer parameter will be located at an offset of two bytes from the first location of the buffer.
WTSClientBuildNumber | Pointer to a ULONG variable. 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.
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.
WTSClientHardwareId | Pointer to a ULONG variable containing a client-specific hardware identifier. 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.
WTSClientProductId | Pointer to a USHORT variable containing a client-specific product identifier. If the function is called from the Terminal Services console, ppBuffer returns a NULL pointer.
WTSClientProtocolType Pointer to a USHORT variable containing the protocol type. This is one of the following values:

WTS_PROTOCOL_TYPE_CONSOLE
WTS_PROTOCOL_TYPE_ICA
WTS_PROTOCOL_TYPE_RDP
WTSConnectState | Pointer to an INT variable that contains a value from the WTS_CONNECTSTATE_CLASS enumeration type to indicate the session's current connection state.
WTSDomainName | Pointer to a null-terminated string that names the domain of the logged-on user.
WTSInitialProgram | Pointer to a null-terminated string containing the name of the initial program that Terminal Services runs when the user logs on.
WTSOEMId | Pointer to a null-terminated string.
WTSSessionId | Pointer to a ULONG variable 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.
WTSWorkingDirectory | Pointer to a null-terminated string containing the default directory used when launching the initial program.

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

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

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

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


WTSQueryUserConfig

The WTSQueryUserConfig function retrieves configuration information for the specified user on the specified domain controller or terminal server.

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

Parameters

pServerName
[in] 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
[in] Pointer to a null-terminated string containing the user name to query.
WTSConfigClass
[in] Specifies the type of information to retrieve. 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
[out] Pointer to a variable that receives a pointer to the requested information. The format and contents of the data depend on the information class specified in the WTSConfigClass parameter. To free the returned buffer, call the WTSFreeMemory function.
pBytesReturned
[out] Pointer to a variable that receives the size, in bytes, of the data returned in ppBuffer.

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

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

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
[in] 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
[in] 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.

To be able to send a message an another user's session, you need to have the Message permission. To modify permissions on a session, use the Terminal Services Configuration administrative tool.

pTitle
[in] Pointer to a null-terminated string for the title bar of the message box.
TitleLength
[in] Specifies the length, in bytes, of the title bar string.
pMessage
[in] Pointer to a null-terminated string containing the message to display.
MessageLength
[in] Specifies the length, in bytes, of the message string.
Style
[in] Specifies the contents and behavior of the message box. This value is typically MB_OK. For a complete list of values, see the uType parameter of the MessageBox function.
Timeout
[in] 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
[out] 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
[in] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Terminal Services API Overview, Terminal Services API Functions, MessageBox


WTSRegisterSessionNotification

The WTSRegisterSessionNotification function registers the specified window to receive session change notifications.

BOOL WTSRegisterSessionNotification(
  HWND hWnd,
  DWORD dwFlags
);

Parameters

hWnd
[in] Handle of the window to receive session change notifications.
dwFlags
[in] Specifies which session notifications are to be received. This parameter can be one of the following values.
Value | Meaning
NOTIFY_FOR_THIS_SESSION | Only session notifications involving the session attached to by the window identified by the hWnd parameter value are to be received.
NOTIFY_FOR_ALL_SESSIONS | All session notifications are to be received.

Return Values

If the function succeeds, the return value is TRUE. Otherwise, it is FALSE. To get extended error information, call GetLastError.

Remarks

Session change notifications are sent in the form of a WM_WTSSESSION_CHANGE message. These notifications are sent only to the windows that have registered for them using this function.

When a window no longer requires these notifications, it must call WTSUnRegisterSessionNotification before being destroyed. For every call to this function, there must be a corresponding call to WTSUnRegisterSessionNotification.

If the window handle passed in this function is already registered, the value of the dwFlags parameter is ignored.

To receive session change notifications from a service, use the HandlerEx function.

Requirements

Version: Requires Whistler.
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, HandlerEx, WTSUnRegisterSessionNotification, WTSGetActiveConsoleSessionId, WM_WTSSESSION_CHANGE, WTSSESSION_NOTIFICATION


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
[in] 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
[in] Pointer to a null-terminated string containing the name of the user whose configuration is being set.
WTSConfigClass
[in] 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
[in] Pointer to the data used to modify the specified user's configuration.
DataLength
[in] 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

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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

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
[in] 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
[in] 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 (except the session calling WTSShutdownSystem) and disables all further logons. This value does not log off the Terminal Services console session; it can be used as a preliminary step before shutting down. Logons are reenabled when the terminal server is restarted.

Use this value only on the Terminal Services console.

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 EWX_SHUTDOWN and EWX_POWEROFF. 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 EWX_REBOOT. The calling process must have the SE_SHUTDOWN_NAME privilege enabled.
WTS_WSD_SHUTDOWN | Shuts down the system on the terminal server. This is equivalent to calling the ExitWindowsEx function with EWX_SHUTDOWN. The calling process must have the SE_SHUTDOWN_NAME privilege enabled.

Return Values

If the function succeeds, the return value is nonzero.

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.

  1. An exit command is issued to all active user applications.
  2. If the application does not exit within a specific interval, the application is terminated.
  3. After all the applications for a user terminate, the user is logged off.
  4. After all users are logged off, an exit command is issued to all system services.
  5. If the system service does not terminate within a specific interval, the service is terminated.
  6. The file system cache is written to disk.
  7. The disks are marked read only.
  8. The terminal server displays the message "It is now safe to turn off your computer", or the system is rebooted if WTS_WSD_REBOOT is specified. (The message is displayed on the console because all client sessions have been terminated.)

Warning Because there can be many users and processes in a large multi-user 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, ExitWindowsEx


WTSTerminateProcess

The WTSTerminateProcess function terminates the specified process on the specified terminal server.

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

Parameters

hServer
[in] 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
[in] Specifies the process identifier of the process to terminate.
ExitCode
[in] 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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions


WTSUnRegisterSessionNotification

The WTSUnRegisterSessionNotification function unregisters the specified window so that it receives no further session change notifications.

BOOL WTSUnRegisterSessionNotification(
  HWND hWnd
);

Parameters

hWnd
[in] Handle of the window to be unregistered from receiving session notifications.

Return Values

If the function succeeds, the return value is TRUE. Otherwise, it is FALSE. To get extended error information, call GetLastError.

Remarks

This function must be called once for every call to the WTSRegisterSessionNotification function.

Requirements

Version: Requires Whistler.
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSRegisterSessionNotification


WTSVirtualChannelClose

The WTSVirtualChannelClose function closes an open virtual channel handle.

BOOL WTSVirtualChannelClose(
  HANDLE hChannelHandle
);

Parameter

hChannelHandle
[in] 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.

Requirements

Version: Requires Windows 2000 or later.
Header: Declared in Wtsapi32.h.
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
[in] 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
[in] 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.

To be able to open a virtual channel on another user's session, you need to have the Virtual Channels permission. To modify permissions on a session, use the Terminal Services Configuration administrative tool.

pVirtualName
[in] Pointer to a null-terminated string containing the virtual channel name. This is an ANSI string (even when UNICODE is defined). The virtual channel name consists of one to CHANNEL_NAME_LEN characters, not including the terminating null.

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.

Remarks

To close the handle when you have finished, call the WTSVirtualChannelClose function.

Requirements

Version: Requires Windows 2000 or later.
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSEnumerateSessions, WTSOpenServer, 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
[in] 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.

Requirements

Version: Requires Windows 2000 or later.
Header: Declared in Wtsapi32.h.
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
[in] 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.

Requirements

Version: Requires Windows 2000 or later.
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions, WTSVirtualChannelPurgeInput


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
[in] Handle to a virtual channel opened by the WTSVirtualChannelOpen function.
TimeOut
[in] 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
[out] 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
[in] Specifies the size, in bytes, of Buffer. If the client set the CHANNEL_OPTION_SHOW_PROTOCOL option, the value of this parameter should be at least CHANNEL_PDU_LENGTH. If the CHANNEL_OPTION_SHOW_PROTOCOL is not used, the value of this parameter should be at least CHANNEL_CHUNK_LENGTH.
pBytesRead
[out] 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.

Requirements

Version: Requires Windows 2000 or later.
Header: Declared in Wtsapi32.h.
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
[in] Handle to a virtual channel opened by the WTSVirtualChannelOpen function.
Buffer
[in] Pointer to a buffer containing the data to write to the virtual channel.
Length
[in] Specifies the size, in bytes, of the data to write.
pBytesWritten
[out] 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.

Requirements

Version: Requires Windows 2000 or later.
Header: Declared in Wtsapi32.h.
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
[in] 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
[in] 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_ALL | Wait for any event type.
WTS_EVENT_CONNECT | A client connected to a WinStation.
WTS_EVENT_CREATE | A new WinStation was created.
WTS_EVENT_DELETE | An existing WinStation was deleted.
WTS_EVENT_DISCONNECT | A client disconnected from a WinStation.
WTS_EVENT_LICENSE | The Terminal Services's license state changed. This occurs when a license is added or deleted using License Manager.
WTS_EVENT_LOGOFF | A user logged off from either the Terminal Services console or from a client WinStation.
WTS_EVENT_LOGON | A user logged on to the system from either the Terminal Services console or from a client 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.

pEventFlags
[out] 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 WTS_EVENT_FLUSH.

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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Library: Use Wtsapi32.lib.

See Also

Terminal Services API Overview, Terminal Services API Functions


Terminal Services API Messages

The following message is used with the Terminal Services API.

WM_WTSSESSION_CHANGE


WM_WTSSESSION_CHANGE

The WM_WTSSESSION_CHANGE message notifies applications of changes in session state.

The window receives this message through its WindowProc function.

LRESULT CALLBACK WindowProc(
  HWND hWnd,
  UINT uMsg,
  WPARAM wParam,
  LPARAM lParam
);

Parameters

hWnd
[in] Handle to the window.
uMsg
[in] Specifies the message.
wParam
[in] Status code describing the reason the session state change notification was sent. This parameter can be one of the following values.
Value | Meaning
WTS_CONSOLE_CONNECT | A session was connected to the console session.
WTS_CONSOLE_DISCONNECT | A session was disconnected from the console session.
WTS_REMOTE_CONNECT | A session was connected to the remote session.
WTS_REMOTE_DISCONNECT | A session was disconnected from the remote session.
WTS_SESSION_LOGON | A user has logged on to the session.
WTS_SESSION_LOGOFF | A user has logged off the session.

lParam
[in] The identifier of the session.

Return Values

The return value is ignored.

Remarks

This message is sent only to applications that have registered to receive this message by calling WTSRegisterSessionNotification.

Examples of how applications can respond to this message include releasing or acquiring console-specific resources, determining how a screen is to be painted, or triggering console animation effects.

Requirements

Version: Requires Whistler.
Header: Declared in Winuser.h; include Windows.h.

See Also

Terminal Services API Overview, Terminal Services API Messages, WTSRegisterSessionNotification, WTSUnRegisterSessionNotification


Terminal Services API Structures

The following structures are used with the Terminal Services API.

CHANNEL_DEF
CHANNEL_ENTRY_POINTS
CHANNEL_PDU_HEADER
WTS_CLIENT_ADDRESS
WTS_CLIENT_DISPLAY
WTS_PROCESS_INFO
WTS_SESSION_INFO
WTSSESSION_NOTIFICATION


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_ENCRYPT_CS | Encrypt client-to-server data.
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_INITIALIZED | The channel is initialized. This value is set by the VirtualChannelInit function.
CHANNEL_OPTION_REMOTE_CONTROL_PERSISTENT | The channel is declared as remote control persistent. This means that the channel will not be closed when a remote control connects to or disconnects from the session connected to the client.
CHANNEL_OPTION_SHOW_PROTOCOL | Affects how data sent by the VirtualChannelWrite function is received at the server end. If this value is set, each data block is preceded by a CHANNEL_PDU_HEADER structure. If this value is not set, the data block includes only the data specified to VirtualChannelWrite.

The following values are defined but not yet supported.
Value | Meaning
CHANNEL_OPTION_COMPRESS | Reserved for future use.
CHANNEL_OPTION_COMPRESS_RDP | Reserved for future use.
CHANNEL_OPTION_ENCRYPT_SC | Reserved for future use.
CHANNEL_OPTION_PRI_HIGH | Reserved for future use.
CHANNEL_OPTION_PRI_LOW | Reserved for future use.
CHANNEL_OPTION_PRI_MED | Reserved for future use.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Pchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Structures, VirtualChannelInit, VirtualChannelWrite


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 pass this structure.

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

Members

cbSize
Size, in bytes, of this structure.
protocolVersion
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.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Cchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Structures, 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, *PCHANNEL_PDU_HEADER;

Members

length
Size, in bytes, of the data block, excluding this header.
flags
Information about the data block. The following bit flags will be set. Do not make direct comparisons using the '==' operator; use the methods described in the following table to compare the corresponding flag value.
Value Meaning
CHANNEL_FLAG_FIRST The chunk is the beginning of the data written by a single write operation.

Use bitwise comparisons when comparing this flag.
CHANNEL_FLAG_LAST The chunk is the end of the data written by a single write operation.

Use bitwise comparisons when comparing this flag.
CHANNEL_FLAG_MIDDLE This is the default. The chunk is in the middle of a block of data written by a single write operation.

Do not use bitwise comparisons to compare this flag value directly. Instead, use bitwise comparisons to determine that the flag value is not CHANNEL_FLAG_FIRST or CHANNEL_FLAG_LAST. This is done by using the following comparison: Result = !(flags & CHANNEL_FLAG_FIRST) && !(flags & CHANNEL_FLAG_LAST).
CHANNEL_FLAG_ONLY Combines the CHANNEL_FLAG_FIRST and CHANNEL_FLAG_LAST values. The chunk contains all the data from a single write operation.

Use bitwise comparisons when comparing this flag.

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.

Requirements

Version: Requires RDP 5.0 client.
Header: Declared in Pchannel.h.

See Also

Terminal Services API Overview, Terminal Services API Structures, 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
Address family. This member can be AF_INET, AF_IPX, AF_NETBIOS, or AF_UNSPEC.
Address
Client network address.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
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
Terminal Services session identifier for the session associated with the process.
ProcessId
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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Unicode: Declared 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
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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Terminal Services API Overview, Terminal Services API Structures, WTSEnumerateSessions


WTSSESSION_NOTIFICATION

The WTSSESSION_NOTIFICATION structure provides information about the session change notification. A service receives this structure in its HandlerEx function in response to a session change event.

typedef struct tagWTSSESSION_NOTIFICATION{
  DWORD cbSize;
  DWORD dwSessionId;
} WTSSESSION_NOTIFICATION, *PWTSSESSION_NOTIFICATION;

Members

cbSize
Size, in bytes, of this structure.
dwSessionId
Session identifier that triggered the session change event.

Requirements

Version: Requires Whistler.
Header: Declared in Winuser.h; include Windows.h.

See Also

Terminal Services API Overview, Terminal Services API Structures, HandlerEx


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_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;

Enumeration 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 value 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 value 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 value that specifies the maximum connection duration, in milliseconds. 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 value that specifies the maximum duration, in milliseconds, 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 value that specifies the maximum idle time, in milliseconds. 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: A value 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 value 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 value 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 value 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 value 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: A 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: A null-terminated string containing the phone number to use for callback connections.
WTSUserConfigShadowingSettings
RDP 5.0 clients and Citrix ICA clients: A value 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 | Disable
1 | Enable input, notify
2 | Enable input, no notify
3 | Enable no input, notify
4 | Enable no input, no notify

WTSUserConfigTerminalServerProfilePath
A null-terminated string containing the path of the user's profile for terminal server logon. The directory the path identifies must be created manually, and must exist prior to the logon. WTSSetUserConfig will not create the directory if it does not already exist.
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 value that indicates whether the user's home directory for terminal server logon is a local path or a mapped drive letter. Note that this value cannot be used with WTSSetUserConfig.
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.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
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;

Enumeration 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. A listener session waits to requests for new client connections. No user is logged on a listener session. A listener session cannot be reset, shadowed, or changed to a regular client session.
WTSReset
The WinStation is being reset.
WTSDown
The WinStation is down due to an error.
WTSInit
The WinStation is initializing.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
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,
  WTSClientProtocolType
} WTS_INFO_CLASS;

Enumeration 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.
WTSClientProtocolType
Information about the session type.

Requirements

Version: Requires Windows 2000 or later (or Terminal Server 4.0 SP4).
Header: Declared in Wtsapi32.h.

See Also

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


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.