Welcome to the ThinManager Knowledgebase.
Additional knowledgebase articles can be found at Rockwell Automation Tech Support.

If you would like to speak with one of our engineers, please Submit a Question or give us a call at the phone number here. In North America, To route your phone support request directly to a technical support engineer, call toll-free 1-888-382-1583 or 1-440-646-3434, select Option 3 (Technical Support), then select Option 5 (More Options). When prompted, enter the ThinManager Direct Dial Code 201.

Difference between revisions of "TermMon ActiveX Control"

From ThinManager Knowledge Base
Jump to: navigation, search
(Read-Only Properties)
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Microsoft Terminal Services lacks the ability to monitor clients and provide much useful information. ACP has  
+
[[Category:TermMon]]
 +
[[Category:ThinManager]]
 +
[[Microsoft Terminal Services]] lacks the ability to monitor clients and provide much useful information. ACP has  
 
written an ActiveX component to overcome this shortcoming.  
 
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  
 
The TermMon (Terminal Monitoring) ActiveX can be embedded into an application that will run on the terminal  
Line 5: Line 7:
 
TermMon ActiveX, the ActiveX will create a socket connection to the terminal and is able to pull data from 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  
 
terminal into the application for display. You can create tags for the data and populate them with data from the  
client via the ActiveX  
+
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.
 +
 
 +
