Terminal Server API

2. Terminal Server API Bernhard Tritsch

3. About Bernhard Tritsch • Author of Microsoft Windows Server 2003 Terminal Services (Microsoft Press) • visionapp’s Chief System Architect • Microsoft Most Valuable Professional (MVP) Windows Server – Terminal Server • Citrix Technology Professional • Author of www.wtstek.com BriForum Europe 2006

4. Contents BriForum Europe 2006

5. Terminal Server Scripting • Most system and terminal server settings are accessible via scripts • TS WMI provider supplies access to configuration and connections information • ADSI Extension for Terminal Services user configuration to automate maintenance of Terminal Services-specific user properties • Microsoft Windows Server 2003 Script Center: http://www.microsoft.com/technet/scriptcenter/hubs/win2003.mspx BriForum Europe 2006

6. ' WMI Scripting Example ' Modify Terminal Services Home Directory strComputer = "." Set objWMIService = GetObject("winmgmts:" _ & "{impersonationLevel=impersonate}\\„ _ & strComputer & "\root\cimv2") Set colItems = objWMIService.ExecQuery _ ("Select * from Win32_TerminalServiceSetting") For Each objItem in colItems errRes = objItem.SetHomeDirectory("u:\tsusers") Next BriForum Europe 2006

7. Introducing the TS API • Terminal Services API is a set of function calls into Wtsapi32.dll • The TS API functions allow for the configuration and management of terminal servers from custom applications BriForum Europe 2006

8. Introducing the TS API • Wtsapi32.dll is present on • Microsoft Windows NT Server 4.0 SP4, Terminal Server Edition • Microsoft Windows 2000 • Microsoft Windows XP • Microsoft Windows Server 2003 • The API functions do not work on other Windows platforms BriForum Europe 2006

9. System-wide User Sessions Wtsapi32.dll TS API Applications Terminal Server Service Winlogon Per- Session Apps User Mode Rdpwsx Smss Csrss Terminal Server Device Driver Termdd.sys Win32k.sys Kernel Mouse, Keyboard Kernel Mode Rdpwd.sys Rdpdd.sys Display Driver Tdtcp.sys Video BriForum Europe 2006

10. Analyzing Wtsapi32.dll • You can list function names for Wtsapi32.dll by running some tools provided with Microsoft Visual Studio • Microsoft Binary File Dumper: “dumpbin –exports wtsapi32.dll” • Microsoft Linker: “link /dump /exports wtsapi32.dll” • Dependency Walker Depends.exe BriForum Europe 2006

11. Analyzing Wtsapi32.dll BriForum Europe 2006

12. TS API Functions [1/2] BriForum Europe 2006

13. TS API Functions [2/2] BriForum Europe 2006

14. Visual Studio with Platform SDK includes the Terminal Services API Requirements for programming the TS API in C Function headers are declared in Wtsapi32.h Add “Wtsapi32.lib” to Configuration Properties | Linker | Command Line | Additional Options Change Configuration Properties | General | Character Set to “Use Multi-Byte Character Set” Change Configuration Properties | C/C++ | Advanced | Compile As to “Compile as C Code (/TC)” Change Configuration Properties | C/C++ | Code Generation | Runtime Library to “Multi-Threaded Debug (/MTd)” or “Multi-Threaded (/MT)” BriForum Europe 2006

15. TS Programming Principles • Retrieve the names of the required terminal servers • Open a handle to a specific terminal server • Perform the required tasks, such as enumerating and managing user sessions or processes • Free allocated resources, such as buffers • Close the open handle to the terminal server BriForum Europe 2006

16. #include <stdio.h> #include <windows.h> #include <wtsapi32.h> int main(int argc, char* argv[]) { char* pszServerName = NULL; HANDLE serverHandle; PWTS_PROCESS_INFO pProcessInfo; serverHandle = WTSOpenServer(pszServerName); // more TS specific code WTSFreeMemory(pProcessInfo); WTSCloseServer(serverHandle); } BriForum Europe 2006

17. Demo Programming the TS API in C/C++ BriForum Europe 2006

18. Solution: TsConsole Sandwich programming style BriForum Europe 2006

19. Using the TS API from .NET? • The Terminal Services API is designed for use by C/C++ programmers → unmanaged code • Programming the TS API with C/C++ is not easy, C# or VB.NET should be a lot better • Challenge: The TS API is not exposed through a .NET standard class • However, it is possible to use the TS API from applications based on the .NET Framework through Platform Invoke (Pinvoke) BriForum Europe 2006

20. TS API P/Invoke Wrapper • Platform Invoke is a service that enables managed code to call unmanaged functions implemented in dynamic link libraries • Within a class, you define a static method for each DLL function you want to call • Once wrapped, you can call methods on the function as you call methods on any other static function [DllImport("wtsapi32.dll")] public static extern IntPtr WTSOpenServer(String strServername); BriForum Europe 2006

21. using System; using System.Runtime.InteropServices; using HANDLE = System.IntPtr; namespace TsNET { class Program { static void Main(string[] args) { HANDLE hServer = IntPtr.Zero; String strServername = null; hServer = WTS.WTSOpenServer(strServername); WTS.WTSCloseServer(hServer); } } } BriForum Europe 2006

22. Demo TS API Wrapper using Platform Invoke BriForum Europe 2006

23. C# console app BriForum Europe 2006

24. Interop BriForum Europe 2006

25. Using the results BriForum Europe 2006

26. Virtual Channels • VCs add functional enhancements to TS • Client-side component • DLL that must be loaded into memory on the client computer when the Terminal Services client program runs • Server-side component • User-mode application running in a client session on the terminal server • The virtual channel application can be started by login script, by Startup folder or by the user BriForum Europe 2006

27. Remote Desktop Client Mstscax.dll Virtual Channel: Additional Features RDP Terminal Server Wtsapi32.dll BriForum Europe 2006

28. TS Client Terminal Server TS Client Application Wtsapi32.dll TS API Applications TS Service Winlogon Per- Session Apps Rdpwsx Smss Csrss Mstscax.dll Terminal Server Device Driver Termdd.sys Win32k.sys Kernel Network Protocol Stack Rdpwd.sys Rdpdd.sys Display Driver Tdtcp.sys BriForum Europe 2006

29. Taking advantage of the client-side Remote Desktop ActiveX Control from a .NET Windows Forms application • Use the OLE/COM Object Viewer Oleview.exe to find out about the functions exposed • Windows Forms ActiveX Control Importer Aximp.exe converts type definitions in a COM type library for an ActiveX control into a Windows Forms control • “Aximp c:\Windows\system32\mstscax.dll” generates assemblies Mstsclib.dll and Axmstsclib.dll for the RDP client ActiveX control Mstscax.dll • Add a reference to these DLLs to the TS client project BriForum Europe 2006

30. OLE/COM Object Viewer Oleview BriForum Europe 2006

31. using AxMSTSCLib; ... private AxMsRdpClient m_msTsc; ... public RDPClientForm() { m_msTsc = new AxMsRdpClient(); m_msTsc.Dock = DockStyle.Fill; Controls.Add(m_msTsc); InitializeComponent(); } ... ServerForm srvForm = new ServerForm(); if (srvForm.ShowDialog() != DialogResult.OK) return; m_msTsc.Server = srvForm.ServerName; m_msTsc.Connect(); BriForum Europe 2006

32. Virtual Channel Programming • Client side • Create virtual channel: m_msTsc.CreateVirtualChannels("VCD"); • Send on virtual channel m_msTsc.SendOnVirtualChannel("VCD", "Message“); • Server side • TS API wrapper class used for the required unmanaged functions BriForum Europe 2006

33. Virtual Channels – Server BriForum Europe 2006

34. Demo Virtual Channel Programming BriForum Europe 2006

35. Object Browser provided by Visual Studio BriForum Europe 2006

36. Client side BriForum Europe 2006

37. Server side BriForum Europe 2006

38. Summary • The terminal server API provides powerful functions to extend standard TS tools and to enhance TS functionalities • Microsoft decided not to publish good examples for TS API programming – heaven knows why... • For an introduction into the TS API check out http://msdn.microsoft.com/library/en-us/termserv /termserv/terminal_services_start_page.asp BriForum Europe 2006