Client API

1 post / 0 new
Michael
Client API

The VirtualHere USB Client can be controlled by another program or on the command line. This is useful when:

  • You want to control the VirtualHere Client when running as a service
  • You want to control the client via a console only session e.g. ssh
  • You want to build a custom graphical interface to VirtualHere via a programming language of your choice
  • You would like to control VirtualHere inside a batch file (Windows) or bash (OSX/Linux) script

When the VirtualHere USB Client runs as a service or application it is controllable over a Named pipe. The named pipe is called \\.\pipe\vhclient (for requests and responses) in Windows, and /tmp/vhclient (for requests) and /tmp/vhclient_response (for responses) in OSX and Linux. You can use any program language or even just the command prompt to control the client, no special dll or language bindings are required! A named pipe is just like a normal file. To contol the client the named pipe needs to be opened and sent a text string in the format <verb>[,arg] followed by a newline character. The client will perform the action corresponding to the verb specified and will return a response string in the response pipe. You can even use the VirtualHere client binary itself to send commands to another instance of the client via the -t parameter, so you dont have to bother writing your own pipe reader/writer

Windows does not have the concept of a console like in POSIX systems(Linux/OSX) for redirection, so if you are calling vhui from a Windows batch file you should use the -r argument with a filename to return the result and parse that (see below).

Anyone can use the API, no special SDK or program library needed!

Run the client with the argument -t HELPto get the list of available commands, e.g

C:\Users\michael>vhui64.exe -t help

VirtualHere Client (v4.1.4) IPC commands (<> = required, [] = optional):

List devices:
    "LIST"
Get the detailed full client state as an XML Document:
    "GET CLIENT STATE"
Use a device:
    "USE,<address>[,password]"
Stop using a device:
    "STOP USING,<address>"
Stop using all devices on all clients:
    "STOP USING ALL"
Stop using all devices just for this client:
    "STOP USING ALL LOCAL"
Device Information:
    "DEVICE INFO,<address>"
Server Information:
    "SERVER INFO,<server name>"
Set device nickname:
    "DEVICE RENAME,<address>,<nickname>"
Rename server:
    "SERVER RENAME,<hubaddress:port>,<new name>"
Turn auto-use all devices on:
    "AUTO USE ALL"
Turn Auto-use all devices on this hub on/off:
    "AUTO USE HUB,<server name>"
Turn Auto-use any device on this port on/off:
    "AUTO USE PORT,<address>"
Turn Auto-use this device on any port on/off:
    "AUTO USE DEVICE,<address>"
Turn Auto-use this device on this port on/off:
    "AUTO USE DEVICE PORT,<address>"
Clear all auto-use settings:
    "AUTO USE CLEAR ALL"
Manually specify a hub to connect to:
    "MANUAL HUB ADD,<address>[:port]"
Remove a manually specified hub:
    "MANUAL HUB REMOVE,<address>[:port]"
Remove all manually specified hubs:
    "MANUAL HUB REMOVE ALL"
Add a reverse client to the server:
    "ADD REVERSE,<server address[:port]>,<client address[:port]>"
Remove a reverse client from the server:
    "REMOVE REVERSE,<server address[:port]>,<client address[:port]>"
List manually specified hubs:
    "MANUAL HUB LIST"
List licenses:
    "LIST LICENSES"
License server:
    "LICENSE SERVER,<license key>"
Clear client log:
    "CLEAR LOG"
Set a custom device event:
    "CUSTOM EVENT,<address>,<event>"
Turn auto-find off:
    "AUTOFIND"
Turn reverse lookup on:
    "REVERSE"
Shutdown the client:
    "EXIT"
Help:
    "HELP"

E.g: To get a list of devices, vhui64.exe -t "LIST"
E.g: Use a device, vhui64.exe -t "USE,QNAP.114"

When a command succeeds it will return "OK" and 0 will be returned to the shell, if a command fails it will return "FAILED" and 1 will be returned to the shell (e.g trying to use an in-use device), or "ERROR: error string" and 2 will be returned to the shell (e.g if the server doesnt exist or the address is invalid)

For example in Windows:

Make sure the client is already running either normally as an application (visible as a green USB icon in the taskbar) or as a background service. We will use the VirtualHere binary itself as the named pipe client to issue commands to the running instance. You need to wrap the command in quotes " because windows will misinterpret commands with spaces. First change to the directory with the VirtualHere client binary is then type vhui64.exe -t "LIST". That will send the LIST command to the running client. It will return something similar to the following:

C:\Users\michael>vhui64.exe -t list
VirtualHere IPC, below are the available devices:
(Value in brackets = address, * = Auto-Use)

Raspberry Hub (raspberrypi:7575)
   --> Ultra USB 3.0 (raspberrypi.114)
QNAP Hub (QNAP:7575)
   --> ADATA USB Flash (QNAP.22)
   --> STORE N GO (QNAP.11)
Synology Hub (synology:17570)
   --> eLicenser (synology.1134)
   --> WIBU-BOX/U (synology.1144)
   --> FT230X Basic UART (synology.1141)
   --> Extreme (synology.1132)
   --> CP2102 USB to UART Bridge Controller (synology.1114)
ASUSTOR Hub (ASUS:7575)
ReadyNAS Hub (readynas:7575)
   --> ASMT1051 (readynas.32)
   --> STORE N GO (readynas.11)

Auto-Find currently on
Auto-Use All currently off
Reverse Lookup currently off
VirtualHere not running as a service

C:\Users\michael>

From this output you can see the client is attached to five USB servers Raspberry Hub at the host raspberrypi:7575, QNAP Hub at host QNAP:7575 etc... and for example, the Synology Hub has 5 devices attached.