===<font color="green">For instructions in a PDF document click the [https://kb.thinmanager.com/images/d/d6/ActiveXData_ThinManager_9.pdf TermMon ActiveX Control for ThinManager 9] link.</font>===
  
 
==Registering the Control==
 
==Registering the Control==
  
 
The TermMon ActiveX control must be registered before it can be used. Copy the file termmon.ocx from  
 
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. Register the OCX by executing:
+
the ThinManager CD to the computer where you want to use it.  
<pre>regsvr32 path\termmon.ocx</pre>
+
 
 +
For 32-bit operating systems, register the OCX by executing:
 +
<pre>regsvr32 c:\path\to\termmon.ocx</pre>
 +
 
 +
For 64-bit operating systems, register the OCX by executing:
 +
<pre>c:\windows\syswow64\regsvr32 c:\path\to\termmon.ocx</pre>
 
   
 
   
 +
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==
 
==Using the Control==
 
===TermMon ActiveX Configuration Module===
 
===TermMon ActiveX Configuration Module===
Line 27: Line 43:
 
ActiveX Control Configuration Module to the terminal in ThinManager and setting the Allow ActiveX
 
ActiveX Control Configuration Module to the terminal in ThinManager and setting the Allow ActiveX
 
Connections option to NO.
 
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===
 
===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.
 
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.
+
::'''TerminalName''' - This is the name of the terminal.
::TerminalModel - This is the terminal model number.
+
::'''TerminalModel''' - This is the terminal model number.
::TerminalIP - This is the terminal IP address.
+
::'''TerminalIP''' - This is the terminal IP address.
::TerminalMAC - This is the terminal MAC Address.
+
::'''TerminalMAC''' - This is the terminal MAC Address.
::TerminalBootLoaderVersion - This is the terminal network boot loader version.
+
::'''TerminalBootLoaderVersion''' - This is the terminal network boot loader version.
::TerminalFirmwareVersion - This is the firmware version that the terminal is running.
+
::'''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.
+
::'''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.
+
::'''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.
+
::'''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 terminal server groups currently running on the terminal.
+
::'''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.
+
::'''ConnectionState''' - This is the Control’s connection state with the terminal.
::CurrentTerminalServerGroup - This is the Terminal Server Group that is currently being displayed on 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.
+
::'''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.
+
::'''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===
 
===Read-Write Properties===
  
 
These properties can be set by the application.
 
These properties can be set by the application.
· RunInSession - When the RunInSession property is set to True, the Control will be running in the
+
::'''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.
terminal’s terminal services session. The terminal IP address will be determined automatically by the
+
::'''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.
control.
+
----
· OverrideIP - If the RunInSession property is set to False, the OverrideIP property specifies the IP
+
'''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.
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
+
::'''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.
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.
+
'''Note''': The Enable Method does not need to be called for [[watchdog]] operation. [[Watchdog]] operation is independent of the Enable and Disable Methods.
· 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
+
::'''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.
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.
 
  
 
===Events===
 
===Events===
  
When a 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 follows:
+
'''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.
::TermMonEvent.TerminalName
+
 
::TermMonEvent.TerminalModel
+
'''OnBiometricData''' -
::TermMonEvent.TerminalIP
+
 
::TermMonEvent.TerminalMAC
+
'''OnBiometricLookupResult''' -
::TermMonEvent.TerminalBootLoaderVersion
+
 
::TermMonEvent.TerminalFirmwareVersion
+
'''OnBiometricLookupUsername''' -
::TermMonEvent.TerminalWindowsUsernameACP TermMon ActiveX Control (Rev. 2) 3
+
 
::TermMonEvent.TermSecureUsername
+
'''OnConnectionState''' -
::TermMonEvent.TermSecureWindowsUsername
+
 
::TermMonEvent.TerminalServerGroupList
+
'''OnCurrentTerminalServerGroup''' -
::TermMonEvent.ConnectionState
+
 
::TermMonEvent.CurrentTerminalServerGroup
+
'''OnCurrentWindowsUsername''' -
::TermMonEvent.CurrentWindowsUsername
+
 
::TermMonEvent.TerminalServerName
+
'''OnRelevanceLocationName''' -
::TermMonEvent.WatchdogTime
+
 
 +
'''OnScanResult''' -
 +
 
 +
'''OnTerminalBootLoaderVersion''' -
 +
 
 +
'''OnTerminalFirmwareVersion''' -
 +
 
 +
'''OnTerminalIP''' -
 +
 
 +
'''OnTerminalMAC''' -
 +
 
 +
'''OnTerminalModel''' -
 +
 
 +
'''OnTerminalName''' -
 +
 
 +
'''OnTerminalServerGroupList''' -
 +
 
 +
'''OnTerminalServerName''' -
 +
 
 +
'''OnTerminalWindowsUsername''' -
 +
 
 +
'''OnTermSecureUserChange''' -
 +
 
 +
'''OnTermSecureUsername''' -
 +
 
 +
'''OnTermSecureWindowsUsername''' -
 +
 
 +
'''OnUserID''' -
 +
 
 +
'''OnWatchdogTime''' -
  
 
===Methods===
 
===Methods===
Line 90: Line 145:
 
::'''Reboot''' - This command will initiate a terminal reboot.
 
::'''Reboot''' - This command will initiate a terminal reboot.
 
::'''Restart''' - This command will initiate a terminal restart.
 
::'''Restart''' - This command will initiate a terminal restart.
::'''Calibrate''' - This command will initiate a touch screen calibration.
+
::'''Calibrate''' - This command will initiate a [[touch screen calibration]].
 
::'''GotoMainMenu''' - This command will cause the Main Menu to be displayed.
 
::'''GotoMainMenu''' - This command will cause the Main Menu to be displayed.
::'''SwitchToNextGroup''' - This command will switch to the next terminal server group.
+
::'''SwitchToNextGroup''' - This command will switch to the next [[Display Client]].
::'''SwitchToPrevGroup''' - This command will switch to the previous terminal server group.
+
::'''SwitchToPrevGroup''' - This command will switch to the previous [[Display Client]].
 
::'''SwitchInstFailover''' - This command will switch the instant failover group.
 
::'''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.
 
::'''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.
 
::'''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 terminal server group which is assigned to the terminal. If no terminal server groups have been configured on the terminal, the TermSecure Log On menu will be displayed.
+
::'''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 terminal server group which is assigned to the terminal. If no terminal server groups 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.ACP TermMon ActiveX Control (Rev. 2) 4
+
::'''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.
 
::'''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:
 
The Command Method constants are provided by the Control as follows:
 
::TermMonCommand.Reboot
 
::TermMonCommand.Reboot
Line 115: Line 176:
 
::TermMonCommand.DisconnectSession
 
::TermMonCommand.DisconnectSession
 
::TermMonCommand.LogOffSession
 
::TermMonCommand.LogOffSession
 +
::TermMonCommand.TileStart
 +
::TermMonCommand.TileEnd
 +
::TermMonCommand.ScanCodeReturnData
 +
::TermMonCommand.ScanCodeAndQueryLocation
 +
::TermMonCommand.ScanBiometricAndQueryUser
  
'''ChangeTerminalServerGroup''' - This method can be used to change the terminal server group currently displayed on the terminal. This method requires one parameter which is the name of the terminal server group that the terminal should switch to.
+
'''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:
 
'''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:
Line 124: Line 190:
 
::TermMonConst.ValidMember - The user is 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.UserNotFound - The TermSecure Username was not found.
::TermMonConst.GroupNotFound - The Access Group Name was not found.ACP TermMon ActiveX Control (Rev. 2) 5
+
::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. [https://msdn.microsoft.com/en-us/library/windows/desktop/aa374909%28v=vs.85%29.aspx MSDN - Access Tokens]
 +
 
 +
'''iFixLogin''' - Logs the current AD link Relevance User into the [[iFix]] application that contains the TermMon ActiveX.
  
 
===Control Constants===
 
===Control Constants===
Line 163: Line 283:
 
|-
 
|-
 
| align="right" | TerminalServerName || align="center" | 14
 
| align="right" | TerminalServerName || align="center" | 14
 +
|-
 +
| align="right" | WatchdogTime || align="center" | 15
 +
|-
 +
| align="right" | UserID || align="center" | 16
 +
|-
 +
| align="right" | RelevanceLocationName || align="center" | 17
 +
|-
 +
| align="right" | ScanResult || align="center" | 18
 +
|-
 +
| align="right" | BiometricData || align="center" | 19
 +
|-
 +
| align="right" | BiometricLookupResult || align="center" | 20
 +
|-
 +
| align="right" | BiometricLookupUsername || align="center" | 21
 
|}
 
|}
 
| STYLE="vertical-align:top; padding-right:50px"|
 
| STYLE="vertical-align:top; padding-right:50px"|
Line 194: Line 328:
 
|-
 
|-
 
| align="right" | LogOffSession || align="center" | 112
 
| align="right" | LogOffSession || align="center" | 112
 +
|-
 +
| align="right" | TileStart || align="center" | 113
 +
|-
 +
| align="right" | TileEnd || align="center" | 114
 +
|-
 +
| align="right" | ScanCodeReturnData || align="center" | 115
 +
|-
 +
| align="right" | ScanCodeAndQueryLocation || align="center" | 116
 +
|-
 +
| align="right" | ScanBiometricAndQueryUser || align="center" | 117
 
|}
 
|}
| STYLE="vertical-align: top"|
+
| STYLE="vertical-align:top; padding-right:50px"|
 
{|
 
{|
 
|-
 
|-
Line 223: Line 367:
 
|-
 
|-
 
| align="right" | GroupNotFound || align="center" | 11
 
| align="right" | GroupNotFound || align="center" | 11
 +
|-
 +
| align="right" | BadPassword || align="center" | 12
 +
|-
 +
| align="right" | NoPermission || align="center" | 13
 +
|-
 +
| align="right" | PasswordChangeReq || align="center" | 14
 +
|-
 +
| align="right" | NoWindowsUsername || align="center" | 15
 +
|-
 +
| align="right" | NoWindowsPassword || align="center" | 16
 +
|}
 +
| STYLE="vertical-align: top"|
 +
{|
 +
|-
 +
! colspan="2"| CustomVarObjectTypeConst
 +
|-
 +
| align="right" | deflt || align="center" | 1
 +
|-
 +
| align="right" | terminal || align="center" | 2
 +
|-
 +
| align="right" | user || align="center" | 3
 +
|-
 +
| align="right" | location || align="center" | 4
 +
|}
 +
| STYLE="vertical-align: top"|
 +
{|
 +
|-
 +
! colspan="2"| TermMonRelevance
 +
|-
 +
| align="right" | ActionNone || align="center" | 0
 +
|-
 +
| align="right" | ActionTransfer || align="center" | 1
 +
|-
 +
| align="right" | ActionClone || align="center" | 2
 +
|-
 +
| align="right" | ActionShadow || align="center" | 3
 
|}
 
|}
 
|}
 
|}

Revision as of 15:50, 5 November 2019

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.

For instructions in a PDF document click the TermMon ActiveX Control for ThinManager 9 link.

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