Notes on wtsapi32.dll

This document is simply bits and pieces of information I am assembling as I look at wrapping the APIs from Terminal Server for easy use in VB applications (and eventually, scripting). 

Warnings for Scripting

An initial caveat about scripted use of the final product is in order.  Several portions of the API (such as the functions which support channels) are  well-suited to use in VB applications; when used within sessions, they are unlikely to produce the problems which VB applications running as services can have.

Unfortunately, the use of them within sessions also means that each component will typically be in  a separate user session.  This immediately means that there will be significant session overhead while a script is actively executing.

Furthermore, the traditional techniques for keeping a script running if it is sinking events can then produce problems if they are not done correctly.  Below are some tips for running scripts on TS.  These apply to any script run within a TS session.

  1. Use a Duty Cycle in Loops
    If you are going to use a loop to monitor a condition or keep your script alive while waiting for a sinkable event, make sure you have a lightweight duty cycle - lots of "downtime" while waiting.  For example, here is VBScript code for a loop used to pause a script while a controlled Internet Explorer session is loading a page:
    Do While oIE.ReadyState<>4:WScript.Sleep 50:Loop
    The first mistake many people make is to not have a Sleep in the loop at all.  The second is to make the duty cycle too short.  Although 10 ms would probably be fine, due to interface update lag and the generally slower execution in scripting overall, a duty cycle of at least 50 ms is even better on TS.  The extra 40 ms that a user *might* wait on the last pass is insignificant compared to the fact that you are reducing CPU load over 80% on this portion of the cycle.
  2. Exit If Possible
    It is best to exit a process early on if at all possible.  For example, if you want to transfer special session data via channels when people log on, you might as well use script; it will only be active a few seconds. 
  3. If It Keeps Going, Use VB
    If you want to write a new, improved RdpClip, put it in VB.  Even if you test initially in script, you can quickly port VBScript code to VB, making it run faster and making everyone happier.

TS API Wrappers

I am just beginning to write these [2002.08.30] so expect chaos and changes for a while.

Constants

This is my initial set of constants for use in VB.  They were pulled from the November 2001 Platform SDK release versions of wtsapi32.h, cchannel.h, and pchannel.h.

Enums

Enumerations pulled from the Platform SDK documentation files directly

Types

Types pulled from the Platform SDK documentation of TS API structures.

Function Wrappers

Fellow Travellers

This will contain wrapping information for functions such as the GetSystemMetrics calls which are a necessity for effective detection of remote computing environments.

Functions Exported from WTSAPI32.DLL

The following list was pulled from viewing wtsapi32.dll version 5.0.2134.1 in Dependency Walker.  These are the undecorated function names.

WTSCloseServer
WTSDisconnectSession
WTSEnumerateProcessesA
WTSEnumerateProcessesW
WTSEnumerateServersA
WTSEnumerateServersW
WTSEnumerateSessionsA
WTSEnumerateSessionsW
WTSFreeMemory
WTSLogoffSession
WTSOpenServerA
WTSOpenServerW
WTSQuerySessionInformationA
WTSQuerySessionInformationW
WTSQueryUserConfigA
WTSQueryUserConfigW
WTSSendMessageA
WTSSendMessageW
WTSSetSessionInformationA
WTSSetSessionInformationW
WTSSetUserConfigA
WTSSetUserConfigW
WTSShutdownSystem
WTSTerminateProcess
WTSVirtualChannelClose
WTSVirtualChannelOpen
WTSVirtualChannelPurgeInput
WTSVirtualChannelPurgeOutput
WTSVirtualChannelQuery
WTSVirtualChannelRead
WTSVirtualChannelWrite
WTSWaitSystemEvent