aboutsummaryrefslogtreecommitdiff
path: root/HID Utilities Source/HID Utilities Read Me.rtf
diff options
context:
space:
mode:
authorHans-Christoph Steiner <eighthave@users.sourceforge.net>2010-01-28 00:37:54 +0000
committerHans-Christoph Steiner <eighthave@users.sourceforge.net>2010-01-28 00:37:54 +0000
commit6b2aa4a4a7816d604ee63c974131c03fed9a4b7c (patch)
treef2e8041327aba32123e3c45acf746a523943d188 /HID Utilities Source/HID Utilities Read Me.rtf
parentd97ac3564e559040da3b87635352da0cea75ab5e (diff)
first working version of hidio+HIDUtilities build on Mac OS X using autotools, still needs work
svn path=/trunk/externals/io/hidio/; revision=13107
Diffstat (limited to 'HID Utilities Source/HID Utilities Read Me.rtf')
-rwxr-xr-xHID Utilities Source/HID Utilities Read Me.rtf331
1 files changed, 0 insertions, 331 deletions
diff --git a/HID Utilities Source/HID Utilities Read Me.rtf b/HID Utilities Source/HID Utilities Read Me.rtf
deleted file mode 100755
index 022748c..0000000
--- a/HID Utilities Source/HID Utilities Read Me.rtf
+++ /dev/null
@@ -1,331 +0,0 @@
-{\rtf1\mac\ansicpg10000\cocoartf102
-{\fonttbl\f0\fswiss\fcharset77 Helvetica;}
-{\colortbl;\red255\green255\blue255;}
-\vieww17000\viewh11120\viewkind0
-\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
-
-\f0\fs22 \cf0 HID Utilities Source\
-Human Interface Device Manager Utility Functions\
-\
-Version 3.7 28 Oct 2K2\
- General cleanup for web posting.\
-\
-Version 3.6 23 Oct 2K2\
- Added new API's: HIDSetElementValue, HIDSetQueueCallback, HIDGetReport, HIDSetReport & HIDPrintElement,\
- Note: <IOHIDPowerUsage.h> & <PID.h> have been incorporated into <IOKit/hid/IOHIDUsageTables.h>.\
-\
-Version 3.5 10 Aug 2K2\
- HIDConfigureAction now only checks kHIDElementTypeInput elements.\
- Changed some "for (x=0;x<n;x++) i[x] = 0;" code to use bzero instead.\
- Moved device & element finding code into its own routines: HIDFindActionDeviceAndElement & HIDFindSubElement.\
- The original HID utilities depended on the BSD FILE* implementation for HID[Save/Restore]ElementConfig and didn't work in CFM applications.\
- So two new routine (HIDSaveElementPref & HIDRestoreElementPref) were added that use the CFPreferences API's instead. \
-\
-Version 3.4 Added code to support hot plugging & un-plugging devices. Note to developers: It's very important to use the HIDIsValidDevice\
- and HIDIsValidElement API's to verify that cached device or element pointers are still valid before de-referencing them.\
- This validation code has been added to all HID Utilities AIP's that take a device or element pointer as a parameter.\
- Note also that this required that queueRunLoopSource and notification port fields be added to the device record. (see <HID_Utilities.h>)\
-\
-Version 3.3 Added output transaction support for UPS & FFB devices (see <HID_Transaction_Utilities.c> & <HID_Transaction_Utilities.h>).\
-\
-Version 3.2 Since 10.2 changed the cookie numbers (by adding a usage == -1element for arrays) a cookie agnostic method of getting\
- device and element names was needed. Plus the nested (device & element) switch statements hardcoding the strings.\
- So all the device, element & cookie strings have been moved out of the source file(s) and put into XML data files instead.\
- NOTE: all local (static) routines now begin with "hid_" instead of "HID".\
- All references to "Kernel/IOKit/hidsystem/" now (correctly) point to "IOKit/hid/" instead.\
-\
-Version 3.1: Added the basics of a element naming scheme. Right now it just supports one device (macally iShock) but as I get more \
- device info I can add other devices (feel free to add to the name lookup file and send me the results). Added bad device \
- and element chencking in config/save. Fixed one case of swapped usage page and usage variables. Fixed a few leaks \
- noted by a developer. Add a NULL check to top level element handler to prevent NULL deference also noted by developer. \
- Checked build with gcc3. Rebuilt bundle and static lib.\
-\
-Version 3.0: Major Change: Added CFM support.\
- Project now can be built in three different ways with the interface being straight C with Mac OS X type reliance, thus completely\
- suitable for CFM or MachO binary formats and Carbon, Cocoa, or command line interfaces.\
-\
- - Static Library: For use with Mac OS X MachO projects. The build product (in the build directory) can be static linked\
- into any exisiting Mac OS X MachO project. The project should include HID_Utilities_External.h only for declarations.\
-\
- - Source: This is just including the HID Utilities source files in the target project. Works as previous, but now all the \
- declarations needed are in the HID_Utilities_External.h header file.\
-\
- - Dynamic Library: Should only be used by CFM applications. There are some notes which MUST be followed. See the HID Explorer\
- or the HID Config Save samples for CW7 projects which show the actual use of the library. The dylib is housed in a bundle\
- which the CFM app finds at runtime and calls into. This bundle is included and the dylib project will automatically place\
- the actual dylib in the bundle (contents/MacOS/). NOTE: The path to this is an absolute path for the build product of the \
- project, you MUST modify this if you rebuild the dylib (which never be required). To do this select the prject name in the\
- Files tab and Get Info. Point the build product to the HID.bundle/contents/MacOS/ directory in the HID Utilities directory.\
- Then point the intermediates to the intermediates directory already in the build directory. This is required since the build\
- product path is absolute and can't be project relative (yes, a bug has been filed). Again, this is only if you wnat to rebuild\
- the dylib used for CFM applications. Also note, you must copy the HID.bundle into your application directory (if you are using\
- the method in the sample to find the bundle) for your CFM application to use it.\
- \
- Other Notes:\
- The interface is now completely Mac OS X type free. This means minor mods to your projects. See the element and device structures\
- for guidence on the types. For example cookies now should be void *'s. Fixed a couple bugs in allocating queues. CLean up error\
- checking to only dump DebugStrs if the source is used (vice the static or dynamic libraries).\
-\
-Version 2.0: Update. Fixed some 10.1 issues, notably spelling errors in constants and include differences. Fixed 10.0.x errors, notably \
- type errors in retrieving element info, negative value handling (see GetElementValue), queuing error, and other minor changes.\
- Major change in element list handling... Elements are now stored in a binary tree to mimic the tree sturcture of the \
- device. This allows hierarchial diplay and parsing (See HID Explorer sample). Additionally, some of the routine declarations \
- have chnaged to work with this tree structure, one can still get same list functionality by using GetNextDeviceElement routine \
- with kHIDElementTypeIO constant. Collections are now stored in tree, so users of these functions must understand if they are \
- looking at a valid IO element or a collection. Lastly, new parsing strings and two new headers are included to aid in decoding \
- PID and power device elements.\
-\
-Version 1.0: Initial release featuring functions to get HID device list, get devices and elements, poll for values, setup queues and get events, \
- handle configuration set up and saving/restoring of configurations.\
-\
-----\
-\
-This group of utilities is stand alone code to help developers work more easily with the HID Manager for Mac OS X with both MachO and CFM support. \
-It provides a high level abstract of the current HID interface that sacrifices slight flexibility in favor single function set up, device and element \
-retrieval, current value and event query, and configuration. This sample is the source code for the Utilities and does not provide a sample of the \
-utilization. There are other samples which provide complete working examples of a HID device explorer and a simple game implementation. More samples \
-will be forth coming shortly.\
-\
-This set of utilities is constantly evolving to both address any bugs and provide better support for developer requested features.\
-Any suggestions and/or bugs can be directed to the Apple bug reporter at:\
-<http://developer.apple.com/bugreporter/index.html>\
-\
-// ==================================\
-\
-// Device and Element Interfaces\
-\
-enum HIDElementTypeMask\
-\{\
- kHIDElementTypeInput = 1 << 1,\
- kHIDElementTypeOutput = 1 << 2,\
- kHIDElementTypeFeature = 1 << 3,\
- kHIDElementTypeCollection = 1 << 4,\
- kHIDElementTypeIO = kHIDElementTypeInput | kHIDElementTypeOutput | kHIDElementTypeFeature,\
- kHIDElementTypeAll = kHIDElementTypeIO | kHIDElementTypeCollection\
-\};\
-typedef enum HIDElementTypeMask 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 (not used often)\
-\
-// runtime variables\
- 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)\
- \
-\};\
-typedef struct recElement recElement;\
-typedef recElement* pRecElement;\
-\
-struct recDevice\
-\{\
- void * interface; // interface to device, NULL = no interface\
- void * queue; // device queue, NULL = no queue\
- char transport[256]; // device transport\
- 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;\
-\
-// ==================================\
-\
-// 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)\
-unsigned char HIDBuildDeviceList (unsigned long usagePage, unsigned long usage);\
-\
-// 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\
-void HIDReleaseDeviceList (void);\
-\
-// does a device list exist\
-unsigned char HIDHaveDeviceList (void);\
-\
-// how many HID devices have been found\
-// returns 0 if no device list exist\
-unsigned long 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\
-unsigned long HIDCountDeviceElements (pRecDevice pDevice, HIDElementTypeMask typeMask);\
-\
-// get the first device in the device list\
-// returns NULL if no list exists\
-pRecDevice HIDGetFirstDevice (void);\
-\
-// get next device in list given current device as parameter\
-// returns NULL if end of list\
-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\
-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\
-pRecElement HIDGetNextDeviceElement (pRecElement pElement, HIDElementTypeMask typeMask);\
-\
-// get previous element of given device in list given current element as parameter\
-// this wlaks 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\
-pRecElement HIDGetPreviousDeviceElement (pRecElement pElement, HIDElementTypeMask typeMask);\
-\
-// returns C string type name given a type enumeration passed in as parameter (see IOHIDKeys.h)\
-// returns empty string for invlid types\
-void HIDGetTypeName (unsigned long type, char * cstrName);\
-\
-// 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\
-void HIDGetUsageName (long valueUsagePage, long valueUsage, char * cstrName);\
-\
-// ==================================\
-\
-// 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\
-unsigned long HIDQueueElement (pRecDevice pDevice, pRecElement pElement);\
-\
-// adds all elements to queue, performing any device queue set up required\
-unsigned long HIDQueueDevice (pRecDevice pDevice);\
-\
-// removes element for queue, if last element in queue will release queue and device\
-unsigned long HIDDequeueElement (pRecDevice pDevice, pRecElement pElement);\
-\
-// completely removes all elements from queue and releases queue and device\
-unsigned long HIDDequeueDevice (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\
-unsigned char HIDGetEvent (pRecDevice pDevice, void * pHIDEvent);\
-\
-// returns current value for element, creating device interface as required, polling element\
-// Note: this DOES NOT release the inteface so applications must properly release devices via ReleaseHIDDeviceList\
-long HIDGetElementValue (pRecDevice pDevice, pRecElement pElement);\
-\
-// 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\
-long HIDCalibrateValue (long 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\
-long HIDScaleValue (long value, pRecElement pElement);\
-\
-// ==================================\
-\
-// Conguration and Save Interfaces\
-\
-enum\
-\{\
- kPercentMove = 10 // precent of overall range a element must move to register\
-\};\
-\
-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;\
-\};\
-typedef struct recSaveHID recSaveHID;\
-typedef 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\
-unsigned char HIDConfigureAction (pRecDevice * ppDevice, pRecElement * ppElement, float timeout);\
-\
-// take input records, save required info\
-// assume file is open and at correct position.\
-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\
-long HIDRestoreElementConfig (FILE * fileRef, pRecDevice * ppDevice, pRecElement * ppElement);\
-\
-----\
-\
-Requirements: Mac OS X, Project Builder (CodeWarrior 7 for sample CFM projects)\
-\
-We hope this helps people get up and running with HID Manager in a quick and painless manner.\
-\
-ggs} \ No newline at end of file