For example the USB stick "STORE N GO" attached to the ReadyNAS hub is at address readynas.11, to use this type vhui64.exe -t "USE,readynas.11", and an OK will be returned to the console.

To stop using the USB stick type: vhui64.exe -t "STOP USING,readynas.11"

To automatically auto-use any device plugged into the Readynas Hub type vhui64.exe -t "AUTO USE HUB,readynas:7575"

A Windows batch file example

This example will show how to correctly parse the result of an IPC command inside a windows batch file. We use the -r argument to redirect the result to a file and then we load the file into the variable RS. It is done this way because Windows doesn't support error codes like linux/osx does.
Firstly run the following batch file without having another client instance running,it will return "IPC ERROR" because there is no client to communicate with. Start a vhui64.exe instance then run the batch file again and it will return "IPC OK, do stuff with result in RS".

@echo off
vhui64.exe -t LIST -r out.txt
set /p RS=<out.txt
IF "%RS:~0,6%"=="FAILED" (
  ECHO "IPC failed"
) ELSE (
  IF "%RS:~0,5%"=="ERROR" (
    ECHO "IPC ERROR"
  ) ELSE (
    ECHO "IPC OK, do stuff with result in RS"
  )
)

Another Windows batch file example

When vhui64.exe is running as a service or in the gui in Windows...

vhui64.exe -t "LIST" -r "out.txt"
FOR /F "tokens=*" %%i IN (out.txt) DO @ECHO %%i

The for loop reads each line in the output (out.txt) and echos it to the script as an example. You can change the "ECHO" command to do something useful, for example to parse the "LIST" argument

C++ example in Windows

Here is some example C++ code for Windows (also using wxWidgets) that will communicate with a running instance of the VirtualHere Client


#define IPCPATH "\\\\.\\pipe\\vhclient"

bool WindowsIPCClient::issueIPCCommand(const wxString& request, wxString& response, bool silent)
{
  response = "";
  bool result = true;
  wxMessageOutputBest consoleLog;
  HANDLE hPipe;
  while (true)
  {
    hPipe = CreateFile(TEXT(IPC_PATH), GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, 0, NULL);
    if (hPipe != INVALID_HANDLE_VALUE)
    {
      break; // ok we opened pipe as a client
    }
    if (GetLastError() == ERROR_PIPE_BUSY) // pipe is busy try again for 2 seconds
    {
      if (!WaitNamedPipe(TEXT(IPC_PATH), 2000))
      {
        if (!silent)
        {
          consoleLog.Printf("IPC client WaitNamedPipe, error timeout");
        }
        result = false;
        break;
      }
    }
    else
    {
      if (!silent)
      {
        consoleLog.Printf("IPC client CreateFile failed, error %lu (%s)", wxSysErrorCode(), wxSysErrorMsg(wxSysErrorCode()));
      }
      result = false;
      break;
    }
  }
  if (result) // if we have a valid pipe
  {
    DWORD dwMode = PIPE_READMODE_MESSAGE;
    if (SetNamedPipeHandleState(hPipe, &dwMode, NULL, NULL))
    {
      DWORD bytesWritten;
      BOOL fSuccess = WriteFile(hPipe, request.c_str(), request.Length(), &bytesWritten, NULL); // * NOTE: DO NOT PASS NULL TERMINATOR *
      if (fSuccess)
      {
        DWORD bytesRead;
        char buffer[BUFFER_SIZE] = { 0 };
        fSuccess = ReadFile(hPipe, buffer, BUFFER_SIZE, &bytesRead, NULL);
        if (!fSuccess)
        {
          if (!silent)
          {
            consoleLog.Printf("IPC client ReadFile failed, error %lu (%s)", wxSysErrorCode(), wxSysErrorMsg(wxSysErrorCode()));
          }
          result = false;
        }
        else
        {
          response.Append(buffer);
        }
      }
      else
      {
        if (!silent)
        {
          consoleLog.Printf("IPC client WriteFile failed, error %lu (%s)", wxSysErrorCode(), wxSysErrorMsg(wxSysErrorCode()));
        }
        result = false;
      }
    }
    else
    {
      if (!silent)
      {
        consoleLog.Printf("IPC client SetNamedPipeHandleState failed, error %lu (%s)", wxSysErrorCode(), wxSysErrorMsg(wxSysErrorCode()));
      }
      result = false;
    }
    CloseHandle(hPipe);
  }
  return result;
}

Client-side Events

Calls to a windows batch file or bash script can be made by the client on certain events. These events are set by right clicking on the device in the virtualhere client and selecting "Custom Event Handler..."

onClientBeforeBind - occurs just before a remote device is bound to the client
onClientAfterBind - just after...
onClientBeforeUnbind - just before a remote device is UNbound from the client
onClientAfterUnbind - just after...

Events are qualifed by the device vendor id,product or and optionally the server usb port

For example in Windows, say you wanted to bring up the printer dialog when a particular printer is connected via VirtualHere. In the VirtualHere client, right click on the Printer and select "Custom Event Handler..." then enter exactly this:

onClientAfterBind.$VENDOR_ID$.$PRODUCT_ID$=control printers

and click OK. The client will replace the $VENDOR_ID$ and $PRODUCT_ID$ with the actual USB vendor and product id of the printer and save this event permanently. Now when you right click on the Printer in the VirtualHere client and select "Use" - after the remote printer has bound to the local client the batch file start "control printers" will be run. The client will wait for the script to exit so you should use the start windows command to run it in the background.

If you would like to run the event batch file with elevated privileges in Windows just include the $ELEVATE$at the beginning of the entry, the string will be removed by the client before execution as an administrator e.g

onClientAfterBind.$VENDOR_ID$.$PRODUCT_ID$=$ELEVATE$control printers