Scripting the Terminal Services Advanced Client

Article
06/29/2006

Nadim Abdo and Jay French
Microsoft Corporation

June 2000

Summary: Provides details for implementing scriptable virtual channels in a Terminal Services Web application, and also includes preliminary documentation for the Terminal Services ActiveX Client Control properties and methods. (29 printed pages)

Introduction Implementing Scriptable Virtual Channels with the TSAC Terminal Services ActiveX Client Control Properties and Methods Secured Settings Interface Secured Settings Interface Methods IMsTscAx Interface Methods Events Interface IMsTscAdvancedSettings Interface The IMsTscNonScriptable Interface

Introduction

Microsoft® Terminal Services technology is a powerful tool for enterprises wanting to reduce their total cost of operation and provide centralized application deployment across the organization. With the release of the Terminal Services Advanced Client (TSAC) as a ValueAdd component on Microsoft Windows® 2000 Server, Service Pack 1, the Terminal Services solution is now extended to the Web. For example, organizations needing to deploy line of business applications to remote offices can do so by means of a Terminal server and a Web server running ASP pages, such as the sample pages supplied with the TSAC. On the client side, all that is needed is Internet Explorer, a connection to the World Wide Web, and appropriate access rights.

This article provides details for implementing scriptable virtual channels in a Terminal Services Web application, and also provides preliminary documentation for the Terminal Services ActiveX® Client Control properties and methods. The article does not discuss the properties and methods in detail, but it does give a preview of their use and function. For more information about deploying the Terminal Services Active X Client control, see the Microsoft® Terminal Services ActiveX® Client Control Deployment Guide, which is included with the TSAC. For more information about creating and deploying virtual channel applications, see the Terminal Services Virtual Channels section of the Platform SDK. You can also download the control. For information about implementing and using the TSAC, including redistribution, read the TSAC Frequently Asked Questions document.

Implementing Scriptable Virtual Channels with the TSAC

Virtual channels technology provides the means for organizations to extend the Terminal Services Remote Desktop Protocol (RDP) to incorporate functional enhancements needed for a specific application. These enhancements might include support for special types of hardware, redirection of data types beyond those which can be redirected using methods provided in the core protocol, and so on.

A virtual channel application has two parts, a client side and a server side. The server side is an executable program running on the Terminal server. Prior to the release of the Terminal Services Advanced Client, implementing virtual channels applications on the client side required developers to create and register a client Dynamic Link Library (DLL), which had to be loaded into memory on the client computer when 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. Examples are in VBScript and assume that the Terminal Services ActiveX Client Control is named MsTsc.

To create and deploy scriptable virtual channels

Deploy the server side of the application, and make sure it is running on the Terminal server.
In your client script, call CreateVirtualChannels, passing a string that contains a comma-separated list of virtual channel names.
```
IMsTscAx::CreateVirtualChannels (BSTR channelNameList)
```
For example:
```
MsTsc.CreateVirtualChannels("mychan1,mychan2")
```
Read the Terminal Services Virtual Channels article for information on virtual channel naming restrictions.
Call Connect to create your Terminal Services connection.
```
MsTsc.connect
```
Use the 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.
```
IMsTscAx::SendOnVirtualChannel(BSTR channelName,BSTR dataToSend)
```
For example:
```
MsTsc.SendOnVirtualChannel("mychan1","hello from the client")
```

Receive data from the server on the OnChannelReceivedData event.

void IMsTscAxEvents::OnChannelReceivedData([in]BSTR chanName,[in]BSTR data)

For example:

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

Terminal Services ActiveX Client Control Properties and Methods

The Terminal Services ActiveX Client Control contains four scriptable interfaces.

IMsTscSecuredSettings interface
IMsTscAx interface
IMsTscAxEvents interface
IMsTscAdvancedSettings interface

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

Secured Settings Interface

Notes on using the Secured Settings Interface properties

For security reasons, some properties of the Terminal Services ActiveX Client Control object are restricted to certain Internet Explorer security zones. This means that when a user browsing the Web accesses the page from a computer in a less secure zone, these properties are disabled. These restricted properties are contained in the Secured Settings Interface. They 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 use the following ActiveX Client Control properties to check for and access Secured Settings properties:

SecuredSettingsEnabled: Returns a BOOL indicating whether or not the secured settings are accessible.
SecuredSettings: Returns the Secured Settings Interface. Returns failure if the page containing the control is not in one of the allowed zones.

The following sample VBScript can be used to launch Microsoft Notepad upon connection. It should be called before the Connect method is called.

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

Note that if the terminal services control is not hosted in a web browser (that is, if it is hosted in a VB app) the secured settings interface is always available.

Secured Settings Interface Methods

IMsTscSecuredSettings::put_StartProgram method

This method is used to specify which program to start on the remote server upon connection.

Syntax:

HRESULT put_StartProgram(BSTR startProgram);

Parameters: StartProgram is the path to the program to start on the remote server.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: See Notes on using the Secured Settings Interface properties for information about using this method.

