1 /* 2 * File: HID_Utilities_External.h 3 * 4 * Contains: Definition of the HID Utilities exported functions 5 * External interface for HID Utilities, can be used with either library or source 6 * Check notes below for usage. Some type casting is required so library is framework and carbon free 7 * 8 * Copyright: Copyright � 2005 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 46 #ifndef _HID_Utilities_External_h_ 47 #define _HID_Utilities_External_h_ 48 49 /*****************************************************/ 50 #pragma mark - includes & imports 51 /*****************************************************/ 52 #if !TARGET_RT_MAC_CFM 53 #include <IOKit/hid/IOHIDLib.h> 54 #endif TARGET_RT_MAC_CFM 55 56 //#include <IOKit/hid/IOHIDUsageTables.h> 57 #if 0 // NOTE: These are now in <IOKit/hid/IOHIDUsageTables.h> 58 #include "PID.h" 59 #include "IOHIDPowerUsage.h" 60 #endif 61 62 #include <stdio.h> 63 64 /*****************************************************/ 65 #if PRAGMA_ONCE 66 #pragma once 67 #endif 68 69 #ifdef __cplusplus 70 extern "C" { 71 #endif 72 73 #if PRAGMA_IMPORT 74 #pragma import on 75 #endif 76 77 #if PRAGMA_STRUCT_ALIGN 78 #pragma options align=mac68k 79 #elif PRAGMA_STRUCT_PACKPUSH 80 #pragma pack( push, 2 ) 81 #elif PRAGMA_STRUCT_PACK 82 #pragma pack( 2 ) 83 #endif 84 85 /*****************************************************/ 86 #pragma mark - typedef's, struct's, enums, defines, etc. 87 /*****************************************************/ 88 #if TARGET_RT_MAC_CFM 89 // from IOHIDKeys.h( IOKit ) 90 // this can't be included since the original file has framework includes 91 // developers may need to add definitions here 92 typedef enum IOHIDElementType { 93 kIOHIDElementTypeInput_Misc = 1, 94 kIOHIDElementTypeInput_Button = 2, 95 kIOHIDElementTypeInput_Axis = 3, 96 kIOHIDElementTypeInput_ScanCodes = 4, 97 kIOHIDElementTypeOutput = 129, 98 kIOHIDElementTypeFeature = 257, 99 kIOHIDElementTypeCollection = 513 100 }IOHIDElementType; 101 102 typedef enum IOHIDReportType { 103 kIOHIDReportTypeInput = 0, 104 kIOHIDReportTypeOutput, 105 kIOHIDReportTypeFeature, 106 kIOHIDReportTypeCount 107 }IOHIDReportType; 108 109 // Notes: This is a MachO function pointer. If you're using CFM you have to call MachOFunctionPointerForCFMFunctionPointer. 110 typedef void( *IOHIDCallbackFunction ) ( void* target, unsigned long result, void* refcon, void* sender ); 111 typedef void* IOHIDEventStruct; 112 #endif TARGET_RT_MAC_CFM 113 114 // Device and Element Interfaces 115 116 typedef enum HIDElementTypeMask 117 { 118 kHIDElementTypeInput = 1 << 1, 119 kHIDElementTypeOutput = 1 << 2, 120 kHIDElementTypeFeature = 1 << 3, 121 kHIDElementTypeCollection = 1 << 4, 122 kHIDElementTypeIO = kHIDElementTypeInput | kHIDElementTypeOutput | kHIDElementTypeFeature, 123 kHIDElementTypeAll = kHIDElementTypeIO | kHIDElementTypeCollection 124 }HIDElementTypeMask; 125 126 struct hu_element_t 127 { 128 unsigned long type; // the type defined by IOHIDElementType in IOHIDKeys.h 129 long usage; // usage within above page from IOUSBHIDParser.h which defines specific usage 130 long usagePage; // usage page from IOUSBHIDParser.h which defines general usage 131 void* cookie; // unique value( within device of specific vendorID and productID ) which identifies element, will NOT change 132 long min; // reported min value possible 133 long max; // reported max value possible 134 long scaledMin; // reported scaled min value possible 135 long scaledMax; // reported scaled max value possible 136 long size; // size in bits of data return from element 137 unsigned char relative; // are reports relative to last report( deltas ) 138 unsigned char wrapping; // does element wrap around( one value higher than max is min ) 139 unsigned char nonLinear; // are the values reported non-linear relative to element movement 140 unsigned char preferredState; // does element have a preferred state( such as a button ) 141 unsigned char nullState; // does element have null state 142 long units; // units value is reported in( not used very often ) 143 long unitExp; // exponent for units( also not used very often ) 144 char name[256]; // name of element( c string ) 145 146 // runtime variables 147 long initialCenter; // center value at start up 148 unsigned char hasCenter; // whether or not to use center for calibration 149 long minReport; // min returned value 150 long maxReport; // max returned value( calibrate call ) 151 long userMin; // user set value to scale to( scale call ) 152 long userMax; 153 154 struct hu_element_t* pPrevious; // previous element( NULL at list head ) 155 struct hu_element_t* pChild; // next child( only of collections ) 156 struct hu_element_t* pSibling; // next sibling( for elements and collections ) 157 158 long depth; 159 }; 160 typedef struct hu_element_t hu_element_t; 161 162 struct hu_device_t 163 { 164 void* interface; // interface to device, NULL = no interface 165 void* queue; // device queue, NULL = no queue 166 void* runLoopSource; // device run loop source, NULL == no source 167 void* queueRunLoopSource; // device queue run loop source, NULL == no source 168 void* transaction; // output transaction interface, NULL == no interface 169 void* notification; // notifications 170 char transport[256]; // device transport( c string ) 171 long vendorID; // id for device vendor, unique across all devices 172 long productID; // id for particular product, unique across all of a vendors devices 173 long version; // version of product 174 char manufacturer[256]; // name of manufacturer 175 char product[256]; // name of product 176 char serial[256]; // serial number of specific product, can be assumed unique across specific product or specific vendor( not used often ) 177 long locID; // long representing location in USB( or other I/O ) chain which device is pluged into, can identify specific device on machine 178 long usage; // usage page from IOUSBHID Parser.h which defines general usage 179 long usagePage; // usage within above page from IOUSBHID Parser.h which defines specific usage 180 long totalElements; // number of total elements( should be total of all elements on device including collections ) ( calculated, not reported by device ) 181 long features; // number of elements of type kIOHIDElementTypeFeature 182 long inputs; // number of elements of type kIOHIDElementTypeInput_Misc or kIOHIDElementTypeInput_Button or kIOHIDElementTypeInput_Axis or kIOHIDElementTypeInput_ScanCodes 183 long outputs; // number of elements of type kIOHIDElementTypeOutput 184 long collections; // number of elements of type kIOHIDElementTypeCollection 185 long axis; // number of axis( calculated, not reported by device ) 186 long buttons; // number of buttons( calculated, not reported by device ) 187 long hats; // number of hat switches( calculated, not reported by device ) 188 long sliders; // number of sliders( calculated, not reported by device ) 189 long dials; // number of dials( calculated, not reported by device ) 190 long wheels; // number of wheels( calculated, not reported by device ) 191 hu_element_t* pListElements; // head of linked list of elements 192 struct hu_device_t* pNext; // next device 193 }; 194 typedef struct hu_device_t hu_device_t; 195 196 // this is the procedure type for a client hot plug callback 197 typedef OSStatus ( *HotPlugCallbackProcPtr )( io_iterator_t inIODeviceIterator ); 198 199 /*****************************************************/ 200 #pragma mark - exported globals 201 /*****************************************************/ 202 #pragma mark - exported function prototypes 203 /*****************************************************/ 204 #pragma mark HID Utilities interface 205 /*****************************************************/ 206 // Create and open an interface to device, required prior to extracting values or building queues 207 // Notes: appliction now owns the device and must close and release it prior to exiting 208 extern unsigned long HIDCreateOpenDeviceInterface( UInt32 inHIDDevice, hu_device_t* inDevice ); 209 210 // builds list of device with elements( allocates memory and captures devices ) 211 // list is allocated internally within HID Utilites and can be accessed via accessor functions 212 // structures within list are considered flat and user accessable, but not user modifiable 213 // can be called again to rebuild list to account for new devices( will do the right thing in case of disposing existing list ) 214 // inUsagePage, usage are each a inNumDeviceTypes sized array of matching usage and usage pages 215 // returns TRUE if successful 216 217 extern Boolean HIDBuildMultiDeviceList( UInt32 *inUsagePage, UInt32 *inUsage, UInt32 inNumDeviceTypes ); 218 219 // same as above but this uses a single inUsagePage and usage 220 221 extern Boolean HIDBuildDeviceList( UInt32 inUsagePage, UInt32 inUsage ); 222 223 // updates the current device list for any new/removed devices 224 // if this is called before HIDBuildDeviceList the it functions like HIDBuildMultiDeviceList 225 // inUsagePage, usage are each a inNumDeviceTypes sized array of matching usage and usage pages 226 // returns TRUE if successful which means if any device were added or removed( the device config changed ) 227 228 extern Boolean HIDUpdateDeviceList( UInt32 *inUsagePage, UInt32 *inUsage, UInt32 inNumDeviceTypes ); 229 230 // release list built by above function 231 // MUST be called prior to application exit to properly release devices 232 // if not called( or app crashes ) devices can be recovered by pluging into different location in USB chain 233 extern void HIDReleaseDeviceList( void ); 234 235 // does a device list exist 236 extern Boolean HIDHaveDeviceList( void ); 237 238 // how many HID devices have been found 239 // returns 0 if no device list exist 240 extern UInt32 HIDCountDevices( void ); 241 242 // how many elements does a specific device have 243 // returns 0 if device is invalid or NULL 244 // uses mask of HIDElementTypeMask to restrict element found 245 // use kHIDElementTypeIO to get non-collection elements 246 extern UInt32 HIDCountDeviceElements( const hu_device_t* inDevice, HIDElementTypeMask inTypeMask ); 247 248 // get the first device in the device list 249 // returns NULL if no list exists 250 extern hu_device_t* HIDGetFirstDevice( void ); 251 252 // get next device in list given current device as parameter 253 // returns NULL if end of list 254 extern hu_device_t* HIDGetNextDevice( const hu_device_t* inDevice ); 255 256 // get the first element of device passed in as parameter 257 // returns NULL if no list exists or device does not exists or is NULL 258 // uses mask of HIDElementTypeMask to restrict element found 259 // use kHIDElementTypeIO to get previous HIDGetFirstDeviceElement functionality 260 extern hu_element_t* HIDGetFirstDeviceElement( const hu_device_t* inDevice, HIDElementTypeMask inTypeMask ); 261 262 // get next element of given device in list given current element as parameter 263 // will walk down each collection then to next element or collection( depthwise traverse ) 264 // returns NULL if end of list 265 // uses mask of HIDElementTypeMask to restrict element found 266 // use kHIDElementTypeIO to get previous HIDGetNextDeviceElement functionality 267 extern hu_element_t* HIDGetNextDeviceElement( hu_element_t* inElement, HIDElementTypeMask inTypeMask ); 268 269 // get previous element of given device in list given current element as parameter 270 // this walks directly up the tree to the top element and does not search at each level 271 // returns NULL if beginning of list 272 // uses mask of HIDElementTypeMask to restrict element found 273 // use kHIDElementTypeIO to get non-collection elements 274 extern hu_element_t* HIDGetPreviousDeviceElement( const hu_element_t* inElement, HIDElementTypeMask inTypeMask ); 275 276 // Sets the client hot plug callback routine 277 extern OSStatus HIDSetHotPlugCallback( HotPlugCallbackProcPtr inHotPlugCallbackProcPtr ); 278 279 /*****************************************************/ 280 #pragma mark Name Lookup Interfaces 281 /*****************************************************/ 282 283 // get vendor name from vendor ID 284 extern Boolean HIDGetVendorNameFromVendorID( long inVendorID, char* outCStrName ); 285 286 // get product name from vendor/product ID 287 extern Boolean HIDGetProductNameFromVendorProductID( long inVendorID, long inProductID, char* outCStrName ); 288 289 // set name from vendor id/product id look up( using cookies ) 290 extern Boolean HIDGetElementNameFromVendorProductCookie( long inVendorID, long inProductID, long inCookie, char* inCStrName ); 291 292 // set name from vendor id/product id look up( using usage page & usage ) 293 extern Boolean HIDGetElementNameFromVendorProductUsage( long inVendorID, long inProductID, long inUsagePage, long inUsage, char* inCStrName ); 294 295 // Add device to usage & cookie db's 296 extern Boolean HIDAddDeviceToXML( const hu_device_t* inDevice ); 297 298 // Add element to usage & cookie db's 299 extern Boolean HIDAddDeviceElementToXML( const hu_device_t* inDevice, const hu_element_t* inElement ); 300 301 // returns C string type name given a type enumeration passed in as parameter( see IOHIDKeys.h ) 302 // returns empty string for invalid types 303 extern void HIDGetTypeName( IOHIDElementType inIOHIDElementType, char* inCStrName ); 304 305 // returns C string usage given usage page and usage passed in as parameters( see IOUSBHIDParser.h ) 306 // returns usage page and usage values in string form for unknown values 307 extern void HIDGetUsageName( long inUsagePage, long inUsage, char* inCStrName ); 308 309 /*****************************************************/ 310 // convert an element type to a mask 311 extern HIDElementTypeMask HIDConvertElementTypeToMask( IOHIDElementType inIOHIDElementType ); 312 313 // find this device 314 extern Boolean HIDFindDevice( const hu_device_t* inSearchDevice, hu_device_t **outFoundDevice ); 315 316 // find the device and element for this action 317 // Device: serial, vendorID, productID, location, inUsagePage, usage 318 // Element: cookie, inUsagePage, usage, 319 extern Boolean HIDFindActionDeviceAndElement( const hu_device_t* inSearchDevice, const hu_element_t* inSearchElement, hu_device_t **outFoundDevice, hu_element_t **outFoundElement ); 320 321 // find the device and element for this action 322 // Device: serial, vendorID, productID, location, inUsagePage, usage 323 // Element: cookie, inUsagePage, usage, 324 325 extern Boolean HIDFindSubElement( const hu_element_t* inStartElement, const hu_element_t* inSearchElement, hu_element_t **outFoundElement ); 326 327 // print out all of an elements information 328 extern int HIDPrintElement( const hu_element_t* inElement ); 329 330 // return TRUE if this is a valid device pointer 331 extern Boolean HIDIsValidDevice( const hu_device_t* inDevice ); 332 333 // return TRUE if this is a valid element pointer for this device 334 extern Boolean HIDIsValidElement( const hu_device_t* inDevice, const hu_element_t* inElement ); 335 336 /*****************************************************/ 337 #pragma mark Element Event Queue and Value Interfaces 338 /*****************************************************/ 339 enum 340 { 341 kDefaultUserMin = 0, // default user min and max used for scaling 342 kDefaultUserMax = 255 343 }; 344 345 enum 346 { 347 kDeviceQueueSize = 50 // this is wired kernel memory so should be set to as small as possible 348 // but should account for the maximum possible events in the queue 349 // USB updates will likely occur at 100 Hz so one must account for this rate of 350 // if states change quickly( updates are only posted on state changes ) 351 }; 352 353 /*****************************************************/ 354 // queues specific element, performing any device queue set up required 355 extern unsigned long HIDQueueElement( hu_device_t* inDevice, const hu_element_t* inElement ); 356 357 // adds all elements to queue, performing any device queue set up required 358 extern unsigned long HIDQueueDevice( hu_device_t* inDevice ); 359 360 // removes element for queue, if last element in queue will release queue and device 361 extern unsigned long HIDDequeueElement( hu_device_t* inDevice, const hu_element_t* inElement ); 362 363 // completely removes all elements from queue and releases queue and device 364 extern unsigned long HIDDequeueDevice( hu_device_t* inDevice ); 365 366 // releases all device queues for quit or rebuild( must be called ) 367 extern unsigned long HIDReleaseAllDeviceQueues( void ); 368 369 // releases interface to device, should be done prior to exiting application( called from HIDReleaseDeviceList ) 370 extern unsigned long HIDCloseReleaseInterface( hu_device_t* inDevice ); 371 372 // returns TRUE if an event is avialable for the element and fills out *outHIDEvent structure, returns FALSE otherwise 373 // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required 374 extern unsigned char HIDGetEvent( const hu_device_t* inDevice, void* outHIDEvent ); 375 376 // returns current value for element, creating device interface as required, polling element 377 extern long HIDGetElementEvent( const hu_device_t* inDevice, hu_element_t* inElement, IOHIDEventStruct* outIOHIDEvent ); 378 379 // returns current value for element, creating device interface as required, polling element 380 extern long HIDGetElementValue( const hu_device_t* inDevice, hu_element_t* inElement ); 381 382 // Set an elements value 383 // NOTE: This should only be used when a single element report needs to be sent. 384 // If multiple elements reports are to be send then transactions should be used. 385 // outIOHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required 386 extern long HIDSetElementValue( const hu_device_t* inDevice, const hu_element_t* inElement, void* outIOHIDEvent ); 387 388 // Set a callback to be called when a queue goes from empty to non-empty 389 // Notes: This is a MachO function pointer. If you're using CFM you have to call MachOFunctionPointerForCFMFunctionPointer. 390 extern long HIDSetQueueCallback( hu_device_t* inDevice, IOHIDCallbackFunction inIOHIDCallback, void* inCallbackTarget, void* inCallbackRefcon ); 391 392 #if defined( AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER ) 393 // Get a report from a device 394 extern long HIDGetReport( const hu_device_t* inDevice, IOHIDReportType inIOHIDReportType, unsigned long inReportID, void* inReportBuffer, unsigned long* inReportBufferSize ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; 395 396 // Send a report to a device 397 extern long HIDSetReport( const hu_device_t* inDevice, IOHIDReportType inIOHIDReportType, unsigned long inReportID, void* inReportBuffer, unsigned long inReportBufferSize ) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; 398 #endif // defined( AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER ) 399 400 #if defined( AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER ) 401 // copy matching elements 402 extern long HIDCopyMatchingElements( const hu_device_t* inDevice, CFDictionaryRef inMatchingDict, CFArrayRef* inElements ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; 403 // Set a callback to be called when a report comes in the interrupt pipe 404 // Notes: This is a MachO function pointer. If you're using CFM you have to call MachOFunctionPointerForCFMFunctionPointer. 405 extern long HIDSetInterruptReportHandlerCallback( const hu_device_t* inDevice, void* inReportBuffer, UInt32 inReportBufferSize, IOHIDReportCallbackFunction inIOHIDReportCallback, void* inCallbackTarget, void* inCallbackRefcon ) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; 406 #endif // defined( AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER ) 407 408 /*****************************************************/ 409 #pragma mark calibration & scale routines 410 /*****************************************************/ 411 // returns calibrated value given raw value passed in 412 // calibrated value is equal to min and max values returned by HIDGetElementValue since device list built scaled to element reported min and max values 413 extern SInt32 HIDCalibrateValue( SInt32 inValue, hu_element_t* inElement ); 414 415 // returns scaled value given raw value passed in 416 // 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 417 extern SInt32 HIDScaleValue( SInt32 inValue, const hu_element_t* inElement ); 418 419 /*****************************************************/ 420 #pragma mark Conguration and Save Interfaces 421 /*****************************************************/ 422 #define kPercentMove 10 // precent of overall range a element must move to register 423 424 typedef struct hu_SaveRec_t 425 { 426 long actionCookie; 427 // device( need to add serial number when I have a test case ) 428 long vendorID; 429 long productID; 430 long locID; 431 long usage; 432 long usagePage; 433 // elements 434 long usagePageE; 435 long usageE; 436 void* cookie; 437 }hu_SaveRec_t; 438 439 // polls all devices and elements for a change greater than kPercentMove. Times out after given time 440 // returns TRUE and pointer to device and element if found 441 // returns FALSE and NULL for both parameters if not found 442 extern Boolean HIDConfigureAction( hu_device_t **outDevice, hu_element_t **outElement, float inTimeout ); 443 444 // -- These are routines to use if the applcation wants HID Utilities to do the file handling -- 445 // Notes: the FILE* is a MachO posix FILE and will not work with the MWCW MSL FILE* type. 446 447 // take input records, save required info 448 // assume file is open and at correct position. 449 extern void HIDSaveElementConfig( FILE* inFILE, const hu_device_t* inDevice, const hu_element_t* inElement, long inActionCookie ); 450 451 // take file, read one record( assume file position is correct and file is open ) 452 // search for matching device 453 // return inDevice, inElement and cookie for action 454 extern long HIDRestoreElementConfig( FILE* inFILE, hu_device_t **outDevice, hu_element_t **outElement ); 455 456 // -- These routines use the CFPreferences API's. 457 458 // Save the device & element values into the specified key in the specified applications preferences 459 extern Boolean HIDSaveElementPref( CFStringRef inKeyCFStringRef, CFStringRef inAppCFStringRef, const hu_device_t* inDevice, const hu_element_t* inElement ); 460 461 // Find the specified preference in the specified application 462 // search for matching device and element 463 // return inDevice, inElement that matches 464 465 extern Boolean HIDRestoreElementPref( CFStringRef inKeyCFStringRef, CFStringRef inAppCFStringRef, hu_device_t **outDevice, hu_element_t **outElement ); 466 467 // -- These are routines to use if the client wants to use their own file handling -- 468 469 // Set up a config record for saving 470 // takes an input records, returns record user can save as they want 471 // Notes: the save rec must be pre-allocated by the calling app and will be filled out 472 extern void HIDSetElementConfig( hu_SaveRec_t* inConfigRec, const hu_device_t* inDevice, const hu_element_t* inElement, long inActionCookie ); 473 474 // Get matching element from config record 475 // takes a pre-allocated and filled out config record 476 // search for matching device 477 // return inDevice, inElement and cookie for action 478 extern long HIDGetElementConfig( hu_SaveRec_t* inConfigRec, hu_device_t **outDevice, hu_element_t **outElement ); 479 480 /*****************************************************/ 481 #pragma mark Output Transaction interface 482 /*****************************************************/ 483 // Create and open an transaction interface to device, required prior to extracting values or building Transactions 484 extern unsigned long HIDTransactionAddElement( hu_device_t* inDevice, const hu_element_t* inElement ); 485 486 // removes an element from a Transaction 487 extern unsigned long HIDTransactionRemoveElement( hu_device_t* inDevice, const hu_element_t* inElement ); 488 489 // return TRUE if this transaction contains this element 490 extern Boolean HIDTransactionHasElement( hu_device_t* inDevice, const hu_element_t* inElement ); 491 492 /* This changes the default value of an element, when the values of the */ 493 /* elements are cleared, on clear or commit, they are reset to the */ 494 /* default value */ 495 /* This call can be made on elements that are not in the transaction, but */ 496 /* has undefined behavior if made on elements not in the transaction */ 497 /* which are later added to the transaction. */ 498 /* In other words, an element should be added before its default is */ 499 /* set, for well defined behavior. */ 500 // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required 501 extern unsigned long HIDTransactionSetElementDefault( hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent ); 502 503 /* Get the current setting of an element's default value */ 504 // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required 505 extern unsigned long HIDTransactionGetElementDefault( hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent ); 506 507 /* Add a change to the transaction, by setting an element value */ 508 /* The change is not actually made until it is commited */ 509 /* The element must be part of the transaction or this call will fail */ 510 // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required 511 extern unsigned long HIDTransactionSetElementValue( hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent ); 512 513 /* Get the current setting of an element value */ 514 // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required 515 extern unsigned long HIDTransactionGetElementValue( hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent ); 516 517 /* Commit the transaction, or clear all the changes and start over */ 518 extern unsigned long HIDTransactionCommit( hu_device_t* inDevice ); 519 520 /* Clear all the changes and start over */ 521 extern unsigned long HIDTransactionClear( hu_device_t* inDevice ); 522 523 /*****************************************************/ 524 #if PRAGMA_STRUCT_ALIGN 525 #pragma options align=reset 526 #elif PRAGMA_STRUCT_PACKPUSH 527 #pragma pack( pop ) 528 #elif PRAGMA_STRUCT_PACK 529 #pragma pack( ) 530 #endif 531 532 #ifdef PRAGMA_IMPORT_OFF 533 #pragma import off 534 #elif PRAGMA_IMPORT 535 #pragma import reset 536 #endif 537 538 #ifdef __cplusplus 539 } 540 #endif 541 /*****************************************************/ 542 #endif // _HID_Utilities_External_h_ 543