TermMon ActiveX Control

Microsoft Terminal Services lacks the ability to monitor clients and provide much useful information. ACP has written an ActiveX component to overcome this shortcoming. The TermMon (Terminal Monitoring) ActiveX can be embedded into an application that will run on the terminal server. When a terminal starts a session on the terminal server and launches the application with the TermMon ActiveX, the ActiveX will create a socket connection to the terminal and is able to pull data from the terminal into the application for display. You can create tags for the data and populate them with data from the client via the ActiveX. The control also provides programmatic control of your terminal, including but not limited to activating tiling mode, launching the calibration window, manipulating IP Camera Overlays, etc.

Registering the Control

The TermMon ActiveX control must be registered before it can be used. Copy the file termmon.ocx from the ThinManager CD to the computer where you want to use it.

For 32-bit operating systems, register the OCX by executing:

regsvr32 c:\path\to\termmon.ocx

For 64-bit operating systems, register the OCX by executing:

c:\windows\syswow64\regsvr32 c:\path\to\termmon.ocx

If you have trouble registering the control on a target machine, it may be because ThinManager is not installed on that machine, or that the required Visual C++ redistributable is missing. For TermMon.ocx versions 7.3 or newer, download the Microsoft Visual C++ 2015 Redistributable Package. For versions of TermMon.ocx prior to version 7.3, download the Microsoft Visual C++ 2010 Redistributable Package

Microsoft Visual C++ 2015 Redistributable: https://www.microsoft.com/en-us/download/details.aspx?id=53587

Microsoft Visual C++ 2010 Redistributable: http://www.microsoft.com/en-us/download/details.aspx?id=5555

Using the Control

TermMon ActiveX Configuration Module

If running the Control in the terminal’s terminal services session, no special configuration of the terminal in ThinManager is required. The TermMon ActiveX Control Configuration Module is not required. If the Control is not run in the terminal’s terminal services session, the TermMon ActiveX Control Configuration Module must be added to the terminal configuration in ThinManager. In the module configuration, Allow ActiveX Connections must be set to YES and Only Allow Connections from Session must be set to NO.

The TermMon ActiveX Control Configuration Module can be used to prevent a connection from an application running in the terminal’s terminal services session. This is accomplished by adding the TermMon ActiveX Control Configuration Module to the terminal in ThinManager and setting the Allow ActiveX Connections option to NO.

The TermMon ActiveX Control communicates to a ThinManager terminal over TCP port 2031. When the Enable method is executed, this connection is attempted. To successfully establish this connection, the Enable method will attempt to determine the IP address of the terminal where the session containing the ActiveX control is being delivered. Special consideration needs to be made if an RD Gateway is being utilized, as the IP address returned by the Enable method will be the IP address of the RD Gateway as opposed to the terminal. In this case, the OverrideIP method can be used to programmatically specify the terminal's IP address and then issue the Enable method. The terminal's IP address can be obtained by using the ThinManager environment variable #TERMINAL_IPADDRESS#. This ThinManager environment variable can be passed into a Display Client's command line to execute a batch file. The batch file can take this ThinManager environment variable and set a Windows environment variable using the SETX command, which can then be retrieved from the ActiveX container hosting the TermMon ActiveX Control.

Read-Only Properties

The following properties are read only strings. An event will be generated any time one of these properties changes. The Enable method must be invoked prior to reading these properties.

TerminalName - This is the name of the terminal.

TerminalModel - This is the terminal model number.

TerminalIP - This is the terminal IP address.

TerminalMAC - This is the terminal MAC Address.

TerminalBootLoaderVersion - This is the terminal network boot loader version.

TerminalFirmwareVersion - This is the firmware version that the terminal is running.

TerminalWindowsUsername - This is the Windows Username that is specified in the terminal’s ThinManager configuration.

TermSecureUsername - This is the TermSecure username of the TermSecure user currently logged onto the terminal. If no TermSecure user is logged on, this value will be blank.

TermSecureWindowsUsername - This is the Windows Username associated with a TermSecure user. This is the Windows Username for all TermSecure user sessions. If no TermSecure user is logged on, this value will be blank.

TerminalServerGroupList - This is a comma-separated list of Display Clients currently running on the terminal.

ConnectionState - This is the Control’s connection state with the terminal.

CurrentTerminalServerGroup - This is the Display Client that is currently being displayed on the terminal.

CurrentWindowsUsername - This is the Windows Username of the session where the Control has been executed. This property is not available when the RunInSession property is set to False.