IMsTscSecuredSettings::get_StartProgram method

This method retrieves the currently set StartProgram property.

Syntax:

HRESULT get_StartProgram(BSTR* pStartProgram);

Parameters: pStartProgram is a pointer to a BSTR that receives the StartProgram property.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: See Notes on using the Secured Settings Interface properties for information about using this method.

IMsTscSecuredSettings::put_WorkDir method

This method specifies the current working directory if a starting program is set with StartProgram.

Syntax:
```
HRESULT put_WorkDir(BSTR workDir);
```
Parameters: WorkDir is the path to the working directory.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: See Notes on using the Secured Settings Interface properties for information about using this method.

IMsTscSecuredSettings::get_WorkDir method

This method retrieves the WorkDir property.

Syntax:
```
HRESULT get_WorkDir(BSTR* pWorkDir);
```
Parameters: pWorkDir is a pointer to a BSTR variable that receives the path to the working directory for the start program.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: See Notes on using the Secured Settings Interface properties for information about using this method.

IMsTscSecuredSettings::put_FullScreen method

This method sets the FullScreen mode for the client control.

Syntax:

HRESULT put_FullScreen(BOOL fullScreen);

Parameters: FullScreen is a VARIANT_BOOL value that toggles the control to FullScreen mode if it is true or out of FullScreen mode if set to false.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Specifies the FullScreen/windowed state of the control upon connection. Set to TRUE to open the connection in FullScreen mode. See Notes on using the Secured Settings Interface properties for information about using this method. Note that although the use of the FullScreen property is restricted to the allowed IE security zones, a user can always change to FullScreen mode, after the connection has been established, by pressing CTRL+ALT+BREAK.

IMsTscSecuredSettings::get_FullScreen method

This method retrieves the FullScreen state of the client control.

Syntax:

HRESULT get_FullScreen(BOOL* pFullScreen);

Parameters: pFullScreen is a pointer to a VARIANT_BOOL value that receives the current FullScreen mode for the control. Set to TRUE if fullscreen or FALSE otherwise.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: See Notes on using the Secured Settings Interface properties for information about using this method.

IMsTscAx Interface Methods

IMsTscAx::put_Server method

This method sets the name of the server to which to connect. This can also be an IP address.

Syntax:
```
HRESULT put_Server(BSTR Server);
```
Parameters: The server name to connect to, this can be a DNS name or an IP address.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This property must be set before the Connect method is called. It is the only required 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 get_Connected method.

IMsTscAx::get_Server method

This method retrieves the server property.

Syntax:
```
HRESULT get_Server(BSTR* pServer);
```
Parameters: pServer is a pointer to a BSTR that receives the server property.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::put_Domain method

This method sets the domain to which the specified user logs on.

Syntax:
```
HRESULT put_Domain(BSTR Domain);
```
Parameters: Domain is the domain to which the specified user logs on
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This property is optional. If it is not specified the user can choose a domain when the Windows Logon dialog box appears at connection time.

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 get_Connected method.

IMsTscAx::get_Domain method

This method retrieves the domain property.

Syntax:
```
HRESULT get_Domain(BSTR* pDomain);
```
Parameters: pDomain is a pointer to a BSTR that receives the domain property.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::put_UserName method

This method sets the username for logon.

Syntax:
```
HRESULT put_UserName(BSTR UserName);
```
Parameters: The UserName for logon.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This property is optional. If it is not specified, the user can provide a username when the Windows Logon dialog box appears at connection time.

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 get_Connected method.

IMsTscAx::get_UserName method

This method retrieves the username property.

Syntax:
```
HRESULT get_UserName(BSTR* pUserName);
```
Parameters: pUserName is a pointer to a BSTR that receives the value of the UserName property.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::put_DisconnectedText method

This method sets the DisconnectedText property. This is a text string that appears centered in the control before a connection is established.

Syntax:

HRESULT put_DisconnectedText(BSTR DisconnectedText);

Parameters: DisconnectedText is the text to be displayed centered in the control after it has been disconnected, this can be a helpful status message (e.g., “Disconnected from server”).
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This 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. It returns E_FAIL if it is called when the control is connected. You can check for the connected state by using the get_Connected method.

IMsTscAx::get_DisconnectedText method

This method retrieves the DisconnectedText property.

Syntax:

HRESULT get_DisconnectedText(BSTR* pDisconnectedText);

Parameters: pDisconnectedText is a pointer to a BSTR that retrieves the disconnected text property. The default value of this property is an empty string.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::put_ConnectingText method

This method sets the ConnectingText property. This is a text string that appears centered in the control while the control is connecting. For example, a status message such as "Connecting to server…" can be displayed.

Syntax:

HRESULT put_ConnectingText(BSTR ConnectingText);

Parameters: ConnectingText is the text to be displayed centered in the control before a connection is established.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This 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. It returns E_FAIL if it is called when the control is connected. You can check for the connected state by using the get_Connected method.

IMsTscAx::get_ConnectingText method

