>Introduction

Using plugins

Programming model

Exported functions

PluginHID_Definition

PluginHID_Information

HID methods

Introduction

Packetizer® Labs PacPhone utilizes plug & play methodology to support USB Audio Devices. A USB device is automatically set when a supported USB device is detected. The design of the interface is very scalable and one or many USB devices can be supported within the one driver. Almost any USB Audio device can be supported within the software by the inclusion of a generic C driver dll placed into the software main directory. On startup the manufacturers driver is detected and loaded and when the USB device is inserted in the computer the software automatically switches audio and key input to that device. The device can be removed and replaced at any time. If a device is not found then the audio is directed to the sound device specified in the software settings.

Using plugins

Installing a HID (Hardware Interface Device) plugin consists of copying the DLL file into the root directory of the PacPhone software usually “c:\{program files}\PacPhone\”. The only condition is that all plugins must have a name that ends in "_pwplugin.dll" and strictly adhere to the specified design criteria.

Programming model

A HID plugin interoperates with the PacPhone by exporting a set of tables that contain all of the data and functions that are needed to access and use the USB device. These tables provide a model of the device to be interpreted within the PacPhone software to correcting interoperate with the device. 

All of the structures and definitions required by this plugin interface are contained in the file opalplugin.h which is provided as part of the OpenH323 source package. A copy of this file and a sample HID plugin code can be downloaded from here. 

Exported functions

A plugin exports two functions in order to be accessible as a codec plugin. Note that these are exported as "C" functions - if the plugin is written in C++, then these names must be exported with unmangled functin names. 

unsigned int PWLibPlugin_GetAPIVersion()

This function is required by all PWLib plugins. 

Return value: the PWLib Plugin API version supported by the plugin. The only version currently supported is "0".

Pluginhid_Definition * OpalHIDPlugin_GetDevice(unsigned * count, unsigned version)

Returns the tables defining the HID interface and parameters 

count: The integer value pointed to by this parameter must be set to the number of elements in the table pointed to by the return value.

version: Specifies the version of the codec plugin interface supported. ( Only 1 is supported )

Return value: Pointer to an array of structures that describe the HID implemented by the plugin. The format of the structures is described below. If NULL, no HID's are defined.  

PluginHID_Definition

The OpalHIDPlugin_GetDevice function returns a pointer an array of structures that provide the primary interface to a HID conversion method. The definition of this structure is as follows:

struct PluginHID_Definition {

unsigned int version; // codec structure version

struct PluginHID_information * info; // license information

unsigned int flags; // PluginHID_Flags,

const char * descr; // text decription

const char * sound; // sound device name

void * (*createHID)(const struct PluginHID_Definition * def); // create HID

void (*destroyHID) (const struct PluginHID_Definition * def); // destroy HID

unsigned int (*HIDFunction) (const struct PluginHID_Definition * def,

unsigned int * InputMask, unsigned int * newVal); // do HID function (Polling Function)

void (*displayHID) (const struct PluginHID_Definition * def, const char * display); // LCD display

};

The meaning of each field is as follows: 

PluginHID_Information

This structure identifies the author of the codec and the plugin interface, as well as indicating what license is applied. It has the following structure:

struct PluginHID_information {

time_t timestamp; // codec creation time and date - obtain with command: date -u "+%c = %s"

const char * sourceAuthor; // source code author

const char * sourceVersion; // source code version

const char * sourceEmail; // source code email contact information

const char * sourceURL; // source code web site

const char * sourceCopyright; // source code copyright

const char * sourceLicense; // source code license

unsigned char sourceLicenseCode; // source code license

const char * HIDDescription; // HID description

const char * HIDManufacturer; // HID Manufacturer

const char * HIDModel; // HID Model

const char * HIDEmail; // HID email contact information

const char * HIDURL; // HID Manufacturer web site

};

HID methods

A HID interface provides four functions that can be used to perform HID function and operations. 

1. The createHID function is used to create a context for a particular instance of a HID. It can also be used to provide any initialisation before the HID is started.

2. The destroyHID function is used to destroy the context created by the createHID function. It can also be used to perform any cleanup after the HID has been stopped.

3. The HIDFunction is used to perform the polling and collecting of events from the HID device.  

4. The displayHID is used to send display information to the HID's LCD display if present

void * createHID(const struct PluginHID_Definition * hid);

Allocates and initialises any instance data required by a hid

hid: pointer to the PluginHID_Definition that defines the HID being created. This allows the same createHID function to be used for different HID devices. 

Return value: pointer to the created instance data  

void destroyHID(const struct PluginHID_Definition * hid, void * context);

Uninitialises and frees any instance data required by a HID

hid: pointer to the PluginHID_Definition that defines the HID being distroyed. This allows the same destroyHID function to be used for different HID devices. 

context: pointer to the context data to be freed 

int HIDFunction(const struct PluginHID_Definition * hid, unsigned int * InputMask, unsigned int * newVal);

Interprets input/output from the USB device. This checks every 100 ms for events from the USB device

hid: pointer to the PluginHID_Definition that defines the HID being monitored.

InputMask: pointer to an integer containing the events being collected from the HID (see below for values)

newVal: pointer to the new value to set in the HID (usually ring/stop ring etc) (see below for values)

Return value: If 1, the data was converted successfully. If 0, then some error occurred during the process.

Input Mask Values

void display_HID(const struct PluginHID_Definition * def, const char * display)

hid: pointer to the PluginHID_Definition that defines the HID which has been created.

display: pointer to zero-terminated string giving the details to display on the HID device.

Copyright © 2007 by Packetizer Labs
All Rights Reserved
All trademarks and copyrights on this page are owned by their respective owners.