Phidget21 C API Documentation

2.1.9

Describes the Application Program Interface (API) for each Phidget device. The API can be used by a number of languages; this manual discusses use via C and the code examples reflect this.

How to use Phidgets

Phidgets are an easy to use set of building blocks for low cost sensing and control from your PC. Using the Universal Serial Bus (USB) as the basis for all Phidgets, the complexity is managed behind this easy to use and robust Application Program Interface (API) library.

The library was written originally for Windows, but has been ported to MacOS and Linux. Although the library is written in C, the functions can be called from a number of languages including C#, C/C++, Java, Python, Visual Basic, and many more. The full library source is not available for all platforms - however, the Linux distribution contains all platform independent code.

See the Modules section for the API documentation.

See Phidget Common for calls common to all phidgets.

Refer to the User Guide for your device and the General Phidget Programming page for more detailed, language inspecific API documentation and examples. You can download a set of C/C++ example code from the Quick Downloads section of the C/C++ Language Page.

General Usage

Phidgets in C are accessed/controlled via handles. Every Phidget has it's own Handle, as well as a generic Phidget handle. These handles are simply pointers from the user's perspective - internally, they point to structures. Almost every function in the API takes a Phidget handle as the first argument.

phidget21.h contains the API calls for all Phidgets. It should be included in any programs which need to access the Phidget C Library from C/C++.

Note that this file is not distributed in the source, this file is generated from the source using the C preproccessor. It is installed with the libraries.

The first step is to create the handle. Every phidget has it's own _create function. This creates space for the structure internally and gives you a valid Handle for passing to all other Phidget functions.

The next step is to register event handlers. These need to be registered now, because they only throw events in the future, and if they are registered later, you will miss events. Every Phidget event takes a Phidget handle, a function callback pointer and a user defined pointer, which is passed back from within the callback.

The next step is to open the Phidget. This is done with either CPhidget_open, CPhidget_openRemote or CPhidget_openRemoteIP, depending on whether you want to open the Phidget locally or over the network. Open returns right away (is asynchronous) so you have to either wait for the attach event, or call CPhidget_waitForAttachment before using the handle further.

The next step it to actually use the Phidget. Once attached, all functions can be called. Device specific handles should be cast to CPhidgetHandle for use with the common API functions.

Once finished, you should call first CPhidget_close and then CPhidget_delete to clean up the connection to the Phidget and the Handle before exiting.

Return Codes

Every Phidget function returns an int. A return code of 0 means success, anything else means failure. The failure codes are documented here: Phidget Constants.

When a value is unknown, in addition to returning an error code, the pointer will be set to one of the unknonwn values documented here: Phidget Constants.