This method retrieves the ConnectingText property.

Syntax:

HRESULT get_ConnectingText(BSTR* pConnectingText);

Parameters: pConnectingText is a pointer to a BSTR that receives the value of the connecting text property.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::get_Connected method

This method retrieves the Connected property.

Syntax:

HRESULT get_Connected(short* pConnected);

Parameters: pConnected is the address of a short variable that is set to "1" if the control is in the connected state or is set to "0" otherwise.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: The preferred way to determine the control's connection state is to respond to the connection events in IMsTscAxEvents.

IMsTscAx::put_DesktopWidth method

This method sets the control's initial remote desktop width in pixels. Setting this 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 remote desktop width. Instead, the control brings up scroll bars or centers the remote desktop, as appropriate.

Syntax:

HRESULT put_DesktopWidth(LONG desktopWidth);

Parameters: DesktopWidth is a LONG value that specifies the desktop width in pixels. The minimum value is 200 pixels; the maximum value is 1600 pixels. DesktopWidth must be specified in a value that is a multiple of 4 pixels (otherwise, the control automatically sets the desktop width to the nearest multiple of 4 pixels).
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: 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 get_Connected method.

IMsTscAx::get_DesktopWidth method

This method retrieves the current remote desktop width.

Syntax:

HRESULT get_DesktopWidth(LONG* pDesktopWidth);

Parameters: pDesktopWidth is the address of a LONG variable that receives the current remote DesktopWidth in pixels.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::put_DesktopHeight method

This method sets the control's initial remote desktop height in pixels. Setting this 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 remote desktop height. Instead, the control brings up scroll bars or centers the remote desktop as appropriate.

Syntax:

HRESULT put_DesktopHeight(LONG desktopHeight);

Parameters: DesktopHeight is the LONG value that specifies the desktop height in pixels. The minimum value is 200 pixels; the maximum value is 1200 pixels.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: 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 get_Connected method.

IMsTscAx::get_DesktopHeight method

This method retrieves the current remote desktop height.

Syntax:

HRESULT get_DesktopHeight(LONG* pDesktopHeight);

Parameters: pDesktopHeight is the address of a LONG variable that receives the current remote desktop height in pixels.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::put_StartConnected method

This method specifies that the control should establish the Terminal server connection immediately upon instantiation. This property is most useful when the control properties are set in the parameter list of an <OBJECT> tag, rather than through script calls.

Syntax:

HRESULT put_StartConnected(BOOL startConnected);

Parameters: StartConnected is a VARIANT_BOOL variable: set to TRUE to indicate that the control should connect immediately on startup.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: 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 instantiates (for example, by including it in the parameter list of an <object> tag when using the control from a Web page).

IMsTscAx::get_StartConnected method

This method retrieves the StartConnected property.

Syntax:

HRESULT get_StartConnected(BOOL* pStartConnected);

Parameters: pStartConnected is the address of a VARIANT_BOOL variable that receives the StartConnected property. This variable defaults to FALSE.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::get_HorizontalScrollBarVisible method

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

Syntax:

HRESULT get_HorizontalScrollBarVisible(BOOL* pSBVisible);

Parameters: pSBVisible is the address of a VARIANT_BOOL variable that is set to TRUE if the horizontal scroll bar is visible.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: The control automatically displays a horizontal scroll bar if the control's width becomes less than the desktop width.

IMsTscAx::get_VerticalScrollBarVisible method

This method retrieves a Boolean value that indicates whether or not the control has displayed a vertical scroll bar.

Syntax:

HRESULT get_VerticalScrollBarVisible(BOOL* pSBVisible);

Parameters: pSBVisible is the address of a VARIANT_BOOL variable that is set to TRUE if the vertical scroll bar is visible.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: The control automatically displays a vertical scroll bar if the control's height becomes less than the desktop height.

IMsTscAx::put_FullScreenTitle method

This method sets the window title that appears when the control is in FullScreen mode.

Syntax:

HRESULT put_FullScreenTitle(BSTR fullScreenTitle);

Parameters: fullScreenTitle is a string that specifies the window title of the FullScreen client window.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This property is used to set the title of the control's window when the connection is opened in FullScreen mode. Do not use this property for container-handled FullScreen mode. When the ContainerHandledFullScreen method is used, the container window is responsible for displaying the window title. See the IMsTscAxAdvancedSettings::put_ContainerHandledFullScreen method for more information.

IMsTscAx::get_CipherStrength method

This method retrieves the encryption strength of the control. For the TSAC, this 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 TS servers.

Syntax:

HRESULT get_CipherStrength(LONG* pCipherStrength);

Parameters: pCipherStrength is the address of a LONG variable that receives the maximum encryption strength of the control.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::get_Version method

This method retrieves a version string for the control.

Syntax:
```
HRESULT get_Version(BSTR* pVersion);
```
Parameters: pVersion is the address of a string (BSTR) that receives the version of the control. The caller frees this buffer with the SysFreeString function.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::get_SecuredSettingsEnabled method

