source: trunk/StreamVision/HID_Utilities_External.h @ 649

Last change on this file since 649 was 300, checked in by Nicholas Riley, 13 years ago

HIDRemotemodule.m: Support for Logitech Music Anywhere USB headphones.

libHIDUtilities.a, HID_Utilities_External.h: built from <http://homepage.mac.com/geowar1/.Public/Sample%20Code/HID_Utilities.sit>

setup.py: Build HIDRemote module.

StreamVision?.py: Support Bluetooth headphones; don't turn on/off the
stereo if we use the play/pause control on the headphones.

File size: 27.3 KB
Line 
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
70extern "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        /*****************************************************/
197#pragma mark - exported globals
198        /*****************************************************/
199#pragma mark - exported function prototypes
200        /*****************************************************/
201#pragma mark HID Utilities interface
202        /*****************************************************/
203        // Create and open an interface to device, required prior to extracting values or building queues
204        // Notes: appliction now owns the device and must close and release it prior to exiting
205        extern unsigned long HIDCreateOpenDeviceInterface(UInt32 inHIDDevice, hu_device_t* inDevice);
206       
207        // builds list of device with elements(allocates memory and captures devices)
208        // list is allocated internally within HID Utilites and can be accessed via accessor functions
209        // structures within list are considered flat and user accessable, but not user modifiable
210        // can be called again to rebuild list to account for new devices(will do the right thing in case of disposing existing list)
211        // inUsagePage, usage are each a inNumDeviceTypes sized array of matching usage and usage pages
212        // returns true if successful
213       
214        extern Boolean HIDBuildMultiDeviceList(UInt32 *inUsagePage, UInt32 *inUsage, UInt32 inNumDeviceTypes);
215       
216        // same as above but this uses a single inUsagePage and usage
217       
218        extern Boolean HIDBuildDeviceList(UInt32 inUsagePage, UInt32 inUsage);
219       
220        // updates the current device list for any new/removed devices
221        // if this is called before HIDBuildDeviceList the it functions like HIDBuildMultiDeviceList
222        // inUsagePage, usage are each a inNumDeviceTypes sized array of matching usage and usage pages
223        // returns true if successful which means if any device were added or removed(the device config changed)
224       
225        extern Boolean HIDUpdateDeviceList(UInt32 *inUsagePage, UInt32 *inUsage, UInt32 inNumDeviceTypes);
226       
227        // release list built by above function
228        // MUST be called prior to application exit to properly release devices
229        // if not called(or app crashes) devices can be recovered by pluging into different location in USB chain
230        extern void HIDReleaseDeviceList(void);
231       
232        // does a device list exist
233        extern Boolean HIDHaveDeviceList(void);
234       
235        // how many HID devices have been found
236        // returns 0 if no device list exist
237        extern UInt32 HIDCountDevices(void);
238       
239        // how many elements does a specific device have
240        // returns 0 if device is invalid or NULL
241        // uses mask of HIDElementTypeMask to restrict element found
242        // use kHIDElementTypeIO to get non-collection elements
243        extern UInt32 HIDCountDeviceElements(const hu_device_t* inDevice, HIDElementTypeMask inTypeMask);
244       
245        // get the first device in the device list
246        // returns NULL if no list exists
247        extern hu_device_t* HIDGetFirstDevice(void);
248       
249        // get next device in list given current device as parameter
250        // returns NULL if end of list
251        extern hu_device_t* HIDGetNextDevice(const hu_device_t* inDevice);
252       
253        // get the first element of device passed in as parameter
254        // returns NULL if no list exists or device does not exists or is NULL
255        // uses mask of HIDElementTypeMask to restrict element found
256        // use kHIDElementTypeIO to get previous HIDGetFirstDeviceElement functionality
257        extern hu_element_t* HIDGetFirstDeviceElement(const hu_device_t* inDevice, HIDElementTypeMask inTypeMask);
258       
259        // get next element of given device in list given current element as parameter
260        // will walk down each collection then to next element or collection(depthwise traverse)
261        // returns NULL if end of list
262        // uses mask of HIDElementTypeMask to restrict element found
263        // use kHIDElementTypeIO to get previous HIDGetNextDeviceElement functionality
264        extern hu_element_t* HIDGetNextDeviceElement(hu_element_t* inElement, HIDElementTypeMask inTypeMask);
265       
266        // get previous element of given device in list given current element as parameter
267        // this walks directly up the tree to the top element and does not search at each level
268        // returns NULL if beginning of list
269        // uses mask of HIDElementTypeMask to restrict element found
270        // use kHIDElementTypeIO to get non-collection elements
271        extern hu_element_t* HIDGetPreviousDeviceElement(const hu_element_t* inElement, HIDElementTypeMask inTypeMask);
272       
273        /*****************************************************/
274#pragma mark Name Lookup Interfaces
275        /*****************************************************/
276        /*!
277                @HIDGetElementNameFromVendorProductCookie
278         @abstract  (set name from vendor id/product id look up)
279         @discussion(using cookies)
280         @param      (name) (description)
281         @result    (description)
282         */
283       
284        // set name from vendor id/product id look up(using cookies)
285        extern Boolean HIDGetElementNameFromVendorProductCookie(long inVendorID, long inProductID, long inCookie, char* inCStrName);
286       
287        // set name from vendor id/product id look up(using usage page & usage)
288        extern Boolean HIDGetElementNameFromVendorProductUsage(long inVendorID, long inProductID, long inUsagePage, long inUsage, char* inCStrName);
289       
290        // Add device to usage & cookie db's
291        extern Boolean HIDAddDeviceToXML(const hu_device_t* inDevice);
292       
293        // Add element to usage & cookie db's
294        extern Boolean HIDAddDeviceElementToXML(const hu_device_t* inDevice, const hu_element_t* inElement);
295       
296        // returns C string type name given a type enumeration passed in as parameter(see IOHIDKeys.h)
297        // returns empty string for invlid types
298        extern void HIDGetTypeName(IOHIDElementType inIOHIDElementType, char* inCStrName);
299       
300        // returns C string usage given usage page and usage passed in as parameters(see IOUSBHIDParser.h)
301        // returns usage page and usage values in string form for unknown values
302        extern void HIDGetUsageName(long inUsagePage, long inUsage, char* inCStrName);
303       
304        /*****************************************************/
305        // convert an element type to a mask
306        extern HIDElementTypeMask HIDConvertElementTypeToMask(IOHIDElementType inIOHIDElementType);
307       
308        // find this device
309        extern Boolean HIDFindDevice(const hu_device_t* inSearchDevice, hu_device_t **outFoundDevice);
310       
311        // find the device and element for this action
312        // Device: serial, vendorID, productID, location, inUsagePage, usage
313        // Element: cookie, inUsagePage, usage,
314        extern Boolean HIDFindActionDeviceAndElement(const hu_device_t* inSearchDevice, const hu_element_t* inSearchElement, hu_device_t **outFoundDevice, hu_element_t **outFoundElement);
315       
316        // find the device and element for this action
317        // Device: serial, vendorID, productID, location, inUsagePage, usage
318        // Element: cookie, inUsagePage, usage,
319       
320        extern Boolean HIDFindSubElement(const hu_element_t* inStartElement, const hu_element_t* inSearchElement, hu_element_t **outFoundElement);
321       
322        // print out all of an elements information
323        extern int HIDPrintElement(const hu_element_t* inElement);
324       
325        // return true if this is a valid device pointer
326        extern Boolean HIDIsValidDevice(const hu_device_t* inDevice);
327       
328        // return true if this is a valid element pointer for this device
329        extern Boolean HIDIsValidElement(const hu_device_t* inDevice, const hu_element_t* inElement);
330       
331        /*****************************************************/
332#pragma mark Element Event Queue and Value Interfaces
333        /*****************************************************/
334        enum
335        {
336                kDefaultUserMin = 0,                                    // default user min and max used for scaling
337                kDefaultUserMax = 255
338        };
339       
340        enum
341        {
342                kDeviceQueueSize = 50   // this is wired kernel memory so should be set to as small as possible
343                                                                // but should account for the maximum possible events in the queue
344                                                                // USB updates will likely occur at 100 Hz so one must account for this rate of
345                                                                // if states change quickly(updates are only posted on state changes)
346        };
347       
348        /*****************************************************/
349        // queues specific element, performing any device queue set up required
350        extern unsigned long HIDQueueElement(hu_device_t* inDevice, const hu_element_t* inElement);
351       
352        // adds all elements to queue, performing any device queue set up required
353        extern unsigned long HIDQueueDevice(hu_device_t* inDevice);
354       
355        // removes element for queue, if last element in queue will release queue and device
356        extern unsigned long HIDDequeueElement(hu_device_t* inDevice, const hu_element_t* inElement);
357       
358        // completely removes all elements from queue and releases queue and device
359        extern unsigned long HIDDequeueDevice(hu_device_t* inDevice);
360       
361        // releases all device queues for quit or rebuild(must be called)
362        extern unsigned long HIDReleaseAllDeviceQueues(void);
363       
364        // releases interface to device, should be done prior to exiting application(called from HIDReleaseDeviceList)
365        extern unsigned long HIDCloseReleaseInterface(hu_device_t* inDevice);
366       
367        // returns true if an event is avialable for the element and fills out *outHIDEvent structure, returns false otherwise
368        // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
369        extern unsigned char HIDGetEvent(const hu_device_t* inDevice, void* outHIDEvent);
370       
371        // returns current value for element, creating device interface as required, polling element
372        extern long HIDGetElementEvent(const hu_device_t* inDevice, hu_element_t* inElement, IOHIDEventStruct* outIOHIDEvent);
373       
374        // returns current value for element, creating device interface as required, polling element
375        extern long HIDGetElementValue(const hu_device_t* inDevice, hu_element_t* inElement);
376       
377        // Set an elements value
378        // NOTE: This should only be used when a single element report needs to be sent.
379        // If multiple elements reports are to be send then transactions should be used.
380        // outIOHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
381        extern long HIDSetElementValue(const hu_device_t* inDevice, const hu_element_t* inElement, void* outIOHIDEvent);
382       
383        // Set a callback to be called when a queue goes from empty to non-empty
384        // Notes: This is a MachO function pointer. If you're using CFM you have to call MachOFunctionPointerForCFMFunctionPointer.
385        extern long HIDSetQueueCallback(hu_device_t* inDevice, IOHIDCallbackFunction inIOHIDCallback, void* inCallbackTarget, void* inCallbackRefcon);
386       
387#if defined(AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER)
388        // Get a report from a device
389        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;
390       
391        // Send a report to a device
392        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;
393#endif // defined(AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER)
394       
395#if defined(AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER)
396        // copy matching elements
397        extern long HIDCopyMatchingElements(const hu_device_t* inDevice, CFDictionaryRef inMatchingDict, CFArrayRef* inElements) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
398        // Set a callback to be called when a report comes in the interrupt pipe
399        // Notes: This is a MachO function pointer. If you're using CFM you have to call MachOFunctionPointerForCFMFunctionPointer.
400        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;
401#endif // defined(AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER)
402       
403        /*****************************************************/
404#pragma mark calibration & scale routines
405        /*****************************************************/
406        // returns calibrated value given raw value passed in
407        // calibrated value is equal to min and max values returned by HIDGetElementValue since device list built scaled to element reported min and max values
408        extern SInt32 HIDCalibrateValue(SInt32 inValue, hu_element_t* inElement);
409       
410        // returns scaled value given raw value passed in
411        // 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
412        extern SInt32 HIDScaleValue(SInt32 inValue, const hu_element_t* inElement);
413       
414        /*****************************************************/
415#pragma mark Conguration and Save Interfaces
416        /*****************************************************/
417#define kPercentMove 10 // precent of overall range a element must move to register
418       
419        typedef struct hu_SaveRec_t
420        {
421                long actionCookie;
422                // device(need to add serial number when I have a test case)
423                long vendorID;
424                long productID;
425                long locID;
426                long usage;
427                long usagePage;
428                // elements
429                long usagePageE;
430                long usageE;
431                void* cookie;
432        }hu_SaveRec_t;
433       
434        // polls all devices and elements for a change greater than kPercentMove. Times out after given time
435        // returns true and pointer to device and element if found
436        // returns false and NULL for both parameters if not found
437        extern unsigned char HIDConfigureAction(hu_device_t **outDevice, hu_element_t **outElement, float inTimeout);
438       
439        // -- These are routines to use if the applcation wants HID Utilities to do the file handling --
440        // Notes: the FILE* is a MachO posix FILE and will not work with the MWCW MSL FILE* type.
441       
442        // take input records, save required info
443        // assume file is open and at correct position.
444        extern void HIDSaveElementConfig(FILE* inFILE, const hu_device_t* inDevice, const hu_element_t* inElement, long inActionCookie);
445       
446        // take file, read one record(assume file position is correct and file is open)
447        // search for matching device
448        // return inDevice, inElement and cookie for action
449        extern long HIDRestoreElementConfig(FILE* inFILE, hu_device_t **outDevice, hu_element_t **outElement);
450       
451        // -- These routines use the CFPreferences API's.
452       
453        // Save the device & element values into the specified key in the specified applications preferences
454        extern Boolean HIDSaveElementPref(CFStringRef inKeyCFStringRef, CFStringRef inAppCFStringRef, const hu_device_t* inDevice, const hu_element_t* inElement);
455       
456        // Find the specified preference in the specified application
457        // search for matching device and element
458        // return inDevice, inElement that matches
459       
460        extern Boolean HIDRestoreElementPref(CFStringRef inKeyCFStringRef, CFStringRef inAppCFStringRef, hu_device_t **outDevice, hu_element_t **outElement);
461       
462        // -- These are routines to use if the client wants to use their own file handling --
463       
464        // Set up a config record for saving
465        // takes an input records, returns record user can save as they want
466        // Notes: the save rec must be pre-allocated by the calling app and will be filled out
467        extern void HIDSetElementConfig(hu_SaveRec_t* inConfigRec, const hu_device_t* inDevice, const hu_element_t* inElement, long inActionCookie);
468       
469        // Get matching element from config record
470        // takes a pre-allocated and filled out config record
471        // search for matching device
472        // return inDevice, inElement and cookie for action
473        extern long HIDGetElementConfig(hu_SaveRec_t* inConfigRec, hu_device_t **outDevice, hu_element_t **outElement);
474       
475        /*****************************************************/
476#pragma mark Output Transaction interface
477        /*****************************************************/
478        // Create and open an transaction interface to device, required prior to extracting values or building Transactions
479        extern unsigned long HIDTransactionAddElement(hu_device_t* inDevice, const hu_element_t* inElement);
480       
481        // removes an element from a Transaction
482        extern unsigned long HIDTransactionRemoveElement(hu_device_t* inDevice, const hu_element_t* inElement);
483       
484        // return true if this transaction contains this element
485        extern Boolean HIDTransactionHasElement(hu_device_t* inDevice, const hu_element_t* inElement);
486       
487        /* This changes the default value of an element, when the values of the */
488        /* elements are cleared, on clear or commit, they are reset to the */
489        /* default value */
490        /* This call can be made on elements that are not in the transaction, but */
491        /* has undefined behavior if made on elements not in the transaction */
492        /* which are later added to the transaction. */
493        /* In other words, an element should be added before its default is */
494        /* set, for well defined behavior. */
495        // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
496        extern unsigned long HIDTransactionSetElementDefault(hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent);
497       
498        /* Get the current setting of an element's default value */
499        // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
500        extern unsigned long HIDTransactionGetElementDefault(hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent);
501       
502        /* Add a change to the transaction, by setting an element value */
503        /* The change is not actually made until it is commited */
504        /* The element must be part of the transaction or this call will fail */
505        // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
506        extern unsigned long HIDTransactionSetElementValue(hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent);
507       
508        /* Get the current setting of an element value */
509        // outHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
510        extern unsigned long HIDTransactionGetElementValue(hu_device_t* inDevice, const hu_element_t* inElement, IOHIDEventStruct* inValueEvent);
511       
512        /* Commit the transaction, or clear all the changes and start over */
513        extern unsigned long HIDTransactionCommit(hu_device_t* inDevice);
514       
515        /* Clear all the changes and start over */
516        extern unsigned long HIDTransactionClear(hu_device_t* inDevice);
517       
518        /*****************************************************/
519#if PRAGMA_STRUCT_ALIGN
520#pragma options align=reset
521#elif PRAGMA_STRUCT_PACKPUSH
522#pragma pack(pop)
523#elif PRAGMA_STRUCT_PACK
524#pragma pack()
525#endif
526       
527#ifdef PRAGMA_IMPORT_OFF
528#pragma import off
529#elif PRAGMA_IMPORT
530#pragma import reset
531#endif
532       
533#ifdef __cplusplus
534}
535#endif
536/*****************************************************/
537#endif // _HID_Utilities_External_h_
Note: See TracBrowser for help on using the repository browser.