Phidget Manager

General Overview

The Phidget Manager is an interface into the device channels available to the Phidget library. The API is strictly asynchronous, and continuously monitors channels as they attach and detach.

Each Phidget exports one or more device channels, and when a Phidget is plugged into a system (or becomes available over the network), a manager attach event is fired for each channel available from the Phidget. When the Phidget is removed from the system, a manger detach event is fired for each channel that is no longer available.

It is important to understand the concepts of attach and detach as the they relate to the manager. A manager attach does not imply that a user channel has attached to a device channel, but that the device channel has appeared, and the device channel is now ready to be attached to a user channel. When a user channel closes and detaches from a device channel, a manager event is not fired. A manager detach event is fired when the Phidget is removed from the system.

Purpose

The primary function of a Phidget Manager is to fire an attach event for each new device channel when a Phidget becomes available to a system, and to fire a detach event for each device channel that is no longer available when the Phidget is removed from the system. For example, when a 1044_0 - PhidgetSpatial is connected, a Phidget Manager would fire three attach events, one for each device channel, as illustrated below:

Using the Phidget Manager

Much like a Phidget channel, a Phidget Manager must be created and opened. Refer to the Phidget22 API for details.

As soon as a manager is opened the Phidget library will fire an event for each device channel that is currently know to the system. After those initial events, attach and detach events will be fired when new Phidgets become available or existing Phidget are removed.

In the C programming language, it is not safe to refer to a PhidgetHandle after an event handler returns, unless Phidget_retain() is first called (Phidget_open() and Phidget_close() retain and release handlers automatically). The PhidgetHandle must be released with Phidget_release() if it has been retained. The object oriented languages supported in the Phidget22 API automatically retain and release handles.

What follows is an example of how to use a manager in C:

static void CCONV
mgrAttachHandler(PhidgetManagerHandle mgr, void *ctx, PhidgetHandle mgrch) {

    PhidgetLog_log("%P attached", mgrch);
}

static void CCONV
mgrDetachHandler(PhidgetManagerHandle mgr, void *ctx, PhidgetHandle mgrch) {

    PhidgetLog_log("%P detached", mgrch);
}

int
main(int argc, char **argv) {
    PhidgetManagerHandle mgr;

    PhidgetManager_create(&mgr);

    PhidgetManager_setOnAttachHandler(mgr, mgrAttachHandler, NULL);
    PhidgetManager_setOnDetachHandler(mgr, mgrDetachHandler, NULL);

    PhidgetManager_open(mgr);

    /* Do something long running, like run a GUI threads */
 
    /* Now close and delete the manager */
    PhidgetManager_close(mgr);
    PhidgetManager_delete(&mgr);
    exit(0);
}

A further example would be "HelloWorld" for most supported languages uses the Phidget Manager.

Opening a Manager Channel

A manager channel passed to a Phidget Manager attach handler is assigned all of the matching parameters for the Phidget device and the device channel the manager channel refers to; however, the manager channel is not attached to the device channel, and is not receiving data and status information from the device.

User code may Open() a manager channel, and just like a channel created by the user code, the Phidget library will begin trying to match the manager channel with a device channel. User code may also set attach and detach handlers on the manager channel, and set change event handlers. The manager channel can be treated exactly the same as a user channel.