The VirtualHere server can synchronously execute server scripts on certain events. Sometimes USB devices need certain commands to be sent to them to workaround their in-built differences (or quirks). You can also use this event system for special logging e.g bind/unbind of devices for time based usage among other use-cases. Please make sure any scripts you run are quick as they are synchronous to the operation of the event.
The way the VirtualHere server handles this is to provide a callback mechanism to call a bash script (Linux/OSX servers) or batch file (Windows) to be executed when a server event occurs. Each callback is specified as a line in the server configuration file.
The event type is specified and a dot, then vendor id and optionally a dot and product id that the event is specified for. If no product id is specified, all products from that vendor have the event script executed against. If no qualification is made it applies to all devices.
For example a script that runs when an iPad is used by a remote virtualhere client could be (a line written inside the server config.ini)
onBind.05ac.12ab=cat $DEVPATH$/bNumConfigurations > $DEVPATH$/bConfigurationValue
onBind is the event, 05ac is the Apple USB Vendor Id, 12ab is the Product Id, VirtualHere will replace $DEVPATH$ with the kernel device path at runtime.
What these lines do is set the iPad configuration to the maximum configuration number supported by the device when it is "used" by a remote client.
See another example at the bottom of this page.
For each event you can pass at least the following arguments:
$ADDRESS$- Unique integer id representing a bus address of the USB device on the server$PRODUCT_ID$- The 4 digit hexadecimal USB Product Id of the device$VENDOR_ID$- The 4 digit hexadecimal USB Vendor Id of the device$DEVPATH$- The unique USB path of the device the Operating System uses to represent the device
These are the events that the VirtualHere server provides callbacks to. Some events have extra arguments that can be passed and these are noted below. [ ] means optional qualifier
onBind[.<vendor_id>[.<product_id>]] - Occurs when the user right clicks on a USB Device and selects Use in the VirtualHere client
You can also use these variables in this event:
$CLIENT_IP$- The IP address of the remote VirtualHere client attempting to use the USB device remotely.$CLIENT_HOSTNAME$- The hostname of the remote VirtualHere client (if any).$CONNECTION_ID$- The unique integer id of a connection session between the client and server. This changes on every new connection. This is useful to know if a connection dropped and returned because the connection id will be different.$NICKNAME$- nickname of the device if one is set. This is set by the user right clicking on the device in the VirtualHere client and selecting Device Properties -> Rename$SERIAL$- the serial number of the USB device if one exists$PRODUCT$- the product name of the USB device as supplied by the vendor
onEnumeration[.<vendor_id>[.<product_id>]] - Occurs when the USB device goes through enumeration. Enumeration is when the USB device is detected as being initially connected by the operating system on the server.
You can also use these variables in this event:
$NICKNAME$- nickname of the device if one is set$SERIAL$- the serial number of the USB device if one exists$PRODUCT$- the product name of the USB device as supplied by the vendor
onDeviceUnplug[.<vendor_id>[.<product_id>]] - Occurs when the USB device is physically unplugged from the server
You can also use these variables in this event:
$NICKNAME$- nickname of the device if one is set$SERIAL$- the serial number of the USB device if one exists$PRODUCT$- the product name of the USB device as supplied by the vendor
onReset[.<vendor_id>[.<product_id>]] - Occurs when a device is required to be "reset", which means a logical unplug/replug, without being physically removed
onPassToKernel[.<vendor_id>[.<product_id>]] - Occurs when a USB device is not being used via VirtualHere and is reattached to the server kernel.
onClearHalt[.<vendor_id>[.<product_id>]] - Occurs when a USB device endpoint has the USB Clear Halt request applied to it
onResetEp[.<vendor_id>[.<product_id>]] - Occurs when a USB device has the Reset Endpoint operation applied to it
onUnbind[.<vendor_id>[.<product_id>]] - Occurs when a device is unbound from a user - i.e when the User selects Stop Using in the VirtualHere Client.
You can also use these variables in this event:
$SURPRISE_UNBOUND$. This will be replaced with1if the device was pulled from the server while it was currently in-use by the client.$CLIENT_ID$- The operating system username/name of the user who is logged in at the VirtualHere client and has selected "Stop Using"$CLIENT_IP$- The IP address of the remote VirtualHere client$CONNECTION_ID$- The unique integer id of a connection session between the client and server. This changes on every new connection$NICKNAME$- nickname of the device if one is set.
onServerRename - This event is called when the user attempts to rename the server by right clicking the Server and selecting Server Properties->Rename. **Note: If you return 1 from the script the rename occurs, anything else (or nothing) and the rename will not occur.**
You can also use these variables in this event:
$NEW_NAME$- the new name of the Server which is attempting to be set$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has attempted the server rename.$CLIENT_IP$- The IP address of the remote VirtualHere client attempting the rename.$CONNECTION_ID$- The unique integer id of a connection session between the client and server. This changes on every new connection
onChangeNickname - This event is called when the user right-clicks on a USB Device in the VirtualHere Client and selects Device Properties -> Rename.**Note: If you return 0 the nickname will be accepted, anything else and the nickname will not be changed.**
You can also use these variables in this event:
$NICKNAME$- the existing nickname of the USB device$NEW_NICKNAME$- the new nickname of the USB device$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has attempted to rename the device$CLIENT_IP$- The IP address of the remote VirtualHere client attempting the rename.
Using this event you can block some (or all users) from renaming a USB device by returning either a 0 or 1 and qualifying the uservia the $CLIENT_ID$ variable.
onDeviceIgnore - This event is called when the user right-clicks on a device and selects Ignore.**Note: If you return 0 the ignore will be silently rejected, if you return 1 the ignore will be accepted, if you return 2 the ignore will be rejected and a message sent to the client saying "Unauthorized operation". **
You can also use these variables in this event:
-
$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has attempted to ignore the device $CLIENT_IP$- The IP address of the remote VirtualHere client attempting the ignore.$CLIENT_HOSTNAME$- The hostname of the remote VirtualHere client (if any).$SERIAL$- the serial number of the USB device being ignored
onDeviceUnignore - This event is called when the user tries to unignore a device. A device is unignored by right clicking on the Server the VirtualHere Client, selecting Server Properties -> (Unignore) **Note: If you return 0 the unignore will be silently rejected, if you return 1 the unignore will be accepted, if you return 2 the unignore will be rejected and a message sent to the client saying "Unauthorized operation" **
You can also use these variables in this event:
-
$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has attempted to unignore the device $CLIENT_IP$- The IP address of the remote VirtualHere client attempting to remove the ignore$CLIENT_HOSTNAME$- The hostname of the remote VirtualHere client (if any).-
$UNIGNORE$- This is a string containing the USB VendorId USB Product Id and Serial concatenated of the ignore that is being removed
onAddReverseClient - This event is called when the user tries to add a reverse client to the server via the Client. A reverse client is an IP address of a remove client which the server will attempt to connect to. **Note: If you return 1 the reverse client will be added, anything else and it will not be added.**
You can also use these variables in this event:
-
$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has attempted to add a new reverse client IP address by right clicking on the Server and selecting Reverse Clients... -> Add $CLIENT_IP$- The IP address of the remote VirtualHere client attempting to add the reverse client.
onRemoveReverseClient - This event is called when the user tries to remove a reverse client from the server via the Client. **Note: If you return 1 the reverse client will be removed, anything else and it will not be removed.**
You can also use these variables in this event:
-
$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has attempted to remove a reverse client IP address by right clicking on the Server and selecting Reverse Clients... -> Remove $CLIENT_IP$- The IP address of the remote VirtualHere client attempting to remove the reverse client.
onClientConnect - This event is called when a new client connects to the server.
You can also use these variables in this event:
$CLIENT_IP$- the IP address of the remote VirtualHere Client about to connect-
$CONNECTION_ID$- the unique id number assigned to the client connection. You can use this id to match the disconnect at a later time.
onClientDisconnect - This event is called when a client disconnects from the server.
You can also use these variables in this event:
$CONNECTION_ID$- the unique id number that was assigned to the client connection session.$REASON$- the reason why there was a disconnection. It is replaced with the stringtimeoutorserver shutdown$CLIENT_ID$- The operating system username/name of the user who is logged in at the virtualhere client and has disconnected
There are a few more authorization/authentication events here here
Example:
In the server config.ini file a line might contain:
onUnbind.4ca.3911=/home/vh/onUnbind.sh "$DEVPATH$" "$ADDRESS$" "$VENDOR_ID$" "$PRODUCT_ID$"
In the onUnbind.sh file:
#!/bin/sh
logger onUnbind "$1" "$2" "$3" "$4"
Output in syslog:
onUnbind "/sys/bus/usb/devices/2-2" "22" "4ca" "3911"
.
See authorization here https://www.virtualhere.com/authorization for more events that can be hooked