lang/LangPrimSource/HID_Utilities_10_4/HID_Utilities.h

   1 /*
   2         File:           HID_Utilities.h
   3
   4         Contains:       External interface for HID Utilities
   5
   6         DRI: George Warner
   7
   8         Copyright:      Copyright © 2002 Apple Computer, Inc., All Rights Reserved
   9
  10         Disclaimer:     IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
  11                                 ("Apple") in consideration of your agreement to the following terms, and your
  12                                 use, installation, modification or redistribution of this Apple software
  13                                 constitutes acceptance of these terms.  If you do not agree with these terms,
  14                                 please do not use, install, modify or redistribute this Apple software.
  15
  16                                 In consideration of your agreement to abide by the following terms, and subject
  17                                 to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs
  18                                 copyrights in this original Apple software (the "Apple Software"), to use,
  19                                 reproduce, modify and redistribute the Apple Software, with or without
  20                                 modifications, in source and/or binary forms; provided that if you redistribute
  21                                 the Apple Software in its entirety and without modifications, you must retain
  22                                 this notice and the following text and disclaimers in all such redistributions of
  23                                 the Apple Software.  Neither the name, trademarks, service marks or logos of
  24                                 Apple Computer, Inc. may be used to endorse or promote products derived from the
  25                                 Apple Software without specific prior written permission from Apple.  Except as
  26                                 expressly stated in this notice, no other rights or licenses, express or implied,
  27                                 are granted by Apple herein, including but not limited to any patent rights that
  28                                 may be infringed by your derivative works or by other works in which the Apple
  29                                 Software may be incorporated.
  30
  31                                 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  32                                 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  33                                 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  34                                 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  35                                 COMBINATION WITH YOUR PRODUCTS.
  36
  37                                 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  38                                 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  39                                 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  40                                 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  41                                 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  42                                 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  43                                 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  44 */
  45 #ifdef SC_DARWIN
  46 #ifndef _HID_Utilities_h_
  47 #define _HID_Utilities_h_
  48
  49 #include <Carbon/Carbon.h>
  50
  51 #include <IOKit/IOTypes.h>
  52 // 10.0.x
  53 //#include <IOKit/IOUSBHIDParser.h>
  54 // 10.1.x
  55 #include <IOKit/hid/IOHIDUsageTables.h>
  56
  57 #include <IOKit/hid/IOHIDLib.h>
  58
  59 // ==================================
  60
  61 #ifdef __cplusplus
  62 extern "C" {
  63 #endif
  64
  65 // ==================================
  66
  67 enum
  68 {
  69     kDefaultUserMin = 0,                                        // default user min and max used for scaling
  70     kDefaultUserMax = 255,
  71 };
  72
  73 typedef enum HIDElementTypeMask
  74 {
  75         kHIDElementTypeInput                            = 1 << 1,
  76         kHIDElementTypeOutput                   = 1 << 2,
  77         kHIDElementTypeFeature                  = 1 << 3,
  78         kHIDElementTypeCollection               = 1 << 4,
  79         kHIDElementTypeIO                                       = kHIDElementTypeInput | kHIDElementTypeOutput | kHIDElementTypeFeature,
  80         kHIDElementTypeAll                                      = kHIDElementTypeIO | kHIDElementTypeCollection
  81 }HIDElementTypeMask;
  82
  83 struct recElement
  84 {
  85     IOHIDElementType type;                                      // the type defined by IOHIDElementType in IOHIDKeys.h
  86     long usagePage;                                                     // usage page from IOUSBHIDParser.h which defines general usage
  87     long usage;                                                         // usage within above page from IOUSBHIDParser.h which defines specific usage
  88     IOHIDElementCookie cookie;                          // unique value (within device of specific vendorID and productID) which identifies element, will NOT change
  89     long min;                                                           // reported min value possible
  90     long max;                                                           // reported max value possible
  91     long scaledMin;                                                     // reported scaled min value possible
  92     long scaledMax;                                                     // reported scaled max value possible
  93     long size;                                                          // size in bits of data return from element
  94     Boolean relative;                                           // are reports relative to last report (deltas)
  95     Boolean wrapping;                                           // does element wrap around (one value higher than max is min)
  96     Boolean nonLinear;                                          // are the values reported non-linear relative to element movement
  97     Boolean preferredState;                                     // does element have a preferred state (such as a button)
  98     Boolean nullState;                                          // does element have null state
  99     long units;                                                         // units value is reported in (not used very often)
 100     long unitExp;                                                       // exponent for units (also not used very often)
 101     Str255 name;                                                        // name of element (not used often)
 102
 103 // runtime variables
 104     long minReport;                                             // min returned value
 105     long maxReport;                                             // max returned value (calibrate call)
 106     long userMin;                                                       // user set value to scale to (scale call)
 107     long userMax;
 108
 109         struct recElement * pPrevious;                  // previous element (NULL at list head)
 110     struct recElement * pChild;                         // next child (only of collections)
 111     struct recElement * pSibling;                       // next sibling (for elements and collections)
 112
 113 };
 114 typedef struct recElement recElement;
 115 typedef recElement* pRecElement;
 116
 117 struct recDevice
 118 {
 119     IOHIDDeviceInterface ** interface;          // interface to device, NULL = no interface
 120     IOHIDQueueInterface ** queue;                       // device queue, NULL = no queue
 121         CFRunLoopSourceRef      queueRunLoopSource;             // device queue run loop source, NULL == no source
 122         IOHIDOutputTransactionInterface ** transaction;         // output transaction interface, NULL == no transaction
 123         io_object_t notification;                               // notifications
 124         Str255 transport;                                               // device transport
 125     long vendorID;                                                      // id for device vendor, unique across all devices
 126     long productID;                                                     // id for particular product, unique across all of a vendors devices
 127     long version;                                                       // version of product
 128     Str255 manufacturer;                                        // name of manufacturer
 129     Str255 product;                                                     // name of product
 130     Str255 serial;                                                      // serial number of specific product, can be assumed unique across specific product or specific vendor (not used often)
 131     long locID;                                                         // long representing location in USB (or other I/O) chain which device is pluged into, can identify specific device on machine
 132     long usage;                                                         // usage page from IOUSBHID Parser.h which defines general usage
 133     long usagePage;                                                     // usage within above page from IOUSBHID Parser.h which defines specific usage
 134     long totalElements;                                         // number of total elements (should be total of all elements on device including collections) (calculated, not reported by device)
 135         long features;                                                  // number of elements of type kIOHIDElementTypeFeature
 136         long inputs;                                                    // number of elements of type kIOHIDElementTypeInput_Misc or kIOHIDElementTypeInput_Button or kIOHIDElementTypeInput_Axis or kIOHIDElementTypeInput_ScanCodes
 137         long outputs;                                                   // number of elements of type kIOHIDElementTypeOutput
 138         long collections;                                               // number of elements of type kIOHIDElementTypeCollection
 139     long axis;                                                          // number of axis (calculated, not reported by device)
 140     long buttons;                                                       // number of buttons (calculated, not reported by device)
 141     long hats;                                                          // number of hat switches (calculated, not reported by device)
 142     long sliders;                                                       // number of sliders (calculated, not reported by device)
 143     long dials;                                                         // number of dials (calculated, not reported by device)
 144     long wheels;                                                        // number of wheels (calculated, not reported by device)
 145     recElement* pListElements;                          // head of linked list of elements
 146     struct recDevice* pNext;                            // next device
 147 };
 148 typedef struct recDevice recDevice;
 149 typedef recDevice* pRecDevice;
 150
 151 // ==================================
 152 // Create and open an interface to device, required prior to extracting values or building queues
 153 // Note: appliction now owns the device and must close and release it prior to exiting
 154 extern IOReturn HIDCreateOpenDeviceInterface (io_object_t hidDevice, pRecDevice pDevice);
 155
 156 // builds list of device with elements (allocates memory and captures devices)
 157 // list is allcoated internally within HID Utilites and can be accessed via accessor functions
 158 // structures within list are considered flat and user accessable, butnot user modifiable
 159 // can be called again to rebuild list to account for new devices (will do the right thing in case of disposing existing list)
 160 extern Boolean HIDBuildDeviceList (UInt32 usagePage, UInt32 usage);
 161
 162 // release list built by above function
 163 // MUST be called prior to application exit to properly release devices
 164 // if not called (or app crashes) devices can be recovered by pluging into different location in USB chain
 165 extern void HIDReleaseDeviceList (void);
 166
 167 // does a device list exist
 168 extern Boolean HIDHaveDeviceList (void);
 169
 170 // how many HID devices have been found
 171 // returns 0 if no device list exist
 172 extern UInt32 HIDCountDevices (void);
 173
 174 // how many elements does a specific device have
 175 // returns 0 if device is invalid or NULL
 176 // uses mask of HIDElementTypeMask to restrict element found
 177 // use kHIDElementTypeIO to get non-collection elements
 178 extern UInt32 HIDCountDeviceElements (pRecDevice pDevice, HIDElementTypeMask typeMask);
 179
 180 // get the first device in the device list
 181 // returns NULL if no list exists
 182 extern pRecDevice HIDGetFirstDevice (void);
 183
 184 // get next device in list given current device as parameter
 185 // returns NULL if end of list
 186 extern pRecDevice HIDGetNextDevice (pRecDevice pDevice);
 187
 188 // get the first element of device passed in as parameter
 189 // returns NULL if no list exists or device does not exists or is NULL
 190 // uses mask of HIDElementTypeMask to restrict element found
 191 // use kHIDElementTypeIO to get previous HIDGetFirstDeviceElement functionality
 192 extern pRecElement HIDGetFirstDeviceElement (pRecDevice pDevice, HIDElementTypeMask typeMask);
 193
 194 // get next element of given device in list given current element as parameter
 195 // will walk down each collection then to next element or collection (depthwise traverse)
 196 // returns NULL if end of list
 197 // uses mask of HIDElementTypeMask to restrict element found
 198 // use kHIDElementTypeIO to get previous HIDGetNextDeviceElement functionality
 199 extern pRecElement HIDGetNextDeviceElement (pRecElement pElement, HIDElementTypeMask typeMask);
 200
 201 // get previous element of given device in list given current element as parameter
 202 // this wlaks directly up the tree to the top element and does not search at each level
 203 // returns NULL if beginning of list
 204 // uses mask of HIDElementTypeMask to restrict element found
 205 // use kHIDElementTypeIO to get non-collection elements
 206 extern pRecElement HIDGetPreviousDeviceElement (pRecElement pElement, HIDElementTypeMask typeMask);
 207
 208 // returns C string type name given a type enumeration passed in as parameter (see IOHIDKeys.h)
 209 // returns empty string for invlid types
 210 extern void HIDGetTypeName (IOHIDElementType type, char * cstrName);
 211
 212 // returns C string usage given usage page and usage passed in as parameters (see IOUSBHIDParser.h)
 213 // returns usage page and usage values in string form for unknown values
 214 extern void HIDGetUsageName (long valueUsagePage, long valueUsage, char * cstrName);
 215
 216 // returns calibrated value given raw value passed in
 217 // calibrated value is equal to min and max values returned by HIDGetElementValue since device list built scaled to element reported min and max values
 218 extern SInt32 HIDCalibrateValue (SInt32 value, pRecElement pElement);
 219
 220 // returns scaled value given raw value passed in
 221 // 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
 222 extern SInt32 HIDScaleValue (SInt32 value, pRecElement pElement);
 223
 224 // ---------------------------------
 225 // convert an element type to a mask
 226 extern HIDElementTypeMask HIDConvertElementTypeToMask (const long type);
 227
 228 // find this device
 229 extern Boolean HIDFindDevice(const pRecDevice pSearchDevice, pRecDevice *ppFoundDevice);
 230
 231 // find the device and element for this action
 232 // Device: serial, vendorID, productID, location, usagePage, usage
 233 // Element: cookie, usagePage, usage,
 234 extern Boolean HIDFindActionDeviceAndElement(const pRecDevice pSearchDevice, const pRecElement pSearchElement,
 235                                                                                   pRecDevice *ppFoundDevice, pRecElement *ppFoundElement);
 236
 237 // find the device and element for this action
 238 // Device: serial, vendorID, productID, location, usagePage, usage
 239 // Element: cookie, usagePage, usage,
 240
 241 extern Boolean HIDFindSubElement(const pRecElement pStartElement, const pRecElement pSearchElement, pRecElement *ppFoundElement);
 242
 243 // print out all of an elements information
 244 extern int HIDPrintElement(const pRecElement pElement);
 245
 246 // return true if this is a valid device pointer
 247 extern Boolean HIDIsValidDevice(const pRecDevice pSearchDevice);
 248
 249 // return true if this is a valid element pointer for this device
 250 extern Boolean HIDIsValidElement(const pRecDevice pSearchDevice, const pRecElement pSearchElement);
 251
 252 #ifdef __cplusplus
 253 }
 254 #endif
 255
 256 #endif // _HID_Utilities_h_
 257 #endif //SC_DARWIN