From 6b2aa4a4a7816d604ee63c974131c03fed9a4b7c Mon Sep 17 00:00:00 2001 From: Hans-Christoph Steiner Date: Thu, 28 Jan 2010 00:37:54 +0000 Subject: first working version of hidio+HIDUtilities build on Mac OS X using autotools, still needs work svn path=/trunk/externals/io/hidio/; revision=13107 --- HID_Utilities_Source/HID_Utilities_External.h | 509 ++++++++++++++++++++++++++ 1 file changed, 509 insertions(+) create mode 100644 HID_Utilities_Source/HID_Utilities_External.h (limited to 'HID_Utilities_Source/HID_Utilities_External.h') diff --git a/HID_Utilities_Source/HID_Utilities_External.h b/HID_Utilities_Source/HID_Utilities_External.h new file mode 100644 index 0000000..62a52ec --- /dev/null +++ b/HID_Utilities_Source/HID_Utilities_External.h @@ -0,0 +1,509 @@ +/* + File: HID_Utilities_External.h + + Contains: Definition of the HID Utilities exported functions + External interface for HID Utilities, can be used with either library or source + Check notes below for usage. Some type casting is required so library is framework and carbon free + + DRI: George Warner + + Copyright: Copyright © 2002 Apple Computer, Inc., All Rights Reserved + + Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Computer, Inc. + ("Apple") in consideration of your agreement to the following terms, and your + use, installation, modification or redistribution of this Apple software + constitutes acceptance of these terms. If you do not agree with these terms, + please do not use, install, modify or redistribute this Apple software. + + In consideration of your agreement to abide by the following terms, and subject + to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs + copyrights in this original Apple software (the "Apple Software"), to use, + reproduce, modify and redistribute the Apple Software, with or without + modifications, in source and/or binary forms; provided that if you redistribute + the Apple Software in its entirety and without modifications, you must retain + this notice and the following text and disclaimers in all such redistributions of + the Apple Software. Neither the name, trademarks, service marks or logos of + Apple Computer, Inc. may be used to endorse or promote products derived from the + Apple Software without specific prior written permission from Apple. Except as + expressly stated in this notice, no other rights or licenses, express or implied, + are granted by Apple herein, including but not limited to any patent rights that + may be infringed by your derivative works or by other works in which the Apple + Software may be incorporated. + + The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO + WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED + WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN + COMBINATION WITH YOUR PRODUCTS. + + IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE + GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION + OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT + (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * +*/ + +#ifndef _HID_Utilities_External_h_ +#define _HID_Utilities_External_h_ +// ================================== +#if PRAGMA_ONCE +#pragma once +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#if PRAGMA_IMPORT +#pragma import on +#endif + +#pragma options align=mac68k +// ================================== +//includes + +#if TARGET_RT_MAC_CFM +// from IOHIDKeys.h (IOKit) +// this can't be included since the orginal file has framework includes +// developers may need to add definitions here +enum IOHIDElementType +{ + kIOHIDElementTypeInput_Misc = 1, + kIOHIDElementTypeInput_Button = 2, + kIOHIDElementTypeInput_Axis = 3, + kIOHIDElementTypeInput_ScanCodes = 4, + kIOHIDElementTypeOutput = 129, + kIOHIDElementTypeFeature = 257, + kIOHIDElementTypeCollection = 513 +}; +typedef enum IOHIDElementType IOHIDElementType; + +enum IOHIDReportType +{ + kIOHIDReportTypeInput = 0, + kIOHIDReportTypeOutput, + kIOHIDReportTypeFeature, + kIOHIDReportTypeCount +}; +typedef enum IOHIDReportType IOHIDReportType; +typedef void (*IOHIDCallbackFunction)(void * target, unsigned long result, void* refcon, void * sender); +typedef void* IOHIDEventStruct; +#else + #include +#endif TARGET_RT_MAC_CFM + +#if 0 +#include + +#include "PID.h" // NOTE: These are now in +#include "IOHIDPowerUsage.h" // NOTE: These are now in +#endif + +#include + +// ================================== +// Device and Element Interfaces + +typedef enum HIDElementTypeMask +{ + kHIDElementTypeInput = 1 << 1, + kHIDElementTypeOutput = 1 << 2, + kHIDElementTypeFeature = 1 << 3, + kHIDElementTypeCollection = 1 << 4, + kHIDElementTypeIO = kHIDElementTypeInput | kHIDElementTypeOutput | kHIDElementTypeFeature, + kHIDElementTypeAll = kHIDElementTypeIO | kHIDElementTypeCollection +}HIDElementTypeMask; + +struct recElement +{ + unsigned long type; // the type defined by IOHIDElementType in IOHIDKeys.h + long usagePage; // usage page from IOUSBHIDParser.h which defines general usage + long usage; // usage within above page from IOUSBHIDParser.h which defines specific usage + void * cookie; // unique value (within device of specific vendorID and productID) which identifies element, will NOT change + long min; // reported min value possible + long max; // reported max value possible + long scaledMin; // reported scaled min value possible + long scaledMax; // reported scaled max value possible + long size; // size in bits of data return from element + unsigned char relative; // are reports relative to last report (deltas) + unsigned char wrapping; // does element wrap around (one value higher than max is min) + unsigned char nonLinear; // are the values reported non-linear relative to element movement + unsigned char preferredState; // does element have a preferred state (such as a button) + unsigned char nullState; // does element have null state + long units; // units value is reported in (not used very often) + long unitExp; // exponent for units (also not used very often) + char name[256]; // name of element (c string) + +// runtime variables + long initialCenter; // center value at start up + unsigned char hasCenter; // whether or not to use center for calibration + long minReport; // min returned value + long maxReport; // max returned value (calibrate call) + long userMin; // user set value to scale to (scale call) + long userMax; + + struct recElement * pPrevious; // previous element (NULL at list head) + struct recElement * pChild; // next child (only of collections) + struct recElement * pSibling; // next sibling (for elements and collections) + + long depth; +}; +typedef struct recElement recElement; +typedef recElement* pRecElement; + +struct recDevice +{ + void * interface; // interface to device, NULL = no interface + void * queue; // device queue, NULL = no queue + void * queueRunLoopSource; // device queue run loop source, NULL == no source + void * transaction; // output transaction interface, NULL == no interface + void * notification; // notifications + char transport[256]; // device transport (c string) + long vendorID; // id for device vendor, unique across all devices + long productID; // id for particular product, unique across all of a vendors devices + long version; // version of product + char manufacturer[256]; // name of manufacturer + char product[256]; // name of product + char serial[256]; // serial number of specific product, can be assumed unique across specific product or specific vendor (not used often) + long locID; // long representing location in USB (or other I/O) chain which device is pluged into, can identify specific device on machine + long usage; // usage page from IOUSBHID Parser.h which defines general usage + long usagePage; // usage within above page from IOUSBHID Parser.h which defines specific usage + long totalElements; // number of total elements (should be total of all elements on device including collections) (calculated, not reported by device) + long features; // number of elements of type kIOHIDElementTypeFeature + long inputs; // number of elements of type kIOHIDElementTypeInput_Misc or kIOHIDElementTypeInput_Button or kIOHIDElementTypeInput_Axis or kIOHIDElementTypeInput_ScanCodes + long outputs; // number of elements of type kIOHIDElementTypeOutput + long collections; // number of elements of type kIOHIDElementTypeCollection + long axis; // number of axis (calculated, not reported by device) + long buttons; // number of buttons (calculated, not reported by device) + long hats; // number of hat switches (calculated, not reported by device) + long sliders; // number of sliders (calculated, not reported by device) + long dials; // number of dials (calculated, not reported by device) + long wheels; // number of wheels (calculated, not reported by device) + recElement* pListElements; // head of linked list of elements + struct recDevice* pNext; // next device +}; +typedef struct recDevice recDevice; +typedef recDevice* pRecDevice; + +// ================================== +// HID Utilities interface +// ================================== +// Create and open an interface to device, required prior to extracting values or building queues +// Note: appliction now owns the device and must close and release it prior to exiting +extern unsigned long HIDCreateOpenDeviceInterface (UInt32 hidDevice, pRecDevice pDevice); + +// builds list of device with elements (allocates memory and captures devices) +// list is allcoated internally within HID Utilites and can be accessed via accessor functions +// structures within list are considered flat and user accessable, butnot user modifiable +// can be called again to rebuild list to account for new devices (will do the right thing in case of disposing existing list) +// usagePage, usage are each a numDeviceTypes sized array of matching usage and usage pages +// returns true if succesful + +extern Boolean HIDBuildMultiDeviceList (UInt32 *pUsagePage, UInt32 *pUsage, UInt32 numDeviceTypes); + +// same as above but this uses a single usagePage and usage + +extern Boolean HIDBuildDeviceList (UInt32 usagePage, UInt32 usage); + +// updates the current device list for any new/removed devices +// if this is called before HIDBuildDeviceList the it functions like HIDBuildMultiDeviceList +// usagePage, usage are each a numDeviceTypes sized array of matching usage and usage pages +// returns true if successful which means if any device were added or removed (the device config changed) + +extern Boolean HIDUpdateDeviceList (UInt32 *pUsagePage, UInt32 *pUsage, UInt32 numDeviceTypes); + +// release list built by above function +// MUST be called prior to application exit to properly release devices +// if not called (or app crashes) devices can be recovered by pluging into different location in USB chain +extern void HIDReleaseDeviceList (void); + +// does a device list exist +extern Boolean HIDHaveDeviceList (void); + +// how many HID devices have been found +// returns 0 if no device list exist +extern UInt32 HIDCountDevices (void); + +// how many elements does a specific device have +// returns 0 if device is invalid or NULL +// uses mask of HIDElementTypeMask to restrict element found +// use kHIDElementTypeIO to get non-collection elements +extern UInt32 HIDCountDeviceElements (pRecDevice pDevice, HIDElementTypeMask typeMask); + +// get the first device in the device list +// returns NULL if no list exists +extern pRecDevice HIDGetFirstDevice (void); + +// get next device in list given current device as parameter +// returns NULL if end of list +extern pRecDevice HIDGetNextDevice (pRecDevice pDevice); + +// get the first element of device passed in as parameter +// returns NULL if no list exists or device does not exists or is NULL +// uses mask of HIDElementTypeMask to restrict element found +// use kHIDElementTypeIO to get previous HIDGetFirstDeviceElement functionality +extern pRecElement HIDGetFirstDeviceElement (pRecDevice pDevice, HIDElementTypeMask typeMask); + +// get next element of given device in list given current element as parameter +// will walk down each collection then to next element or collection (depthwise traverse) +// returns NULL if end of list +// uses mask of HIDElementTypeMask to restrict element found +// use kHIDElementTypeIO to get previous HIDGetNextDeviceElement functionality +extern pRecElement HIDGetNextDeviceElement (pRecElement pElement, HIDElementTypeMask typeMask); + +// get previous element of given device in list given current element as parameter +// this walks directly up the tree to the top element and does not search at each level +// returns NULL if beginning of list +// uses mask of HIDElementTypeMask to restrict element found +// use kHIDElementTypeIO to get non-collection elements +extern pRecElement HIDGetPreviousDeviceElement (pRecElement pElement, HIDElementTypeMask typeMask); + +// ================================== +// Name Lookup Interfaces + +// returns C string type name given a type enumeration passed in as parameter (see IOHIDKeys.h) +// returns empty string for invlid types +extern void HIDGetTypeName (IOHIDElementType theType, char * cstrName); + +// set name from vendor id/product id look up (using cookies) +extern Boolean HIDGetElementNameFromVendorProductCookie (const long vendorID, const long productID, const long cookie, char * pName); + +// set name from vendor id/product id look up (using usage page & usage) +extern Boolean HIDGetElementNameFromVendorProductUsage (const long vendorID, const long productID, const long pUsagePage, const long pUsage, char * pName); + +// returns C string usage given usage page and usage passed in as parameters (see IOUSBHIDParser.h) +// returns usage page and usage values in string form for unknown values +extern void HIDGetUsageName (long valueUsagePage, long valueUsage, char * cstrName); + +// --------------------------------- +// convert an element type to a mask +extern HIDElementTypeMask HIDConvertElementTypeToMask (const long type); + +// find this device +extern Boolean HIDFindDevice(const pRecDevice pSearchDevice, pRecDevice *ppFoundDevice); + +// find the device and element for this action +// Device: serial, vendorID, productID, location, usagePage, usage +// Element: cookie, usagePage, usage, +extern Boolean HIDFindActionDeviceAndElement(const pRecDevice pSearchDevice, const pRecElement pSearchElement, + pRecDevice *ppFoundDevice, pRecElement *ppFoundElement); + +// find the device and element for this action +// Device: serial, vendorID, productID, location, usagePage, usage +// Element: cookie, usagePage, usage, + +extern Boolean HIDFindSubElement(const pRecElement pStartElement, const pRecElement pSearchElement, pRecElement *ppFoundElement); + +// print out all of an elements information +extern int HIDPrintElement(const pRecElement pElement); + +// return true if this is a valid device pointer +extern Boolean HIDIsValidDevice(const pRecDevice pSearchDevice); + +// return true if this is a valid element pointer for this device +extern Boolean HIDIsValidElement(const pRecDevice pSearchDevice, const pRecElement pSearchElement); + +// ================================== +// Element Event Queue and Value Interfaces + +enum +{ + kDefaultUserMin = 0, // default user min and max used for scaling + kDefaultUserMax = 255 +}; + +enum +{ + kDeviceQueueSize = 50 // this is wired kernel memory so should be set to as small as possible + // but should account for the maximum possible events in the queue + // USB updates will likely occur at 100 Hz so one must account for this rate of + // if states change quickly (updates are only posted on state changes) +}; + +// ================================== +// queues specific element, performing any device queue set up required +extern unsigned long HIDQueueElement (pRecDevice pDevice, pRecElement pElement); + +// adds all elements to queue, performing any device queue set up required +extern unsigned long HIDQueueDevice (pRecDevice pDevice); + +// removes element for queue, if last element in queue will release queue and device +extern unsigned long HIDDequeueElement (pRecDevice pDevice, pRecElement pElement); + +// completely removes all elements from queue and releases queue and device +extern unsigned long HIDDequeueDevice (pRecDevice pDevice); + +// releases all device queues for quit or rebuild (must be called) +extern unsigned long HIDReleaseAllDeviceQueues (void); + +// releases interface to device, should be done prior to exiting application (called from HIDReleaseDeviceList) +extern unsigned long HIDCloseReleaseInterface (pRecDevice pDevice); + +// returns true if an event is avialable for the element and fills out *pHIDEvent structure, returns false otherwise +// pHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required +extern unsigned char HIDGetEvent (pRecDevice pDevice, void * pHIDEvent); + +// returns current value for element, creating device interface as required, polling element +extern long HIDGetElementValue (pRecDevice pDevice, pRecElement pElement); + +// Set an elements value +// NOTE: This should only be used when a single element report needs to be sent. +// If multiple elements reports are to be send then transactions should be used. +// pIOHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required +extern long HIDSetElementValue (pRecDevice pDevice, pRecElement pElement,void* pIOHIDEvent); + +// Set a callback to be called when a queue goes from empty to non-empty +extern long HIDSetQueueCallback (pRecDevice pDevice, IOHIDCallbackFunction callback,void* callbackTarget, void* callbackRefcon); + +#if MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_2 +// Get a report from a device +extern long HIDGetReport (pRecDevice pDevice,const IOHIDReportType reportType, const unsigned long reportID, void* reportBuffer, unsigned long* reportBufferSize); + +// Send a report to a device +extern long HIDSetReport (pRecDevice pDevice,const IOHIDReportType reportType, const unsigned long reportID, void* reportBuffer, const unsigned long reportBufferSize); +#endif MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_2 + +// ================================== +// HUD utilities interfaces + +// returns calibrated value given raw value passed in +// calibrated value is equal to min and max values returned by HIDGetElementValue since device list built scaled to element reported min and max values +extern SInt32 HIDCalibrateValue (SInt32 value, pRecElement pElement); + +// returns scaled value given raw value passed in +// scaled value is equal to current value assumed to be in the range of element reported min and max values scaled to user min and max scaled values +extern SInt32 HIDScaleValue (SInt32 value, pRecElement pElement); + +// ================================== +// Conguration and Save Interfaces + +enum +{ + kPercentMove = 10 // precent of overall range a element must move to register +}; + +typedef struct recSaveHID +{ + long actionCookie; + // device + // need to add serial number when I have a test case + long vendorID; + long productID; + long locID; + long usage; + long usagePage; + // elements + long usagePageE; + long usageE; + void * cookie; +}recSaveHID,*pRecSaveHID; + +// polls all devices and elements for a change greater than kPercentMove. Times out after given time +// returns true and pointer to device and element if found +// returns false and NULL for both parameters if not found +extern unsigned char HIDConfigureAction (pRecDevice * ppDevice, pRecElement * ppElement, float timeout); + +// -- These are routines to use if the applcation wants HID Utilities to do the file handling -- +// Note: the FILE* is a MachO posix FILE and will not work with the MW MSL FILE* type. + +// take input records, save required info +// assume file is open and at correct position. +extern void HIDSaveElementConfig (FILE* fileRef, pRecDevice pDevice, pRecElement pElement, long actionCookie); + +// take file, read one record (assume file position is correct and file is open) +// search for matching device +// return pDevice, pElement and cookie for action +extern long HIDRestoreElementConfig (FILE* fileRef, pRecDevice * ppDevice, pRecElement * ppElement); + +// -- These routines use the CFPreferences API's. + +// Save the device & element values into the specified key in the specified applications preferences +extern Boolean HIDSaveElementPref (CFStringRef keyCFStringRef, CFStringRef appCFStringRef, pRecDevice pDevice, pRecElement pElement); + +// Find the specified preference in the specified application +// search for matching device and element +// return pDevice, pElement that matches + +extern Boolean HIDRestoreElementPref (CFStringRef keyCFStringRef, CFStringRef appCFStringRef, pRecDevice * ppDevice, pRecElement * ppElement); + +// -- These are routines to use if the client wants to use their own file handling -- + +// Set up a config record for saving +// takes an input records, returns record user can save as they want +// Note: the save rec must be pre-allocated by the calling app and will be filled out +extern void HIDSetElementConfig (pRecSaveHID pConfigRec, pRecDevice pDevice, pRecElement pElement, long actionCookie); + +// Get matching element from config record +// takes a pre-allocated and filled out config record +// search for matching device +// return pDevice, pElement and cookie for action +extern long HIDGetElementConfig (pRecSaveHID pConfigRec, pRecDevice * ppDevice, pRecElement * ppElement); + +// ================================== +// Output Transaction interface + +// Create and open an transaction interface to device, required prior to extracting values or building Transactions +extern unsigned long HIDTransactionAddElement(pRecDevice pDevice, pRecElement pElement); + +// removes an element from a Transaction +extern unsigned long HIDTransactionRemoveElement(pRecDevice pDevice, pRecElement pElement); + +// return true if this transaction contains this element +extern Boolean HIDTransactionHasElement(pRecDevice pDevice, pRecElement pElement); + +/* This changes the default value of an element, when the values of the */ +/* elements are cleared, on clear or commit, they are reset to the */ +/* default value */ +/* This call can be made on elements that are not in the transaction, but */ +/* has undefined behavior if made on elements not in the transaction */ +/* which are later added to the transaction. */ +/* In other words, an element should be added before its default is */ +/* set, for well defined behavior. */ +// pHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required +extern unsigned long HIDTransactionSetElementDefault(pRecDevice pDevice, pRecElement pElement,IOHIDEventStruct* pValueEvent); + +/* Get the current setting of an element's default value */ +// pHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required +extern unsigned long HIDTransactionGetElementDefault(pRecDevice pDevice, pRecElement pElement,IOHIDEventStruct* pValueEvent); + +/* Add a change to the transaction, by setting an element value */ +/* The change is not actually made until it is commited */ +/* The element must be part of the transaction or this call will fail */ +// pHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required +extern unsigned long HIDTransactionSetElementValue(pRecDevice pDevice, pRecElement pElement,IOHIDEventStruct* pValueEvent); + +/* Get the current setting of an element value */ +// pHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required +extern unsigned long HIDTransactionGetElementValue(pRecDevice pDevice, pRecElement pElement,IOHIDEventStruct* pValueEvent); + +/* Commit the transaction, or clear all the changes and start over */ +/* timoutMS is the timeout in milliseconds, a zero timeout will cause */ +/* this call to be non-blocking (returning queue empty) if there */ +/* is a NULL callback, and blocking forever until the queue is */ +/* non-empty if their is a valid callback */ +/* callback, if non-NULL is a callback to be called when data is */ +/* inserted to the queue */ +/* callbackTarget and callbackRefcon are passed to the callback */ +extern unsigned long HIDTransactionCommit(pRecDevice pDevice); + +/* Clear all the changes and start over */ +extern unsigned long HIDTransactionClear(pRecDevice pDevice); + +// ================================== +#pragma options align=reset + +#ifdef PRAGMA_IMPORT_OFF +#pragma import off +#elif PRAGMA_IMPORT +#pragma import reset +#endif + +#ifdef __cplusplus +} +#endif +// ================================== + +#endif // _HID_Utilities_External_h_ -- cgit v1.2.1