TerminalServerName - This is the name of the Terminal Server where the Control is running. This property is not available when the RunInSession property is set to False.

UserID - This is the identifier associated with a TermSecure user. An example of this would be the badge number of a security badge used by a TermSecure user when scanning the badge. Using this property may require enabling the “Expose ID” setting in the appropriate ThinManager module (i.e. RFIdeas pcProx USB Module).

RelevanceLocationName - This is the complete path and name of the current Relevance Location.

ScanResult - This property will contain the result of the Command Method Scan Code commands.

BiometricData – This property will contain the raw data returned from a biometric scan. The format of this data will be determined by the Biometric module as configured on the terminal.

BiometricLookupResult – This property will contain the result of the ScanBiometricAndQueryUser command.

TermMonConst.Success – The lookup was successful.

TermMonConst.Timeout - The request timed out.

TermMonConst.Busy - The Control is busy with another request.

TermMonConst.UserNotFound - The scan did not match an enrolled user.

TermMonConst.Fail - The operation failed.

BiometricLookupUsername – This property will contain the TermSecure username when the result of the ScanBiometricAndQueryUser command is successful.

Read-Write Properties

These properties can be set by the application.

RunInSession - When the RunInSession property is set to True, the Control will be running in the terminal’s terminal services session. The terminal IP address will be determined automatically by the control.

OverrideIP - If the RunInSession property is set to False, the OverrideIP property specifies the IP Address of the terminal that the Control will connect to.

---

Note: To use the OverrideIP property, the TermMon ActiveX Control Configuration Module must be added to the terminal configuration in ThinManager. In the module configuration, Allow ActiveX Connections must be set to YES, and Only Allow Connections from Session must be set to NO.

---

WatchdogTime – This is the number of seconds before the watchdog will reset the terminal session. Once this property is set to a non-zero value, the property must be updated before the watchdog time reaches zero. To disable the watchdog, set this property to zero. The watchdog is disabled by default.

---

Note: The Enable Method does not need to be called for watchdog operation. Watchdog operation is independent of the Enable and Disable Methods.

---

ActiveScreen – For MultiMonitor configurations, this is the active screen number. A value of zero (default) will set the active screen to the screen the mouse pointer is on when a method or command is executed. A non-zero value will set the Active Screen to the screen number specified. All methods and commands will be executed on the specified screen.

Events

OnEvent - When any property value changes, an event will be generated by the Control. When an Event occurs the event code can be used to determine the property that changed. The Event method must be invoked in order to receive events (except for WatchdogTime). The event code is provided by the Control as a TermMonEvent constant.

OnBiometricData -

OnBiometricLookupResult -

OnBiometricLookupUsername -

OnConnectionState -

OnCurrentTerminalServerGroup -

OnCurrentWindowsUsername -

OnRelevanceLocationName -

OnScanResult -

OnTerminalBootLoaderVersion -

OnTerminalFirmwareVersion -

OnTerminalIP -

OnTerminalMAC -

OnTerminalModel -

OnTerminalName -

OnTerminalServerGroupList -

OnTerminalServerName -

OnTerminalWindowsUsername -

OnTermSecureUserChange -

OnTermSecureUsername -

OnTermSecureWindowsUsername -

OnUserID -

OnWatchdogTime -

Methods

Enable - Invoking this method will enable the Control. The Control will attempt to connect to the terminal and generate events to update the Control Properties. The Control will maintain a connection to the terminal as long as it is enabled.

Disable - Invoking this method will cause the Control to break the connection with the terminal. Events will be generated to clear the Control Properties.

Command - The Command method can be used to send terminal action commands. The Command method requires one parameter which is the terminal command to be performed. The Enable method must be invoked before these commands can be executed (except for noted exceptions). The supported commands are:

Reboot - This command will initiate a terminal reboot.

Restart - This command will initiate a terminal restart.

Calibrate - This command will initiate a touch screen calibration.

GotoMainMenu - This command will cause the Main Menu to be displayed.

SwitchToNextGroup - This command will switch to the next Display Client.

SwitchToPrevGroup - This command will switch to the previous Display Client.

SwitchInstFailover - This command will switch the instant failover group.

ChangeTermSecureUser - This command will disconnect any current TermSecure user sessions and then display the TermSecure Log On menu.

LogOffAndChangeTermSecureUser - This command will log off any current TermSecure user sessions and then display the TermSecure Log On menu.

LogOffTermSecureUser - This command will log off any current TermSecure user sessions and will return to a Display Client which is assigned to the terminal. If no Display Clients have been configured on the terminal, the TermSecure Log On menu will be displayed.