This method retrieves a Boolean value indicating whether or not the secured settings interface is available (that is, if the page containing the control is currently in one of the allowed Internet Explorer security zones). See Notes on using the Secured Settings Interface properties for a list of allowed and disallowed Security Zones.

Syntax:

HRESULT get_SecuredSettingsEnabled(BOOL* pSecuredSettingsEnabled);

Parameters: pSecuredSettingsEnabled is the address of a VARIANT_BOOL variable that is set to TRUE if the secured settings interface is available.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Use this method to query whether or not the SecuredSettings interface is available before calling the get_SecuredSettings method.

IMsTscAx::get_SecuredSettings method

This method retrieves the SecuredSettings interface (IMsTscSecuredSettings). See get_SecuredSettingsEnabled for restrictions on when this interface is available.

Syntax:

HRESULT get_SecuredSettings (IMsTscSecuredSettings** ppSecuredSettings);

Parameters: ppSecuredSettings is a pointer to a pointer set to the address of the control's IMsTscSecuredSettings interface.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Note that if the control is hosted in a Web page and the current Internet Explorer security zone does not allow retrieving this interface (see get_SecuredSettingsEnabled), this call returns E_FAIL.

IMsTscAx::get_AdvancedSettings method

This method retrieves the AdvancedSettings interface (IMsTscAdvancedSettings).

Syntax:

HRESULT get_AdvancedSettings (IMsTscAdvancedSettings** ppAdvancedSettings);

Parameters: ppAdvancedSettings is a pointer to a pointer set to the address of the control's IMsTscAdvancedSettings interface.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAx::Connect method

This method initiates a connection that uses the current properties that have been set on the control. The only required property is the server name (see put_Server).

Syntax:
```
HRESULT Connect ();
```
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Note that 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.

Note also that after Connect has been called, most of the control properties can no longer be set (they return FAILURE) until the control is back in the disconnected state.

The minimum set of method calls necessary for a successful connection is put_Server followed by Connect.

If the DesktopWidth/DesktopHeight properties are not specified, the control sets the initial desktop width and height to the dimensions of the control at connect time.

IMsTscAx::Disconnect method

This method disconnects the active connection.

Syntax:
```
HRESULT Disconnect ();
```
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This method returns a failure if it is called when the control is not connected. It is also possible to disconnect the control by merely closing its main window. In other words, if the control is hosted in a Web page, it is not necessary to call the disconnect method before leaving the page; the closing of the control triggers a disconnection.

IMsTscAx::CreateVirtualChannels method

This method creates a client-side virtual channel object for each virtual channel name specified in the channelNameList. (See Implementing Scriptable Virtual Channels with TSAC.)

Syntax:

HRESULT CreateVirtualChannels (BSTR channelNameList);

Parameters: channelNameList is a comma-separated list of valid virtual channel names.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This method should be called before Connect. Read the Terminal Services Virtual Channels article for information about virtual channel naming restrictions.

IMsTscAx::SendOnVirtualChannel method

This method is used to send data to the server over a virtual channel that has been previously created with the CreateVirtualChannels method.

Syntax:

HRESULT SendOnVirtualChannel (BSTR channelName,BSTR dataToSend);

Parameters: channelName is a virtual channel name that was specified in the call to CreateVirtualChannels.
DataToSend: is data in BSTR form (not restricted to just a NULL terminated string) that is to be sent over the virtual channel.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Read the Terminal Services Virtual Channels article for information about virtual channel naming restrictions.

Events Interface

IMsTscAxEvents::OnConnecting method

This event is called when the client control begins connecting to a server in response to a Connect method call.

Syntax:
```
HRESULT OnConnecting ();
```
Return Value: Returns S_OK if successful or an error value otherwise.
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 VBScript code (assuming your control object is named MsTsc.)
```
Sub MsTsc.OnConnecting()
   Msgbox("Connecting”)
End sub
```

IMsTscAxEvents::OnConnected method

This event is called when the client control has established a connection with a terminal server. At the point the event has fired login has not yet completed. See the OnLoginComplete event for more information.

Syntax:
```
HRESULT OnConnected ();
```
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Implement this method in your event sink to receive notification that the control has established a connection with a terminal server.

IMsTscAxEvents::OnLoginComplete method

This event is called when the client control has successfully logged on to a terminal server (following the Windows Logon dialog box).

Syntax:
```
HRESULT OnLoginComplete();
```
Return Value: Returns S_OK if successful or an error value otherwise.
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 VBScript code (assuming your control object is named MsTsc.)
```
Sub MsTsc.OnLoginComplete()
   Msgbox("Login has completed”)
End sub
```

IMsTscAxEvents::OnDisconnected method

This event is called when the client control has been disconnected from the terminal server.

Syntax:

HRESULT OnDisconnected(long disconnectReason);

Parameters: DisconnectReason is a long value that specifies the reason for the disconnection. The following is a list of error codes:

1	Local Disconnection (not an error)
2	Remote Disconnection by user (not an error)
3	Remote Disconnection by server (not an error)
260	DNS Lookup Failed
262	Out of memory condition
264	Connection Timed Out
516	WinSock socket connect failed
518	Out of memory condition
520	Host Not Found error (GetHostByName failed).
772	WinSock send call failed
774	Out of memory condition
776	Invalid IP address specified
1028	WinSock recv call failed
1030	Invalid Security Data
1032	Internal error (code 1032)
1286	Invalid Encryption Method
1288	DNS Lookup failed
1540	GetHostByName call failed
1542	Invalid server security data
1544	Internal Error (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 Value: Returns S_OK if successful or an error value otherwise.

IMsTscAxEvents::OnEnterFullScreenMode method

This event is called when the client enters FullScreen mode; for example, when the user presses the FullScreen mode shortcut key combination (CTRL + ALT + BREAK).

Syntax:
```
HRESULT OnEnterFullScreenMode();
```
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAxEvents::OnLeaveFullScreenMode method

This event is called when the client leaves FullScreen mode; for example, when the user presses the FullScreen mode shortcut key combination (CTRL + ALT + BREAK).

Syntax:
```
HRESULT OnLeaveFullScreenMode();
```
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAxEvents::OnChannelReceivedData method

This event is called when the client receives data on a scriptable virtual channel.

Syntax:

HRESULT OnChannelReceivedData(BSTR chanName, BSTR data);

Parameters: chanName is a BSTR that indicates the name of the virtual channel on which data was received. Data is a BSTR that contains the data received on the scriptable virtual channel. This name matches one of the channels created in the CreateVirtualChannels call.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: See Implementing Scriptable Virtual Channels with the TSAC for more information about this event.

IMsTscAxEvents::OnRequestGoFullScreen method

This event is called when the client requests to switch to FullScreen mode and the IMsTscAdvancedSettings::put_ContainerHandledFullScreen property is set. See IMsTscAdvancedSettings::put_ContainerHandledFullScreen for more information about this event.

Syntax:
```
HRESULT OnRequestGoFullScreen();
```
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: In container-handled FullScreen mode, the container should enter FullScreen mode in response to this event.

IMsTscAxEvents::OnRequestLeaveFullScreen method

This event is called when the client requests to leave FullScreen mode and the IMsTscAdvancedSettings::put_ContainerHandledFullScreen property is set. See IMsTscAdvancedSettings::put_ContainerHandledFullScreen for more information about this event.

Syntax:
```
HRESULT OnRequestLeaveFullScreen();
```
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: In container-handled FullScreen mode, the container should leave FullScreen mode in response to this event.

IMsTscAxEvents::OnFatalError method

This event is called when the client control encounters a fatal error. In response to this event, the container displays an error message and shuts down.

Syntax:
```
HRESULT OnFatalError(long errorCode);
```

Parameters: ErrorCode is a long value that indicates the error code. The following values are possible error codes:

Value	Meaning
0	An unknown error has occurred
1	Internal error code 1
2	Out of memory error
3	Window creation error
4	Internal error code 2
5	Internal error code 3 (Invalid state)
100	Winsock initialization error

Return Value: Returns S_OK if successful, or an error value otherwise.

IMsTscAxEvents::OnWarning method

This event is called when the client control encounters a non-fatal error.

Syntax:
```
HRESULT OnWarning(long warningCode);
```
Parameters: warningCode is a long value that indicates the error code. The following values are possible warning codes:

Value Meaning

1 Bitmap cache corrupted warning
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAxEvents::OnRemoteDesktopSizeChange method

This event is called to indicate the client control's remote desktop size has changed in response, for example, to shadowing a session with a different resolution.

Syntax:

HRESULT OnRemoteDesktopSizeChange (long width, long height);

Parameters: Width is the width in pixels of the new remote desktop size. Height is the height in pixels of the new remote desktop size.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This event allows the container to determine if it must resize itself in response to a shadow operation (which could result in a larger viewable desktop size). Note that the control will automatically adjust scroll bars for the new session size.

IMsTscAdvancedSettings Interface

IMsTscAdvancedSettings::put_Compress method

This method enables or disables compression.

Syntax:
```
HRESULT put_Compress (long compress);
```
Parameters: compress is a LONG value. Compression is disabled if set to 0 or enabled if set to any other value.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::get_Compress method

This method retrieves the compression property.

Syntax:

HRESULT get_Compress (long* pCompress);

Parameters: PCompress is a pointer to a LONG value that receives the compression-enabled status (1 for enabled, 0 otherwise).
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::put_BitmapPeristence method

This method enables or disables bitmap caching. Note the misspelling of the method and its parameter in the released version of the control.

Syntax:

HRESULT put_BitmapPeristence (long bitmapPeristence);

Parameters: bitmapPeristence is a LONG value. Bitmap caching is disabled if set to 0 or enabled if set to any other value.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::get_BitmapPeristence method

This method retrieves the BitmapPeristence property. Note the misspelling of the method and its parameter in the released version of the control.

Syntax:

HRESULT get_BitmapPeristence (long* pBitmapPeristence);

Parameters: PBitmapPeristence is a pointer to a LONG value that receives the BitmapPeristence property (1 for enabled, 0 otherwise).
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::put_PluginDlls method

This method specifies the names of virtual channel client .dll(s).

Syntax:

HRESULT put_PluginDlls (BSTR pluginList);

Parameters: PluginList is a comma-separated list of the names of the virtual channel plugin .dll(s).
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: For security reasons, if the control is hosted in a web page the PluginDlls property only accepts a named list of virtual channels .dll's. The control returns an error if any form of path (filesystem or UNC) is specified. PluginDlls that need to be used from a web page must be installed into the system32 directory, since the control will add the path to that directory to the plugin dll names. Note that if the control is not hosted in a web page, this security restriction does not exist and full paths may be used to reference plugindlls.

IMsTscAdvancedSettings::put_ContainerHandledFullScreen method

This method sets the container-handled FullScreen property, which specifies that it is the container's responsibility to handle switching into and out of FullScreen mode. This method should be used only if the container needs fine level control over FullScreen mode behavior. When this property is set, the control does not enter or leave FullScreen mode in response to the FullScreen 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.

Syntax:

HRESULT put_containerHandledFullScreen (BOOL containerHandledFullScreen);

Parameters: ContainerHandledFullScreen is a VARIANT_BOOL value that indicates the container handles FullScreen mode if set to TRUE.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Most container applications will not need to use ContainerHandledFullScreen mode.

IMsTscAdvancedSettings::get_ContainerHandledFullScreen method

This method retrieves the ContainerHandledFullScreen property.

Syntax:

HRESULT get_containerHandledFullScreen (BOOL* pContainerHandledFullScreen);

Parameters: pContainerHandledFullScreen is a pointer to a VARIANT_BOOL that receives the container handled FullScreen mode property.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::put_DisableRdpdr method

This method disables the internal client side component that controls printer redirection and clipboard redirection.

Syntax:

HRESULT DisableRdpdr (BOOL disableRdpdr);

Parameters: DisableRdpdr is a VARIANT_BOOL value that is set to TRUE to disable the internal printer redirection component.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This property can be used to turn off printer/clipboard redirection. Note that in TSAC printer/clipboard redirection is a built in component of the ActiveX control (this component was located in rdpdr.dll for the Windows 2000 client.) This property should also be used if a replacement Rdpdr.dll needs to be loaded (for example, Resource Kit versions which provide modified functionality–see the pluginDlls property for instructions about how to load the alternate .dll).

IMsTscAdvancedSettings::get_DisableRdpdr method

This method retrieves the disableRdpdr property.

Syntax:

HRESULT DisableRdpdr (BOOL* pDisableRdpdr);

Parameters: PDisableRdpdr is a pointer to a VARIANT_BOOL that receives the Disable Rdpdr property.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::put_IconFile method

This method specifies what icon to use when the client is in fullscreen mode.

Syntax:
```
HRESULT put_IconFile (BSTR IconFile);
```
Parameters: IconFile is a path to an IconFile (.ico) or to a file containing icons, such as a .dll file.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscAdvancedSettings::put_IconIndex method

This method sets the index of the icon within the chosen IconFile (see the put_IconFile method for more information).

Syntax:

HRESULT put_IconIndex (LONG IconIndex);

Parameters: IconIndex specifies the index within the IconFile.
Return Value: Returns S_OK if successful or an error value otherwise.

The IMsTscNonScriptable Interface

The ImsTscNonScriptable interface contains properties and methods that relate to applying a password to the Terminal Services ActiveX client control. The interface can be used to configure automatic logon to Terminal servers. With automatic logon, the user is not presented with a Windows Logon dialog box at connection time.

Note Automatic logon can also be enabled at the server with the Terminal Services Configuration tool (Tscc.msc). A server administrator can use this tool to assign a specific password to a connection in cases where automated logons are necessary.

The ImsTscNonScriptable is also intentionally non-scriptable and can only be accessed through vtable binding (for example, from C or C++ code). The password properties were placed in a non-scriptable interface to improve security. If these methods were scriptable, it could encourage Web developers to be careless about password security. For this reason, the main use of this interface is to allow automatic password logon access in scenarios where the control is hosted in a custom-written container.

It is also possible to write a secondary scriptable ActiveX control that can be placed on a Web page to allow scriptable access to the password property. For the reasons outlined above, Microsoft does not provide such a control. Third party developers can develop such functionality, but they should be very careful about the security considerations of password passing by their underlying Web application. In addition, it will be a third party’s responsibility to ensure the security of their control before digitally signing it as safe for scripting.

Providing a password to the control is completely optional. Three separate password formats are supported:

Clear text
Portable encoded
Binary (non-portable) encoded

If a password is to be provided to the control, only one of the three forms should be applied to the control before initiating the connection with a call to the Connect() method.

The methods below can be used to specify the passwords in one of the three forms. They also allow for conversion between clear text passwords and one of the two encoded forms. To do this conversion, set a password in clear text form and then retrieve it in one of the two encoded forms.

IMsTscNonScriptable::put_ ClearTextPassword Method

Sets the password in clear text format. This method can be used to provide a connection password in clear text form.

Syntax:

HRESULT put_ClearTextPassword(BSTR ClearTextPassword);

Parameters: ClearTextPassword is the password with which to connect.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: The UserName and Domain properties must also be set to allow an automatic logon to happen. If the password fails to authenticate the user, the Windows Logon box is displayed at the server to prompt the user for the password.

This method can also be called to set a clear text password that is to be converted to one of the other supported forms (see PortablePassword and BinaryPassword methods).

After the password is set, it is not possible to retrieve it in clear text format.

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 get_Connected method.

IMsTscNonScriptable::put_ PortablePassword Method

Sets the password in portable encoded format. This method can be used to specify a connection password in portable form.

Syntax:

HRESULT put_PortablePassword(BSTR PortablePassword);

Parameters: PortablePassword is the password with which to connect. It is specified in portable encoded format (see Remarks section).
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: A portable encoded password is a password/salt pair (see put_PortableSalt) that is encoded to provide some level of obscurity, but it should not be considered safely encrypted. See the get_PortablePassword method for details about how to retrieve a password in portable form. Portable passwords can be transferred and used by other users on other machines.

The UserName, Domain, and PortableSalt properties must also be set to allow an automatic logon to happen. If the password fails to authenticate the user, the Windows Logon box is displayed at the server to prompt the user for the password.

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 get_Connected method.

IMsTscNonScriptable::get_ PortablePassword Method

Retrieves the password in portable encoded format. This method can be called after the password is set in clear text format using the put_ClearTextPassword method to retrieve the password in portable form.

Syntax:

HRESULT get_PortablePassword(BSTR* pPortablePassword);

Parameters: pPortablePassword is a pointer to a BSTR that receives the portable password.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Note: a portable password is part of a password/salt pair. Use the get_PortableSalt method to retrieve the portable salt.

A portable password/salt pair appears as a string of HEX digits.

IMsTscNonScriptable::put_ PortableSalt Method

Sets the portable salt part of a portable password.

Syntax:

HRESULT put_PortableSalt(BSTR PortableSalt);

Parameters: PortableSalt is the portable salt portion of a portable password.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: 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 get_Connected method.

IMsTscNonScriptable::get_ PortableSalt Method

Retrieves the password’s portable salt. This method can be called to retrieve the password’s portable salt after the password has been set in clear text format using put_ClearTextPassword. A portable password consists of a portable password and portable salt pair.

Syntax:

HRESULT get_PortableSalt(BSTR* pPortableSalt);

Parameters: pPortableSalt is a pointer to a BSTR that receives the portable password’s salt value.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: A portable salt appears as a string of HEX digits.

IMsTscNonScriptable::put_ BinaryPassword Method

Sets the password in binary format. This method can be used to specify a connection password in binary form.

Syntax:

HRESULT put_BinaryPassword(BSTR BinaryPassword);

Parameters: BinaryPassword is the password with which to connect, specified in binary format (see Remarks section).
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: A binary encoded password is a password/salt pair (see put_BinarySalt) that is encoded to provide some level of obscurity, but it should not be considered safely encrypted. See the get_BinaryPassword method for details about how to retrieve a password in portable form. Binary passwords do not appear in human readable form and can only be used by the same user (and on the same machine) where they were encrypted.

The UserName, Domain, and BinarySalt properties must also be set to allow an automatic logon. If the password fails to authenticate the user, the Windows Logon box is displayed at the server to prompt the user for the password.

Apply only those binary encoded passwords that were generated by converting clear text passwords to binary password/salt pairs using the control’s get_BinaryPassword/get_BinarySalt methods.

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 get_Connected method.

IMsTscNonScriptable::get_ BinaryPassword Method

Retrieves the password in binary encoded format. This method can be called to retrieve the password in binary encoded (non-portable) form after the password has been set in clear text format using put_ClearTextPassword

Syntax:

HRESULT get_BinaryPassword(BSTR* pBinaryPassword);

Parameters: pBinaryPassword is a pointer to a BSTR that receives the binary password.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: Note that a binary encoded password is part of a password/salt pair. Use the get_BinarySalt method to retrieve the portable salt.

A binary encoded password/salt pair does not appear in human readable form.

IMsTscNonScriptable::put_ BinarySalt Method

Sets the binary salt portion of a binary encoded (non-portable) password.

Syntax:

HRESULT put_BinarySalt(BSTR BinarySalt);

Parameters: BinarySalt is the binary salt portion of a binary encoded (non-portable) password.
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: 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 get_Connected method.

IMsTscNonScriptable::get_ BinarySalt Method

Retrieves the password’s binary salt. This method can be called to retrieve the password’s binary salt after the password has been set in clear text format using put_ClearTextPassword. A binary encoded (non-portable) password consists of a binary password and binary salt pair.

Syntax:

HRESULT get_BinarySalt(BSTR* pBinarySalt);

Parameters: pBinarySalt is a pointer to a BSTR that receives the binary password’s salt value.
Return Value: Returns S_OK if successful or an error value otherwise.

IMsTscNonScriptable::ResetPassword Method

Call this method to reset all password states in the control. This clears passwords stored in any of the three forms: ClearText, portable encoded, or binary encoded (non-portable).

This method can be used to reset the password after disconnecting from one connection, ensuring that a subsequent connection (with the same instance of the control) does not automatically log on with the previously set password.

Syntax:
```
HRESULT ResetPassword();
```
Return Value: Returns S_OK if successful or an error value otherwise.
Remarks: This method can only be called 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 get_Connected method.

Value	Meaning
1	Bitmap cache corrupted warning

Scripting the Terminal Services Advanced Client

Contents

Introduction

Implementing Scriptable Virtual Channels with the TSAC

To create and deploy scriptable virtual channels

Terminal Services ActiveX Client Control Properties and Methods

Secured Settings Interface

Notes on using the Secured Settings Interface properties

Secured Settings Interface Methods

IMsTscSecuredSettings::put_StartProgram method

IMsTscSecuredSettings::get_StartProgram method

IMsTscSecuredSettings::put_WorkDir method

IMsTscSecuredSettings::get_WorkDir method

IMsTscSecuredSettings::put_FullScreen method

IMsTscSecuredSettings::get_FullScreen method

IMsTscAx Interface Methods

IMsTscAx::put_Server method

IMsTscAx::get_Server method

IMsTscAx::put_Domain method

IMsTscAx::get_Domain method

IMsTscAx::put_UserName method

IMsTscAx::get_UserName method

IMsTscAx::put_DisconnectedText method

IMsTscAx::get_DisconnectedText method

IMsTscAx::put_ConnectingText method

IMsTscAx::get_ConnectingText method

IMsTscAx::get_Connected method

IMsTscAx::put_DesktopWidth method

IMsTscAx::get_DesktopWidth method

IMsTscAx::put_DesktopHeight method

IMsTscAx::get_DesktopHeight method

IMsTscAx::put_StartConnected method

IMsTscAx::get_StartConnected method

IMsTscAx::get_HorizontalScrollBarVisible method

IMsTscAx::get_VerticalScrollBarVisible method

IMsTscAx::put_FullScreenTitle method

IMsTscAx::get_CipherStrength method

IMsTscAx::get_Version method

IMsTscAx::get_SecuredSettingsEnabled method

IMsTscAx::get_SecuredSettings method

IMsTscAx::get_AdvancedSettings method

IMsTscAx::Connect method

IMsTscAx::Disconnect method

IMsTscAx::CreateVirtualChannels method

IMsTscAx::SendOnVirtualChannel method

Events Interface

IMsTscAxEvents::OnConnecting method

IMsTscAxEvents::OnConnected method

IMsTscAxEvents::OnLoginComplete method

IMsTscAxEvents::OnDisconnected method

IMsTscAxEvents::OnEnterFullScreenMode method

IMsTscAxEvents::OnLeaveFullScreenMode method

IMsTscAxEvents::OnChannelReceivedData method

IMsTscAxEvents::OnRequestGoFullScreen method

IMsTscAxEvents::OnRequestLeaveFullScreen method

IMsTscAxEvents::OnFatalError method

IMsTscAxEvents::OnWarning method

IMsTscAxEvents::OnRemoteDesktopSizeChange method

IMsTscAdvancedSettings Interface

IMsTscAdvancedSettings::put_Compress method

IMsTscAdvancedSettings::get_Compress method

IMsTscAdvancedSettings::put_BitmapPeristence method

IMsTscAdvancedSettings::get_BitmapPeristence method

IMsTscAdvancedSettings::put_PluginDlls method

IMsTscAdvancedSettings::put_ContainerHandledFullScreen method

IMsTscAdvancedSettings::get_ContainerHandledFullScreen method

IMsTscAdvancedSettings::put_DisableRdpdr method

IMsTscAdvancedSettings::get_DisableRdpdr method

IMsTscAdvancedSettings::put_IconFile method

IMsTscAdvancedSettings::put_IconIndex method

The IMsTscNonScriptable Interface

IMsTscNonScriptable::put_ ClearTextPassword Method

IMsTscNonScriptable::put_ PortablePassword Method

IMsTscNonScriptable::get_ PortablePassword Method

IMsTscNonScriptable::put_ PortableSalt Method

IMsTscNonScriptable::get_ PortableSalt Method

IMsTscNonScriptable::put_ BinaryPassword Method

IMsTscNonScriptable::get_ BinaryPassword Method

IMsTscNonScriptable::put_ BinarySalt Method

IMsTscNonScriptable::get_ BinarySalt Method