first working version of hidio+HIDUtilities build on Mac OS X using autotools, still needs work

svn path=/trunk/externals/io/hidio/; revision=13107

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