DisconnectTermSecureUser - This command will disconnect any current TermSecure user sessions and will return to a Display Client which is assigned to the terminal. If no Display Clients have been configured on the terminal, the TermSecure Log On menu will be displayed.

DisconnectSession - This command will disconnect the Terminal Services Session running on the terminal. This command does not require that the Enable Method be invoked prior to execution.

LogOffSession - This command will log off the Terminal Services Session running on the terminal. This command does not require that the Enable Method be invoked prior to execution.

TileStart - This command will tile the Display Clients on the current Screen.

TileEnd - This command will untile the Display Clients on the current Screen.

ScanCodeReturnData - This command will prompt the user to scan a QR or Barcode. After the scan is complete, the scan data will be returned in the ScanResult property.

ScanCodeAndQueryLocation - This command will prompt the user to scan a QR or Barcode. After the scan is complete, the location path and name will be returned in the ScanResult property.

ScanBiometricAndQueryUser - This command will send the next Biometric scan to ThinServer and return the associated TermSecure Username. The result of the operation will be returned in the BiometricLookupResult property.Upon a successful result, the TermSecure username is returned in the BiometricLookupUsername property.

The Command Method constants are provided by the Control as follows:

TermMonCommand.Reboot

TermMonCommand.Restart

TermMonCommand.Calibrate

TermMonCommand.GotoMainMenu

TermMonCommand.SwitchToNextGroup

TermMonCommand.SwitchToPrevGroup

TermMonCommand.SwitchInstFailover

TermMonCommand.ChangeTermSecureUser

TermMonCommand.LogOffAndChangeTermSecureUser

TermMonCommand.LogOffTermSecureUser

TermMonCommand.DisconnectTermSecureUser

TermMonCommand.DisconnectSession

TermMonCommand.LogOffSession

TermMonCommand.TileStart

TermMonCommand.TileEnd

TermMonCommand.ScanCodeReturnData

TermMonCommand.ScanCodeAndQueryLocation

TermMonCommand.ScanBiometricAndQueryUser

ChangeTerminalServerGroup - This method can be used to change the Display Client currently displayed on the terminal. This method requires one parameter which is the name of the Display Client that the terminal should switch to.

TermSecureCheckAccess - This method can be used to query the access rights of a TermSecure user. This method requires two parameters. The first parameter is the name of the user. The second parameter is the name of the Access Group. This method returns the result of the query as follows:

TermMonConst.Timeout - The request timed out.

TermMonConst.Busy - The Control is busy with another request.

TermMonConst.InvalidMember - The user is not a member of the specified TermSecure Access Group.

TermMonConst.ValidMember - The user is a member of the specified TermSecure Access Group.

TermMonConst.UserNotFound - The TermSecure Username was not found.

TermMonConst.GroupNotFound - The Access Group Name was not found.

GetGroupScreen - This method can be used to determine which screen the specified Display Client is currently on for MultiMonitor configurations. This method requires one parameter which is the name of the Display Client.

TermSecureLogonUser - This method can be used to Log On a specified TermSecure user. This method requires two parameters. The first parameter is the name of the TermSecure user. The second parameter is the password of the TermSecure user. The password will be encrypted before being sent to the terminal. This method returns a result as follows:

TermMonConst.Success - The TermSecure user was successfully logged on.

TermMonConst.Timeout - The request timed out.

TermMonConst.Busy - The Control is busy with another request.

TermMonConst.UserNotFound - The TermSecure Username was not found.

TermMonConst.BadPassword - The TermSecure password was invalid.

TermMonConst.NoPermission - The TermSecure user does not have permission to use the terminal.

TermMonConst.NoWindowsUsername - This TermSecure user does not have a Windows Username specified in the TermSecure user configuration. This is only required for Terminal Services Display Clients assigned to the TermSecure User.

TermMonConst.NoWindowsPassword - This TermSecure user does not have a Windows Password specified in the TermSecure user configuration. This is only required for Terminal Services Display Clients assigned to the TermSecure User.

CameraOverlayEnable - This method is used to enable a camera overlay. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlayDisable - This method is used to disable a camera overlay. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlayCycleStart - This method is used to start camera cycling for a camera overlay. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlayCycleStop - This method is used to stop camera cycling for a camera overlay. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlaySwitchNext - This method is used to switch to the next camera in a camera overlay list. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlaySwitchPrev - This method is used to switch to the previous camera in a camera overlay list. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlayFullscreenEnter - This method is used to make the current camera in a camera overlay enter full screen. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlayFullscreenExit - This method is used to make the current camera in a camera overlay exit full screen. This method requires two parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay.

