VirtualHere Server Event System

1 post / 0 new
Michael
VirtualHere Server Event System

The VirtualHere server can make callbacks to scripts on certain events. Sometimes USB devices need certain commands to be sent to them to workaround their in-built differences (or quirks). Most USB devices will work with VirtualHere without having to set anything special in the configuration. You can also use the event system for special logging e.g bind/unbind of devices for time based usage.

However some devices like iPads/iPods and some phones require certain commands to be sent on specific events to function properly. VirtualHere will automatically generate the special events for iPad/iPhone/iPod2G and Galaxy S without requiring any changes by you.

Devices that VirtualHere does not have default quirk handlers for will require special configuration:

The way the VirtualHere server handles this is to provide a callback mechanism to enable a bash script to be executed to issue commands. The callback mechanism is specified in the server configuration. The event type is specified and a dot, then vendor id and optionally a dot and product id that the quirk is specified for. If no product id is specified, all products from that vendor have the quirk script executed against.

For example the default iPad scripts are as follows (written inside the server config.ini)

onEnumeration.05ac=cat $DEVPATH$/bNumConfigurations > $DEVPATH$/bConfigurationValue
onBind.05ac=cat $DEVPATH$/bNumConfigurations > $DEVPATH$/bConfigurationValue

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 its first plugged in and when it is "used" by a remote client. This allows proper operation of the iDevice.

For each event you can pass at least the following arguments:

$ADDRESS$ Address of the device on the server
$PRODUCT_ID$ The USB product id of the device
$VENDOR_ID$ The USB Vendor id of the device
$DEVPATH$ The USB path of the device the Operating System uses to represent the device

There are 12 events that the VirtualHere server provides callbacks to. (Some events have extra arguments that can be passed and these are noted below.)

onBind.<vendor_id>[.<product_id>] - Occurs when the user selects "Use" on the client.

onEnumeration.<vendor_id>[.<product_id>] - Occurs when the USB device goes through "enumeration" when it is first plugged into the server

onReset.<vendor_id>[.<product_id>] - Occurs when a device is required to be "reset"

onPassToKernel.<vendor_id>[.<product_id>] - Occurs when a device control is passed from VirtualHere (for example if the device or bus is ignored) to the Linux Kernel (host).

onClearHalt.<vendor_id>[.<product_id>] - Occurs when a device endpoint has the USB "clear halt" applied to it

onResetEp.<vendor_id>[.<product_id>] - Occurs when a device has the linux "reset endpoint" operation applied to it

onUnbind.<vendor_id>[.<product_id>] - Occurs when a device is unbound from a user, e.g the User selects "Stop Using". You can use the $SURPRISE_UNBOUND$ statement in the arguments to the script. That will return 1 if the device was pulled from the server while it was in use by the client.

onServerRename - This event is called when the user renames the server by right clicking it in the Client GUI. You can pass the script $NEW_NAME$ as an argument to the script call.

onChangeNickname - This event is called when the user clicks on a device and selects "Rename". If you return 0 the nickname will be accepted, anything else and the nickname will not be accepted. You can use the string $NICKNAME$ and $NEW_NICKNAME$ in the script call to get the old/new nickname for use in your script. You can pass $CLIENT_ID$ and $CLIENT_IP$ as arguments to the script call for information about the client making the call.

onDeviceIgnore - This event is called when the user clicks on a device and selects "Ignore". If you return 1 the ignore will be accepted, anything else and the ignore will not occur. You can pass $CLIENT_ID$ and $CLIENT_IP$ as arguments to the script call for information about the client making the call. You can also use $VENDOR_ID$ and $PRODUCT_ID$ to get information about the device being ignored

onAddReverseClient - This event is called when the user tries to add a reverse client to the server via the Client. If you return 1 the reverse client will be added, anything else and it will not be added. You can pass $CLIENT_ID$ and $CLIENT_IP$ as arguments to the script call for information about the client making the call.

onRemoveReverseClient - This event is called when the user tries to remove a reverse client from the server via the Client. If you return 1 the reverse client will be removed, anything else and it will not be removed. You can pass $CLIENT_ID$ and $CLIENT_IP$ as arguments to the script call for information about the client making the call.

The USB Specification provides exact definitions of "enumeration" and "reset", and "clear halt"

Example:

In the server config.ini file:

...
...
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"

Contact mail@virtualhere.com for help with setting your device quirks.