CameraOverlaySwitchByName - This method is used to change cameras in a camera overlay. This method requires three parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay. The third parameter is the name of the camera. The camera name must include the full path if the camera is in a camera group.

CameraOverlayMove - This method is used to change the position of a camera overlay. This method requires four parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay. The third parameter is the x location. The forth parameter is the y position.

CameraOverlayResize - This method is used to change the size of a camera overlay. This method requires four parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay. The third parameter is the width. The forth parameter is the height.

CameraOverlayResizeMove - This method is used to change the size and position of a camera overlay. This method requires six parameters. The first parameter is the name of the Display Client the overlay is on. The second parameter is the name of the overlay. The third parameter is the x position. The forth parameter is the y position. The fifth parameter is the width. The sixth parameter is the height.

RelevanceLocationLogon - This method is used to log into a relevance location. This method requires two parameters. The first parameter is the complete path and name of the desired location formatted as “top_level_location_name\sub_location_name\location_name”. This string must match the location tree hierarchy in the ThinManager location tree. The second parameter is the action to be performed as defined by the TermMonRelevance action constants.

RelevanceLocationLogoff - This method will log the device out of the current relevance location.

ScreenOverlayShow - This method will show a virtual screen overlay. The method requires two parameters. The first parameter is the name of the Display Client that contains the virtual screen overlay. The second parameter is the overlay name.

ScreenOverlayHide - This method will hide a virtual screen overlay. The method requires two parameters. The first parameter is the name of the Display Client that contains the virtual screen overlay. The second parameter is the overlay name.

GetCustomVariable - This method can be used to retrieve a custom variable. In ThinManager, custom variables can be added to users, locations, and terminals. This method requires one parameter. The parameter is the name of the custom variable. This method returns the result of the query as a TermMonConst found below. Upon a successful result, the value of the custom variable can be read from the CustomVariableValue property.

GetCustomVariable2 - This method can be used to retrieve a custom variable. This method requires two parameters. The first parameter is the name of the custom variable. The second parameter is the type as a CustomVarObjectTypeConst found below. This method returns the result of the query as a TermMonConst found below. Upon a successful result, the value of the custom variable can be read from the CustomVariableValue property.

SetCustomVariable - This method can be used to set a custom variable. This method requires three parameters. The first parameter is the name of the custom variable. The second parameter is the desired value of the custom variable. The third parameter is the type as a CustomVarObjectTypeConst found below. This method returns the result of the query as a TermMonConst found below.

GenerateWindowsAccessToken - Generates and returns a Windows Access Token for the current logged in user. MSDN - Access Tokens

iFixLogin - Logs the current AD link Relevance User into the iFix application that contains the TermMon ActiveX.

Control Constants

Constant values provided by the Control are as follows:

TermMonEvent TerminalName 1 TerminalModel 2 TerminalIP 3 TerminalMAC 4 TerminalBootLoaderVersion 5 TerminalFirmwareVersion 6 TerminalWindowsUsername 7 TermSecureUsername 8 TermSecureWindowsUsername 9 TerminalServerGroupList 10 ConnectionState 11 CurrentTerminalServerGroup 12 CurrentWindowsUsername 13 TerminalServerName 14 WatchdogTime 15 UserID 16 RelevanceLocationName 17 ScanResult 18 BiometricData 19 BiometricLookupResult 20 BiometricLookupUsername 21

TermMonCommand Reboot 100 Restart 101 Calibrate 102 GotoMainMenu 103 SwitchToNextGroup 104 SwitchToPrevGroup 105 SwitchInstantFailover 106 ChangeTermSecureUser 107 LogOffAndChangeTermSecureUser 108 LogOffTermSecureUser 109 DisconnectTermSecureUser 110 DisconnectSession 111 LogOffSession 112 TileStart 113 TileEnd 114 ScanCodeReturnData 115 ScanCodeAndQueryLocation 116 ScanBiometricAndQueryUser 117

TermMonConst Success 0 Fail 1 Disconnected 2 Connected 3 Timeout 4 Busy 5 Updating 6 RequestFailed 7 InvalidMember 8 ValidMember 9 UserNotFound 10 GroupNotFound 11 BadPassword 12 NoPermission 13 PasswordChangeReq 14 NoWindowsUsername 15 NoWindowsPassword 16

CustomVarObjectTypeConst deflt 1 terminal 2 user 3 location 4

TermMonRelevance ActionNone 0 ActionTransfer 1 ActionClone 2 ActionShadow 3