#alternate HID Class Device Interface Guide Next Prev Mac Developer Library Developer HID Class Device Interface Guide PDF Companion File * (BUTTON) Table of Contents * [Jump To…] * (BUTTON) Download Sample Code Accessing a HID Device OS X version 10.5 ("Leopard") introduces new APIs that abstract he current complexities of utilizing the I/O Kit to communicate with the HID Manager. These APIs allow you to enumerate HID devices and elements, access their properties, register for notification of HID device discovery and removal (hot plugging and unplugging), send and receive device reports, use queues to get notification of HID element value changes, and use transactions to talk to HID devices. Application developers that need to communicate with HID devices should read this chapter first. This documentation assumes a basic understanding of the material contained in Accessing Hardware From Applications. For definitions of I/O Kit terms used in this documentation (such as matching dictionaries) see the overview of I/O Kit terms and concepts in the “Device Access and the I/O Kit” chapter. A detailed description of the HID class specification is beyond the scope of this document. For more information, including the complete listing of HID usage tables, visit the USB website at http://www.usb.org/developers/hidpage/. Note: For binary compatibility, HID code written for OS X version 10.4 ("Tiger") will continue to work for the lifetime of OS X version 10.5 ("Leopard"). New development targeting Leopard should use the new HID Manager APIs. Note: All HID functions with callback parameters also have a context pointer parameter whose value is passed to that callback. These context pointers are intended for developer use and are passed as-is to the callback routines. In particular, they are not retained, released, or freed in any way. If you need to retain an object passed to one of these routines, you must do so yourself prior to registering the callback. Device Matching and Access HID Manager references are used to communicate with the I/O Kit HID subsystem. They are created by using the IOHIDManagerCreate function: // Create HID Manager reference IOHIDManagerRef IOHIDManagerCreate( CFAllocatorRef inCFAllocatorRef, // Allocator to be used during creation IOOptionBits inOptions); // options Reserved for future use The first parameter (allocator) is a CFAllocator to be used when allocating the returned IOHIDManagerRef. The last parameter (options) is currently reserved for future use. Developers should pass kIOHIDOptionsTypeNone (zero) for this parameter. There is no IOHIDManagerDestroy (or release, free, and so on); because the HID Manager reference is a Core Foundation object reference, CFRelease should be used to dispose of it. A CFTypeRef can be verified to be a HID Manager reference by comparing its Core Foundation type against IOHIDManagerGetTypeID: Listing 2-1 Validating a HID Manager reference if (CFGetTypeID(tCFTypeRef) == IOHIDManagerGetTypeID()) { // this is a HID Manager reference! } Matching HID Devices Once a HID Manager reference has been created, it has to be opened before it can be used to access the HID devices associated with it. To restrict the HID devices with which a HID Manager reference is associated, set a matching dictionary (single criteria) or array of matching dictionaries (multiple criteria). The functions are: // Sets single matching criteria (dictionary) for device enumeration. void IOHIDManagerSetDeviceMatching( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFDictionaryRef inMatchingDictRef); // single dictionary containing device matching criteria. // Sets multiple matching criteria (array of dictionaries) for device enumeration. void IOHIDManagerSetDeviceMatchingMultiple( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFArrayRef inCFArrayRef); // array of dictionaries containing device matching criteria. Note: Either one of the above APIs must be called before any devices will be matched. The matching keys used in the dictionary entries are declared in : Listing 2-2 HID device property keys #include #define kIOHIDTransportKey "Transport" #define kIOHIDVendorIDKey "VendorID" #define kIOHIDVendorIDSourceKey "VendorIDSource" #define kIOHIDProductIDKey "ProductID" #define kIOHIDVersionNumberKey "VersionNumber" #define kIOHIDManufacturerKey "Manufacturer" #define kIOHIDProductKey "Product" #define kIOHIDSerialNumberKey "SerialNumber" #define kIOHIDCountryCodeKey "CountryCode" #define kIOHIDLocationIDKey "LocationID" #define kIOHIDDeviceUsageKey "DeviceUsage" #define kIOHIDDeviceUsagePageKey "DeviceUsagePage" #define kIOHIDDeviceUsagePairsKey "DeviceUsagePairs" #define kIOHIDPrimaryUsageKey "PrimaryUsage" #define kIOHIDPrimaryUsagePageKey "PrimaryUsagePage" #define kIOHIDMaxInputReportSizeKey "MaxInputReportSize" #define kIOHIDMaxOutputReportSizeKey "MaxOutputReportSize" #define kIOHIDMaxFeatureReportSizeKey "MaxFeatureReportSize" #define kIOHIDReportIntervalKey "ReportInterval" Note: The kIOHIDPrimaryUsageKey and kIOHIDPrimaryUsagePageKey keys are no longer rich enough to describe a HID device's capabilities. For example, take a HID device that describes both a keyboard and a mouse in the same descriptor. The previous behavior was to only describe the keyboard behavior with the primary usage and usage page. Needless to say, this would sometimes cause a program interested in mice to skip this device when matching. To resolve this issue three additional keys have been added: * kIOHIDDeviceUsageKey * kIOHIDDeviceUsagePageKey * kIOHIDDeviceUsagePairsKey The kIOHIDDeviceUsagePairsKey key is used to represent an array of dictionaries containing key/value pairs referenced by kIOHIDDeviceUsageKey and kIOHIDDeviceUsagePageKey. These usage pairs describe all application type collections (behaviors) defined by the HID device. An application interested in only matching on one criteria would only add the kIOHIDDeviceUsageKey and kIOHIDDeviceUsagePageKey keys to the matching dictionary. If it is interested in a HID device that has multiple behaviors, the application would instead add an array of dictionaries referenced by kIOHIDDeviceUsagePairsKey to their matching dictionary. This is equivalent to passing an array of dictionaries each containing two entries with keys kIOHIDDeviceUsagePageKey and kIOHIDDeviceUsageKey to IOHIDManagerSetDeviceMatchingMultiple. Passing a NULL dictionary will result in all devices being enumerated. Any subsequent calls will cause the HID Manager to release previously enumerated devices and restart the enumeration process using the revised criteria. Listing 2-3 Matching against a single set (dictionary) of properties // function to create matching dictionary static CFMutableDictionaryRef hu_CreateDeviceMatchingDictionary(UInt32 inUsagePage, UInt32 inUsage) { // create a dictionary to add usage page/usages to CFMutableDictionaryRef result = CFDictionaryCreateMutable( kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); if (result) { if (inUsagePage) { // Add key for device type to refine the matching dictionary. CFNumberRef pageCFNumberRef = CFNumberCreate( kCFAllocatorDefault, kCFNumberIntType, &inUsagePage); if (pageCFNumberRef) { CFDictionarySetValue(result, CFSTR(kIOHIDDeviceUsagePageKey), pageCFNumberRef); CFRelease(pageCFNumberRef); // note: the usage is only valid if the usage page is also defined if (inUsage) { CFNumberRef usageCFNumberRef = CFNumberCreate( kCFAllocatorDefault, kCFNumberIntType, &inUsage); if (usageCFNumberRef) { CFDictionarySetValue(result, CFSTR(kIOHIDDeviceUsageKey), usageCFNumberRef); CFRelease(usageCFNumberRef); } else { fprintf(stderr, "%s: CFNumberCreate(usage) failed.", __PRETTY_FUNCTION__); } } } else { fprintf(stderr, "%s: CFNumberCreate(usage page) failed.", __PRETTY_FUNCTION__); } } } else { fprintf(stderr, "%s: CFDictionaryCreateMutable failed.", __PRETTY_FUNCTION__); } return result; } // hu_CreateDeviceMatchingDictionary // Create a matching dictionary CFDictionaryRef matchingCFDictRef = hu_CreateDeviceMatchingDictionary(kHIDPage_GenericDesktop, kHIDUsage_GD_Keyboard); if (matchingCFDictRef) { // set the HID device matching dictionary IOHIDManagerSetDeviceMatching(managerRef, matchingCFDictRef); } else { fprintf(stderr, "%s: hu_CreateDeviceMatchingDictionary failed.", __PRETTY_FUNCTION__); } Listing 2-4 Matching against multiple sets (arrays of dictionaries) of properties // create an array of matching dictionaries CFArrayRef matchingCFArrayRef = CFArrayCreateMutable(kCFAllocatorDefault, 0, &kCFTypeArrayCallBacks); if (matchingCFArrayRef) { // create a device matching dictionary for joysticks CFDictionaryRef matchingCFDictRef = hu_CreateDeviceMatchingDictionary(kHIDPage_GenericDesktop, kHIDUsage_GD_Joystick); if (matchingCFDictRef) { // add it to the matching array CFArrayAppendValue(matchingCFArrayRef, matchingCFDictRef); CFRelease(matchingCFDictRef); // and release it } else { fprintf(stderr, "%s: hu_CreateDeviceMatchingDictionary(joystick) failed.", __PRETTY_FUNCTION__); } // create a device matching dictionary for game pads matchingCFDictRef = hu_CreateDeviceMatchingDictionary(kHIDPage_GenericDesktop, kHIDUsage_GD_GamePad); if (matchingCFDictRef) { // add it to the matching array CFArrayAppendValue(matchingCFArrayRef, matchingCFDictRef); CFRelease(matchingCFDictRef); // and release it } else { fprintf(stderr, "%s: hu_CreateDeviceMatchingDictionary(game pad) failed.", __PRETTY_FUNCTION__); } } else { fprintf(stderr, "%s: CFArrayCreateMutable failed.", __PRETTY_FUNCTION__); } -- EITHER -- // create a dictionary for the kIOHIDDeviceUsagePairsKey entry matchingCFDictRef = CFDictionaryCreateMutable( kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); // add the matching array to it CFDictionarySetValue(matchingCFDictRef, CFSTR(kIOHIDDeviceUsagePairsKey), matchingCFArrayRef); // release the matching array CFRelease(matchingCFArrayRef); // set the HID device matching dictionary IOHIDManagerSetDeviceMatching(managerRef, matchingCFDictRef); // and then release it CFRelease(matchingCFDictRef); -- OR -- // set the HID device matching array IOHIDManagerSetDeviceMatchingMultiple(managerRef, matchingCFArrayRef); // and then release it CFRelease(matchingCFArrayRef); Before opening the HID Manager reference it may be desirable to register routines to be called when (matching) devices are connected or disconnected. Note: This matching routine is called once per currently connected (and matching) device when the HID Manager reference is opened. // Register device matching callback routine // This routine will be called when a new (matching) device is connected. void IOHIDManagerRegisterDeviceMatchingCallback( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference IOHIDDeviceCallback inIOHIDDeviceCallback, // Pointer to the callback routine void * inContext); // Pointer to be passed to the callback // Registers a routine to be called when any currently enumerated device is removed. // This routine will be called when a (matching) device is disconnected. void IOHIDManagerRegisterDeviceRemovalCallback( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference IOHIDDeviceCallback inIOHIDDeviceCallback, // Pointer to the callback routine void * inContext); // Pointer to be passed to the callback Note: There is no special function to unregister HID callback routines. You can unregistered by calling the appropriate registration function and passing NULL for the pointer to the callback routine. Listing 2-5 Examples of HID device matching & removal callback routines // this will be called when the HID Manager matches a new (hot plugged) HID device static void Handle_DeviceMatchingCallback( void * inContext, // context from IOHIDManagerRegisterDeviceMatchingCallback IOReturn inResult, // the result of the matching operation void * inSender, // the IOHIDManagerRef for the new device IOHIDDeviceRef inIOHIDDeviceRef // the new HID device ) { printf("%s(context: %p, result: %p, sender: %p, device: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, (void*) inIOHIDDeviceRef); } // Handle_DeviceMatchingCallback // this will be called when a HID device is removed (unplugged) static void Handle_RemovalCallback( void * inContext, // context from IOHIDManagerRegisterDeviceMatchingCallback IOReturn inResult, // the result of the removing operation void * inSender, // the IOHIDManagerRef for the device being removed IOHIDDeviceRef inIOHIDDeviceRef // the removed HID device ) { printf("%s(context: %p, result: %p, sender: %p, device: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, (void*) inIOHIDDeviceRef); } // Handle_RemovalCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Scheduling the HID Manager on a Run Loop Before HID Manager callback routines can be dispatched the HID Manager reference must first be scheduled with a run loop: // Schedule HID Manager with run loop void IOHIDManagerScheduleWithRunLoop( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFRunLoopRef inRunLoop, // Run loop to be used when scheduling asynchronous activity CFStringRef inRunLoopMode); // Run loop mode to be used when scheduling This formally associates the HID Manager with the client's run loop. This schedule will propagate to all HID devices that are currently enumerated and to new HID devices as they are matched by the HID Manager. Listing 2-6 Scheduling a HID Manager with the current run loop IOHIDManagerScheduleWithRunLoop(inIOHIDManagerRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode); There is a corresponding function to unschedule a HID Manager reference from a run loop: void IOHIDManagerUnscheduleFromRunLoop( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFRunLoopRef inRunLoop, // Run loop to be used when unscheduling asynchronous activity CFStringRef inRunLoopMode); // Run loop mode to be used when unscheduling Listing 2-7 Unscheduling a HID Manager from a run loop IOHIDManagerUnscheduleFromRunLoop(managerRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode); Now we're ready to open the HID Manager reference. // Open a HID Manager reference IOReturn IOHIDManagerOpen( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference IOOptionBits inOptions); // Option bits This will open all matching HID devices. It returns kIOReturnSuccess if successful. Currently the only valid options (second parameter) are kIOHIDOptionsTypeNone or kIOHIDOptionsTypeSeizeDevice (which forces exclusive access for all matching devices). Note: As of Leopard, the kIOHIDOptionsTypeSeizeDevice option requires root privileges to be used with keyboard devices. If there is a device matching callback routine registered when IOHIDManagerOpen is called then this routine will be called once for each HID device currently connected that matches the current matching criteria. This routine will also be called when new devices that match the current matching criteria are connected to the computer (but only if the HID Manager reference is still open). Listing 2-8 Opening a HID Manager reference // open it IOReturn tIOReturn = IOHIDManagerOpen(managerRef, kIOHIDOptionsTypeNone); Once a HID Manager reference has been opened it may be closed by using the IOHIDManagerClose function: // Closes the IOHIDManager IOReturn IOHIDManagerClose(IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference IOOptionBits inOptions); // Option bits This will also close all devices that are currently enumerated. The options are propagated to the HID device close function. Registering Value Callbacks Once a connection to the HID manager is open, developers may register a routine to be called when input values change: // Register a routine to be called when an input value changes void IOHIDManagerRegisterInputValueCallback( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference IOHIDValueCallback inCallback, // Pointer to the callback routine void * inContext); // Pointer to be passed to the callback The registered callback routine will be called when the HID value of any element of type kIOHIDElementTypeInput changes for all matching HID devices. Note: To unregister pass NULL for the callback. Note: The HID Manager must be scheduled with a run loop for HID Manager callbacks to be dispatched. See Listing 2-6 for more information. Listing 2-9 Registering for an input value callback IOHIDManagerRegisterInputValueCallback(managerRef, Handle_IOHIDInputValueCallback, context); This routine will be called when an input value changes for any input element for all matching devices. Listing 2-10 Example input value callback routine static void Handle_IOHIDInputValueCallback( void * inContext, // context from IOHIDManagerRegisterInputValueCallback IOReturn inResult, // completion result for the input value operation void * inSender, // the IOHIDManagerRef IOHIDValueRef inIOHIDValueRef // the new element value ) { printf("%s(context: %p, result: %p, sender: %p, value: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, (void*) inIOHIDValueRef); } // Handle_IOHIDInputValueCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Note: HID values are documented in the “HID Value Functions” section. If only notifications from specific devices are of interest, then the IOHIDDeviceRegisterInputValueCallback function (described in Listing 2-20) should be used. For value changes on specific HID elements, the HID queue functions (described in “HID Queue Functions”) should be used. To receive notifications when HID reports are received from a HID device, the IOHIDDeviceGetReport or IOHIDDeviceGetReportWithCallback functions (described in Listing 2-28) may be used. void IOHIDManagerSetInputValueMatching( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFDictionaryRef inMatchingDictRef); // single dictionary containing // element matching criteria. // Sets multiple matching criteria (array of dictionaries) // for the input value callback. void IOHIDManagerSetInputValueMatchingMultiple( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFArrayRef inCFArrayRef); // array of dictionaries containing // element matching criteria. Note: The default element criteria is to match all elements. Specific matching criteria can be reset to this default by passing NULL to ether of the above APIs. Note: The IOHIDManagerSetInputValueMatching, IOHIDManagerSetInputValueMatchingMultiple, IOHIDDeviceSetInputValueMatching, and IOHIDDeviceSetInputValueMatchingMultiple APIs (documented below) override each other. The last one called has precedence. The matching keys for HID elements are prefixed by kIOHIDElement. They are declared in . See Listing 2-31 for more information. The IOHIDManagerGetProperty and IOHIDManagerSetProperty functions are available to access the HID Manager's properties: // Obtains a property of a HIDManagerRef CFTypeRef IOHIDManagerGetProperty( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFStringRef inKeyCFStringRef); // CFStringRef for the key // Sets a property for a HIDManagerRef void IOHIDManagerSetProperty( IOHIDManagerRef inIOHIDManagerRef, // HID Manager reference CFStringRef inKeyCFStringRef, // CFStringRef for the key CFTypeRef inValueCFTypeRef); // the HID value for the property Currently there are not any default HID Manager properties set by the system. However since HID Manager properties are propagated to all HID devices as they are enumerated (matched) this might be a convient way to set default HID device property values. Note: Currently all HID Manager, device, and element properties are lost when the HID Manager reference that they are associated with is closed. Developers should save and restore any values that they want to persist outside that scope. Listing 2-11 Accessing HID Manager properties CFTypeRef tCFTypeRef = IOHIDManagerGetProperty(managerRef, key); IOHIDManagerSetProperty(managerRef, key, tCFTypeRef); To determine what devices match the current matching criteria use IOHIDManagerCopyDevices: CFSetRef IOHIDManagerCopyDevices(IOHIDManagerRef inIOHIDManagerRef); // HID Manager reference The parameter is a HID Manager reference. This call returns a Core Foundation set (CFSetRef) of IOHIDDeviceRef objects. Listing 2-12 Getting the set of matching HID device references CFSetRef tCFSetRef = IOHIDManagerCopyDevices(managerRef); The HID device references in the returned set can be obtained by using the CFSetGetValues function or iterated over by using the CFSetApplyFunction function. HID Device Functions A CFTypeRef object can be verified to be a HID device reference by comparing its Core Foundation type against IOHIDDeviceGetTypeID: Listing 2-13 Validating a HID device reference if (CFGetTypeID(tCFTypeRef) == IOHIDDeviceGetTypeID()) { // this is a valid HID device reference } Once you have a valid HID device reference the IOHIDDeviceGetProperty function can be used to access its properties (manufacturer, vendor, product IDs, and so on) using the HID device keys defined in . See Listing 2-2 for more information. Listing 2-14 Examples of getting HID device properties // Get a HID device's transport (string) CFStringRef IOHIDDevice_GetTransport(IOHIDDeviceRef inIOHIDDeviceRef) { return IOHIDDeviceGetProperty(inIOHIDDeviceRef, CFSTR(kIOHIDTransportKey)); } // function to get a long device property // returns FALSE if the property isn't found or can't be converted to a long static Boolean IOHIDDevice_GetLongProperty( IOHIDDeviceRef inDeviceRef, // the HID device reference CFStringRef inKey, // the kIOHIDDevice key (as a CFString) long * outValue) // address where to return the output value { Boolean result = FALSE; CFTypeRef tCFTypeRef = IOHIDDeviceGetProperty(inDeviceRef, inKey); if (tCFTypeRef) { // if this is a number if (CFNumberGetTypeID() == CFGetTypeID(tCFTypeRef)) { // get its value result = CFNumberGetValue((CFNumberRef) tCFTypeRef, kCFNumberSInt32Type, outValue); } } return result; } // IOHIDDevice_GetLongProperty // Get a HID device's vendor ID (long) long IOHIDDevice_GetVendorID(IOHIDDeviceRef inIOHIDDeviceRef) { long result = 0; (void) IOHIDDevice_GetLongProperty(inIOHIDDeviceRef, CFSTR(kIOHIDVendorIDKey), &result); return result; } // IOHIDDevice_GetVendorID // Get a HID device's product ID (long) long IOHIDDevice_GetProductID(IOHIDDeviceRef inIOHIDDeviceRef) { long result = 0; (void) IOHIDDevice_GetLongProperty(inIOHIDDeviceRef, CFSTR(kIOHIDProductIDKey), &result); return result; } // IOHIDDevice_GetProductID Determining Suitability There is a convenience function that will scan a device's application collection elements to determine if the device conforms to a specified usage page and usage: Boolean IOHIDDeviceConformsTo(IOHIDDeviceRef inIOHIDDeviceRef, // IOHIDDeviceRef for the HID device uint32_t inUsagePage, // the usage page to test conformance with uint32_t inUsage); // the usage to test conformance with Some examples of application collection usage pairs are: * usagePage = kHIDPage_GenericDesktop, usage = kHIDUsage_GD_Mouse * usagePage = kHIDPage_GenericDesktop, usage = kHIDUsage_GD_Keyboard Before you can communicate with a HID device it has to be opened; Opened HID device references should be closed when communications are complete. Here are the functions to open and close a HID device reference: IOReturn IOHIDDeviceOpen(IOHIDDeviceRef inIOHIDDeviceRef, // IOHIDDeviceRef for the HID device IOOptionBits inOptions); // Option bits to be sent down to the HID device IOReturn IOHIDDeviceClose(IOHIDDeviceRef IOHIDDeviceRef, // IOHIDDeviceRef for the HID device IOOptionBits inOptions); // Option bits to be sent down to the HID device On the IOHIDDeviceOpen call developers may pass kIOHIDOptionsTypeNone or kIOHIDOptionsTypeSeizeDevice option to request exclusive access to the HID device. Both functions return kIOReturnSuccess if successful. Note: As of Leopard, the kIOHIDOptionsTypeSeizeDevice option requires root privileges to be used with keyboard devices. Obtaining Elements for a Device To obtain the HID elements associated with a specific device use the IOHIDDeviceCopyMatchingElements function: // return the HID elements that match the criteria contained in the matching dictionary CFArrayRef IOHIDDeviceCopyMatchingElements( IOHIDDeviceRef inIOHIDDeviceRef, // IOHIDDeviceRef for the HID device CFDictionaryRef inMatchingCFDictRef, // the matching dictionary IOOptionBits inOptions); // Option bits The first parameter is the HID Manager reference. The second parameter is a matching dictionary (which may be NULL to return all elements). The third parameter contains any option bits (currently unused, pass kIOHIDOptionsTypeNone). This API returns a CFArrayRef object containing IOHIDElementRef objects. Developers may then use CFArrayGetValueAtIndex function to retrieve a specific IOHIDElementRef object, CFArrayGetValues to retrieve all IOHIDElementRef objects or CFSetApplyFunction to iterate all IOHIDElementRef objects in this array. The matching keys for HID elements are prefixed by kIOHIDElement. They are declared in . See Listing 2-31 for more information. Listing 2-15 IOHIDDeviceCopyMatchingElements examples // to return all elements for a device CFArrayRef elementCFArrayRef = IOHIDDeviceCopyMatchingElements(deviceRef, NULL, kIOHIDOptionsTypeNone); // to return all elements with usage page keyboard // create a dictionary to add element properties to CFMutableDictionaryRef tCFDictRef = CFDictionaryCreateMutable( kCFAllocatorDefault, 0, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks); if (tCFDictRef) { // Add key for element usage page to matching dictionary int usagePage = kHIDUsage_GD_Keyboard; CFNumberRef pageCFNumberRef = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &usagePage); if (pageCFNumberRef) { CFDictionarySetValue(tCFDictRef, CFSTR(kIOHIDElementUsagePageKey), pageCFNumberRef); CFRelease(pageCFNumberRef); } else { fprintf(stderr, "%s: CFNumberCreate(usage page) failed.", __PRETTY_FUNCTION__); } } else { fprintf(stderr, "%s: CFDictionaryCreateMutable failed.", __PRETTY_FUNCTION__); } if (tCFDictRef) { CFArrayRef elementCFArrayRef = IOHIDDeviceCopyMatchingElements( deviceRef, tCFDictRef, kIOHIDOptionsTypeNone); CFRelease(tCFDictRef); } Registering for Unplug Notifications Callbacks can be registered that will be called when a HID device is unplugged, when input values change, when input reports are received, or when asynchronous get and set value and report functions complete. (These callbacks are documented below.) Before these HID device callbacks are dispatched, however, the HID device must be scheduled with a run loop. Note: If a HID Manager is scheduled with a run loop, then by default, when new devices are matched by that HID Manager, they are automatically scheduled with the same run loop, in which case this additional step is unnecessary. Listing 2-16 Scheduling a HID device with a run loop IOHIDDeviceScheduleWithRunLoop(inIOHIDDeviceRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode); There is a corresponding function to unschedule a HID device from a run loop: Listing 2-17 Unscheduling a HID device from a run loop IOHIDDeviceUnscheduleFromRunLoop(deviceRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode); To register a routine to be called when a HID device is removed: Listing 2-18 Registering a HID device removal callback routine IOHIDDeviceRegisterRemovalCallback(deviceRef, Handle_IOHIDDeviceRemovalCallback, context); Note: To unregister pass NULL for the callback. Listing 2-19 HID device removal callback routine static void Handle_IOHIDDeviceRemovalCallback( void * inContext, // context from IOHIDDeviceRegisterRemovalCallback IOReturn inResult, // the result of the removal void * inSender // IOHIDDeviceRef for the HID device being removed ) { printf("%s(context: %p, result: %p, sender: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender); } // Handle_IOHIDDeviceRemovalCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Registering for Value Change Notifications To register a routine to be called when an input value is changed by a HID device: Listing 2-20 Registering a HID device input value callback routine IOHIDDeviceRegisterInputValueCallback(deviceRef, Handle_IOHIDDeviceInputValueCallback, context); The first parameter is a HID device reference. The second parameter is the callback routine. The third parameter is a user context parameter that is passed to that callback routine. Note: To unregister pass NULL for the callback. Listing 2-21 HID device input value callback routine static void Handle_IOHIDDeviceInputValueCallback( void * inContext, // context from IOHIDDeviceRegisterInputValueCallback IOReturn inResult, // completion result for the input value operation void * inSender, // IOHIDDeviceRef of the device this element is from IOHIDValueRef inIOHIDValueRef // the new element value ) { printf("%s(context: %p, result: %p, sender: %p, value: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, (void*) inIOHIDValueRef); } // Handle_IOHIDDeviceInputValueCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Note: HID values are documented in the “HID Value Functions” section. To limit the element value changes reported by this callback to specific HID elements, an element matching dictionary (single criteria) or array of matching dictionaries (multiple criteria) may be set using the IOHIDDeviceSetInputValueMatching or IOHIDDeviceSetInputValueMatchingMultiple functions. // Sets single element matching criteria (dictionary) for the // input value callback. void IOHIDDeviceSetInputValueMatching( IOHIDDeviceRef inIOHIDDeviceRef, // IOHIDDeviceRef for the HID device CFDictionaryRef inMatchingDictRef); // single dictionary containing // element matching criteria. // Sets multiple matching criteria (array of dictionaries) for the // input value callback. void IOHIDDeviceSetInputValueMatchingMultiple( IOHIDDeviceRef inIOHIDDeviceRef, // IOHIDDeviceRef for the HID device CFArrayRef inCFArrayRef); // array of dictionaries containing // element matching criteria. Note: The default element criteria is to match all elements. Specific matching criteria can be reset to this default by passing NULL to ether of the above APIs. Note: The IOHIDDeviceSetInputValueMatching, IOHIDDeviceSetInputValueMatchingMultiple, IOHIDManagerSetInputValueMatching, and IOHIDManagerSetInputValueMatchingMultiple APIs (documented above) override each other. The last one called has precedence. The matching keys for HID elements are prefixed by kIOHIDElement. They are declared in . See Listing 2-31 for more information. Registering for Input Report Notifications To register a routine to be called when an input report is issued by a HID device: Listing 2-22 Registering a HID device input report callback routine CFIndex reportSize = 64; // note: this should be greater than or equal to the size of the report uint8_t report = malloc(reportSize); IOHIDDeviceRegisterInputReportCallback(deviceRef, // IOHIDDeviceRef for the HID device report, // pointer to the report data (uint8_t's) reportSize, // number of bytes in the report (CFIndex) Handle_IOHIDDeviceIOHIDReportCallback, // the callback routine context); // context passed to callback The first parameter is a HID device reference. The second is the address where to store the input report. The third parameter is the address of the callback routine. The last parameter is a user context parameter that is passed to that callback routine. Note: To unregister pass NULL for the callback. The report buffer should be large enough to store the largest report that can be expected to be received from the HID device. This size can be obtained by passing kIOHIDMaxInputReportSizeKey as the key to IOHIDDeviceGetProperty. Listing 2-23 HID device input report callback routine static void Handle_IOHIDDeviceIOHIDReportCallback( void * inContext, // context from IOHIDDeviceRegisterInputReportCallback IOReturn inResult, // completion result for the input report operation void * inSender, // IOHIDDeviceRef of the device this report is from IOHIDReportType inType, // the report type uint32_t inReportID, // the report ID uint8_t * inReport, // pointer to the report data CFIndex InReportLength) // the actual size of the input report { printf("%s(context: %p, result: %p, sender: %p," \ "type: %d, id: %p, report: %p, length: %d).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, (long) inType, inReportID, inReport, inReportLength); } // Handle_IOHIDDeviceIOHIDReportCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Note: The layout and the size of the report data is device specific and requires advanced knowledge of how elements are bundled into reports. While this knowledge is available by parsing HID device descriptors, parsing the descriptors also requires advanced knowledge. A higher level abstraction that doesn't require as much advanced knowledge is the HID transactions APIs described in the “HID Transaction Functions” section. Getting and Setting Output or Feature Values To set the HID value of a single output or feature type element the IOHIDDeviceSetValue (synchronous) or IOHIDDeviceSetValueWithCallback (asynchronous) functions may be used. (to set multiple values consider using reports or transactions): // synchronous IOReturn tIOReturn = IOHIDDeviceSetValue( deviceRef, // IOHIDDeviceRef for the HID device elementRef, // IOHIDElementRef for the HID element valueRef); // IOHIDValueRef for the HID element's new value // asynchronous IOReturn tIOReturn = IOHIDDeviceSetValueWithCallback( deviceRef, // IOHIDDeviceRef for the HID device elementRef, // IOHIDElementRef for the HID element valueRef, // IOHIDValueRef for the HID element's new value tCFTimeInterval, // timeout duration Handle_IOHIDDeviceSetValueCallback, // the callback routine context); // context passed to callback The first parameter is a HID device reference. The second is a HID element reference. The third parameter is a HID value reference. For the asynchronous version, the fourth parameter is a timeout, the fifth parameter is the callback routine, and the last parameter is a context pointer that is passed to that callback routine. Listing 2-24 HID device set value callback routine static void Handle_IOHIDDeviceSetValueCallback( void * inContext, // context from IOHIDDeviceSetValueWithCallback IOReturn inResult, // completion result for the set value operation void * inSender, // IOHIDDeviceRef of the device IOHIDValueRef inIOHIDValueRef) // the HID element value { printf("%s(context: %p, result: %p, sender: %p, value: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, inIOHIDValueRef); } // Handle_IOHIDDeviceSetValueCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Note: HID values are documented in the “HID Value Functions” section. To get the HID value of a single element the IOHIDDeviceGetValue (synchronous) or IOHIDDeviceGetValueWithCallback (asynchronous) functions may be used. (To get multiple values consider using reports or transactions.) For input type elements the synchronous function returns immediately; for feature type elements it will block until the get value report has been issued to the HID device. // synchronous IOReturn tIOReturn = IOHIDDeviceGetValue( deviceRef, // IOHIDDeviceRef for the HID device elementRef, // IOHIDElementRef for the HID element valueRef); // IOHIDValueRef for the HID element's new value // asynchronous IOReturn tIOReturn = IOHIDDeviceGetValueWithCallback( deviceRef, // IOHIDDeviceRef for the HID device elementRef, // IOHIDElementRef for the HID element valueRef, // IOHIDValueRef for the HID element's new value tCFTimeInterval, // timeout duration Handle_IOHIDDeviceGetValueCallback, // the callback routine context); // context passed to callback For both of these functions the first parameter is a HID device reference. The second is a HID element reference. The third parameter is a HID value reference. For the asynchronous version, the fourth parameter is a timeout, the fifth parameter is a callback routine, and the last parameter is a context pointer that is passed to that callback routine. Listing 2-25 HID device get value callback routine static void Handle_IOHIDDeviceGetValueCallback( void * inContext, // context from IOHIDDeviceGetValueWithCallback IOReturn inResult, // completion result for the get value operation void * inSender, // IOHIDDeviceRef of the device IOHIDValueRef inIOHIDValueRef) // the HID element value { printf("%s(context: %p, result: %p, sender: %p, value: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, inIOHIDValueRef); } // Handle_IOHIDDeviceGetValueCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Note: HID values are documented in the “HID Value Functions” section. Getting and Setting HID Reports USB data is transferred to and from HID devices packetized into reports. These reports consist of one or more element fields usually contained in a hierarchy of collections. Developers who understand how elements are packaged into reports can use the IOHIDDeviceGetReport, IOHIDDeviceGetReportWithCallback, IOHIDDeviceSetReport, and IOHIDDeviceSetReportWithCallback functions to talk directly with HID devices. Developers unfamiliar with how HID reports are constructed may use the HID transaction functions. See “HID Transaction Functions” for more information. To send a report to a HID device the IOHIDDeviceSetReport (synchronous) or IOHIDDeviceSetReportWithCallback (asynchronous) functions should be used: Listing 2-26 Sending a HID Report CFIndex reportSize = 64; uint8_t report = malloc(reportSize); // synchronous IOReturn tIOReturn = IOHIDDeviceSetReport( deviceRef, // IOHIDDeviceRef for the HID device tIOHIDReportType, // IOHIDReportType for the report reportID, // CFIndex for the report ID report, // address of report buffer reportLength); // length of the report // asynchronous IOReturn tIOReturn = IOHIDDeviceSetReportWithCallback( deviceRef, // IOHIDDeviceRef for the HID device tIOHIDReportType, // IOHIDReportType for the report reportID, // CFIndex for the report ID report, // address of report buffer reportLength, // length of the report tCFTimeInterval, // timeout duration Handle_IOHIDDeviceSetReportCallback, // the callback routine context); // context passed to callback For both of these functions the first parameter is a HID device reference. The second parameter is an IOHIDReportType object for the report. The third parameter is the report ID. The fourth parameter is the address of the report buffer. The fifth parameter is the size of the report being sent. For the asynchronous version, the sixth parameter is a timeout, the seventh parameter is a callback routine, and the last parameter is a context pointer that is passed to that callback routine: Listing 2-27 HID device set report callback routine static void Handle_IOHIDDeviceSetReportCallback( void * inContext, // context from IOHIDDeviceSetReportWithCallback IOReturn inResult, // completion result for the set value operation void * inSender, // IOHIDDeviceRef of the device this report is from IOHIDReportType inIOHIDReportType, // the report type uint32_t inReportID, // the report ID uint8_t* inReport, // the address of the report CFIndex inReportLength) // the length of the report { printf("%s(context: %p, result: %p, sender: %p, " \ "type: %d, id: %d, report: %p, length: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, inIOHIDReportType, inReportID, inReport, inReportLength); } // Handle_IOHIDDeviceSetReportCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. To request a report from a HID device, you should use the IOHIDDeviceGetReport (synchronous) or IOHIDDeviceGetReportWithCallback (asynchronous) functions as shown below: Listing 2-28 IOHIDDeviceGetReport and IOHIDDeviceGetReportWithCallback // synchronous IOReturn tIOReturn = IOHIDDeviceGetReport( deviceRef, // IOHIDDeviceRef for the HID device tIOHIDReportType, // IOHIDReportType for the report reportID, // CFIndex for the report ID report, // address of report buffer &reportSize); // address of length of the report // asynchronous IOReturn tIOReturn = IOHIDDeviceGetReportWithCallback( deviceRef, // IOHIDDeviceRef for the HID device tIOHIDReportType, // IOHIDReportType for the report reportID, // CFIndex for the report ID report, // address of report buffer &reportSize, // address of length of the report tCFTimeInterval, // timeout duration Handle_IOHIDDeviceGetReportCallback, // the callback routine context); // context passed to callback For both of these functions, the first parameter is a HID device reference. The second is an IOHIDReportType for the report. The third parameter is the report ID. The fourth parameter is the address of the report buffer. The fifth parameter should be the address of a CFIndex variable. Initially, you should set the value of this CFIndex variable to be the size of the report you are requesting. On return, the new value in that variable is the size of the returned report. For the asynchronous version, the sixth parameter is a timeout, the seventh parameter is a callback routine, and the last parameter is a context pointer that is passed to the callback routine. Listing 2-29 HID device get report callback routine static void Handle_IOHIDDeviceGetReportCallback( void * inContext, // context from IOHIDDeviceGetReportWithCallback IOReturn inResult, // completion result for the get report operation void * inSender, // IOHIDDeviceRef of the device this report is from IOHIDReportType inIOHIDReportType, // the report type uint32_t inReportID, // the report ID uint8_t* inReport, // the address of the report CFIndex inReportLength) // the length of the report { printf("%s(context: %p, result: %p, sender: %p, " \ "type: %d, id: %d, report: %p, length: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender, inIOHIDReportType, inReportID, inReport, inReportLength); } // Handle_IOHIDDeviceGetReportCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Working With HID Elements A CFTypeRef can be verified to be a HID element reference by comparing its Core Foundation type against IOHIDElementGetTypeID: Listing 2-30 Validating a HID element reference if (CFGetTypeID(tCFTypeRef) == IOHIDElementGetTypeID()) { // this is a valid HID element reference } Once a valid HID element reference is available, the IOHIDElementGetProperty function may be used to access its properties (type, usage page and usage, and so on) using the HID element keys defined in : Listing 2-31 HID element keys From : #define kIOHIDElementCookieKey "ElementCookie" #define kIOHIDElementTypeKey "Type" #define kIOHIDElementCollectionTypeKey "CollectionType" #define kIOHIDElementUsageKey "Usage" #define kIOHIDElementUsagePageKey "UsagePage" #define kIOHIDElementMinKey "Min" #define kIOHIDElementMaxKey "Max" #define kIOHIDElementScaledMinKey "ScaledMin" #define kIOHIDElementScaledMaxKey "ScaledMax" #define kIOHIDElementSizeKey "Size" #define kIOHIDElementReportSizeKey "ReportSize" #define kIOHIDElementReportCountKey "ReportCount" #define kIOHIDElementReportIDKey "ReportID" #define kIOHIDElementIsArrayKey "IsArray" #define kIOHIDElementIsRelativeKey "IsRelative" #define kIOHIDElementIsWrappingKey "IsWrapping" #define kIOHIDElementIsNonLinearKey "IsNonLinear" #define kIOHIDElementHasPreferredStateKey "HasPreferredState" #define kIOHIDElementHasNullStateKey "HasNullState" #define kIOHIDElementFlagsKey "Flags" #define kIOHIDElementUnitKey "Unit" #define kIOHIDElementUnitExponentKey "UnitExponent" #define kIOHIDElementNameKey "Name" #define kIOHIDElementValueLocationKey "ValueLocation" #define kIOHIDElementDuplicateIndexKey "DuplicateIndex" #define kIOHIDElementParentCollectionKey "ParentCollection" #define kIOHIDElementVendorSpecificKey "VendorSpecific" #define kIOHIDElementCalibrationMinKey "CalibrationMin" #define kIOHIDElementCalibrationMaxKey "CalibrationMax" #define kIOHIDElementCalibrationSaturationMinKey "CalibrationSaturationMin" #define kIOHIDElementCalibrationSaturationMaxKey "CalibrationSaturationMax" #define kIOHIDElementCalibrationDeadZoneMinKey "CalibrationDeadZoneMin" #define kIOHIDElementCalibrationDeadZoneMaxKey "CalibrationDeadZoneMax" #define kIOHIDElementCalibrationGranularityKey "CalibrationGranularity" Note: Use the CFSTR macro to pass these keys to the get/set property functions as CFStringRef pointers. Important: Convenience functions have been provided to allow developers to access many of these properties directly without having to use intermediary Core Foundation types. See Listing 2-34 for more information. Due to an unintentional implementation detail (bug) these element properties may or may not be accessible via the IOHIDElementGetProperty and IOHIDElementSetProperty functions. Please use the convenience APIs to access these properties. All the kIOHIDElementCalibration***Key properties are accessible via the IOHIDElementGetProperty and IOHIDElementSetProperty functions. Listing 2-32 Passing HID element keys to the Get/Set Property functions IOHIDElementGetProperty(element, CFSTR(kIOHIDElementTypeKey), &tCFNumberRef); Here are two functions that can be used to get or set long properties: Listing 2-33 Examples of how to get or set long HID element properties static Boolean IOHIDElement_GetLongProperty( IOHIDElementRef inElementRef, // the HID element CFStringRef inKey, // the kIOHIDElement key (as a CFString) long * outValue) // address where to return the output value { Boolean result = FALSE; CFTypeRef tCFTypeRef = IOHIDElementGetProperty(inElementRef, inKey); if (tCFTypeRef) { // if this is a number if (CFNumberGetTypeID() == CFGetTypeID(tCFTypeRef)) { // get its value result = CFNumberGetValue((CFNumberRef) tCFTypeRef, kCFNumberSInt32Type, outValue); } } return result; } static void IOHIDElement_SetLongProperty( IOHIDElementRef inElementRef, // the HID element CFStringRef inKey, // the kIOHIDElement key (as a CFString) long inValue) // the long value to be set { CFNumberRef tCFNumberRef = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &inValue); if (tCFNumberRef) { IOHIDElementSetProperty(inElementRef, inKey, tCFNumberRef); CFRelease(tCFNumberRef); } } // access the kIOHIDElementVendorSpecificKey if it exists: long longValue; if (IOHIDElement_GetLongProperty(elementRef, CFSTR(kIOHIDElementVendorSpecificKey), &longValue)) { printf("Element 0x%08lX has a vendor specific key of value 0x%08lX.\n", elementRef, longValue); } There are convenience functions to retrieve many of these element properties directly: Listing 2-34 HID element property functions // IOHIDElementCookie represent a unique identifier for a HID element within a HID device. IOHIDElementCookie cookie = IOHIDElementGetCookie(elementRef); // return the collection type: // kIOHIDElementTypeInput_Misc = 1, // kIOHIDElementTypeInput_Button = 2, // kIOHIDElementTypeInput_Axis = 3, // kIOHIDElementTypeInput_ScanCodes = 4, // kIOHIDElementTypeOutput = 129, // kIOHIDElementTypeFeature = 257, // kIOHIDElementTypeCollection = 513 IOHIDElementType tType = IOHIDElementGetType(elementRef); // If the HID element type is of type kIOHIDElementTypeCollection then // the collection type is one of: // kIOHIDElementCollectionTypePhysical = 0x00, // kIOHIDElementCollectionTypeApplication = 0x01, // kIOHIDElementCollectionTypeLogical = 0x02, // kIOHIDElementCollectionTypeReport = 0x03, // kIOHIDElementCollectionTypeNamedArray = 0x04, // kIOHIDElementCollectionTypeUsageSwitch = 0x05, // kIOHIDElementCollectionTypeUsageModifier = 0x06 IOHIDElementCollectionType collectionType = IOHIDElementGetCollectionType(elementRef); // usage and usage pages are defined on the USB website at: uint32_t page = IOHIDElementGetUsagePage(elementRef); uint32_t usage = IOHIDElementGetUsage(elementRef); // Boolean properties Boolean isVirtual = IOHIDElementIsVirtual(elementRef); Boolean isRelative = IOHIDElementIsRelative(elementRef); Boolean isWrapping = IOHIDElementIsWrapping(elementRef); Boolean isArray = IOHIDElementIsArray(elementRef); Boolean isNonLinear = IOHIDElementIsNonLinear(elementRef); Boolean hasPreferred = IOHIDElementHasPreferredState(elementRef); Boolean hasNullState = IOHIDElementHasNullState(elementRef); // the HID element name CFStringRef name = IOHIDElementGetName(elementRef); // element report information uint32_t reportID = IOHIDElementGetReportID(elementRef); uint32_t reportSize = IOHIDElementGetReportSize(elementRef); uint32_t reportCount = IOHIDElementGetReportCount(elementRef); // element unit & exponent uint32_t unit = IOHIDElementGetUnit(elementRef); uint32_t unitExp = IOHIDElementGetUnitExponent(elementRef); // logical & physical minimums & maximums CFIndex logicalMin = IOHIDElementGetLogicalMin(elementRef); CFIndex logicalMax = IOHIDElementGetLogicalMax(elementRef); CFIndex physicalMin = IOHIDElementGetPhysicalMin(elementRef); CFIndex physicalMax = IOHIDElementGetPhysicalMax(elementRef); There are also functions to determine the device, parent, and child of a specified HID element: Listing 2-35 HID element hierarchy functions // return the HID device that a element belongs to IOHIDDeviceRef deviceRef = IOHIDElementGetDevice(elementRef); // return the collection element that a HID element belongs to (if any) IOHIDElementRef elementRef = IOHIDElementGetParent(elementRef); // return the child elements of a collection element (if any) CFArrayRef tCFArrayRef = IOHIDElementGetChildren(elementRef); HID Queue Functions While developers can use the IOHIDDeviceGetValue to get the most recent value of a HID element, for some elements this is not sufficient. If it is necessary to keep track of all value changes of a HID element, rather than just the most recent one, developers can create a queue and add the HID elements of interest to it. After doing so, all value change events involving those elements are captured by the HID queue (up to the depth of the HID queue). HID queue references (IOHIDQueueRef objects) are used to communicate with the HID queues. They are created by using the IOHIDQueueCreate function: // Create HID queue reference IOHIDQueueRef IOHIDQueueCreate( CFAllocatorRef inCFAllocatorRef, // Allocator to be used during creation IOHIDDeviceRef inIOHIDDeviceRef, // the HID device to be associated with this queue CFIndex inDepth, // the maximum number of values to queue IOOptionBits inOptions) // options (currently reserved) The first parameter is a CFAllocatorRef object to be used when allocating the returned IOHIDQueueRef. The second parameter is the HID device to be associated with this queue. The third parameter is the maximum depth of the HID queue. The last parameter (options) is currently reserved for future use. Developers should pass kIOHIDOptionsTypeNone (zero) for this parameter. There is no IOHIDQueueDestroy (or release, free, and so on). Because the HID queue reference is a Core Foundation object reference, CFRelease should be used to dispose of it. A CFTypeRef can be verified to be a HID queue reference by comparing its Core Foundation type against IOHIDQueueGetTypeID: Listing 2-36 Validating a HID queue reference if (CFGetTypeID(tCFTypeRef) == IOHIDQueueGetTypeID()) { // this is a valid HID queue reference! } Once a HID queue reference has been created, it has to be started before it can be used to access the HID devices associated with it. void IOHIDQueueStart(IOHIDQueueRef inIOHIDQueueRef); The corresponding function to stop a HID queue is: void IOHIDQueueStop(IOHIDQueueRef inIOHIDQueueRef); Note: HID queues have to be stopped before HID elements can be added or removed. Also HID elements can only be added to the HID queue for their device. You can't use a single HID queue for multiple devices. To determine the HID device associated with a specific HID queue use the IOHIDQueueGetDevice function: IOHIDDeviceRef IOHIDQueueGetDevice(IOHIDQueueRef inIOHIDQueueRef); There are accessor function to get and set the HID queue's depth: CFIndex IOHIDQueueGetDepth(IOHIDQueueRef inIOHIDQueueRef); void IOHIDQueueSetDepth(IOHIDQueueRef inIOHIDQueueRef, CFIndex inDepth); HID elements can be added and removed by using these functions: void IOHIDQueueAddElement(IOHIDQueueRef inIOHIDQueueRef, IOHIDElementRef inIOHIDElementRef); void IOHIDQueueRemoveElement(IOHIDQueueRef inIOHIDQueueRef, IOHIDElementRef inIOHIDElementRef); To determine if a HID element has been added to a HID queue use this function: Boolean IOHIDQueueContainsElement(IOHIDQueueRef inIOHIDQueueRef, IOHIDElementRef inIOHIDElementRef); Once a HID queue has been created, HID elements have been added, and the queue has been started, HID values can then be dequeued with one of these functions: IOHIDValueRef IOHIDQueueCopyNextValue(IOHIDQueueRef inIOHIDQueueRef); IOHIDValueRef IOHIDQueueCopyNextValueWithTimeout(IOHIDQueueRef inIOHIDQueueRef, CFTimeInterval inTimeout); Note: The first function is synchronous and will block until there is a HID value available. While this may be desirable when called from a secondary thread blocking as the main thread should always be avoided. So on the main thread developers will most likely want to use the the second function with a zero timeout. This is essentially a method for polling the HID queue without blocking. Note: Because the HID value is a retained copy, it is up to the caller to release the HID value (using CFRelease). Note: HID values are documented in the “HID Value Functions” section. To avoid polling the HID queue for HID value changes developers can instead register a callback routine: void IOHIDQueueRegisterValueAvailableCallback( IOHIDQueueRef inIOHIDQueueRef, // reference to the HID queue IOHIDCallback inCallback, // address of the callback routine void * inContext); // context passed to callback Note: The HID queue must be scheduled with a run loop for this callback routine to be dispatched. The functions to schedule and unschedule a HID queue from a run loop are: // Schedule a HID queue with a runloop void IOHIDQueueScheduleWithRunLoop(IOHIDQueueRef inIOHIDQueueRef, // reference to the HID queue CFRunLoopRef inRunLoop, // Run loop to be scheduled with CFStringRef inRunLoopMode); // Run loop mode for scheduling // Unschedule a HID queue from a runloop void IOHIDQueueUnscheduleFromRunLoop( IOHIDQueueRef inIOHIDQueueRef, // reference to the HID queue CFRunLoopRef inRunLoop, // Run loop to be unscheduling from CFStringRef inRunLoopMode); // Run loop mode for unscheduling Listing 2-37 Scheduling a HID queue with a run loop IOHIDQueueScheduleWithRunLoop(inIOHIDQueueRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode); Listing 2-38 HID queue value available callback routine static void Handle_ValueAvailableCallback( void * inContext, // context from IOHIDQueueRegisterValueAvailableCallback IOReturn inResult, // the inResult void * inSender, // IOHIDQueueRef of the queue ) { printf("%s(context: %p, result: %p, sender: %p).\n", __PRETTY_FUNCTION__, inContext, (void *) inResult, inSender); do { IOHIDValueRef valueRef = IOHIDQueueCopyNextValueWithTimeout((IOHIDQueueRef) inSender, 0.); if (!valueRef) break; // process the HID value reference . . . CFRelease(valueRef); // Don't forget to release our HID value reference } while (1) ; } // Handle_ValueAvailableCallback The inResult callback parameter contains the error result of the operation that is calling the callback. You should check the return value, and if it is nonzero, handle the failure accordingly. Note: This routine is not called every time a new value is added to a queue; It is only called when the HID queue transitions to non-empty. For this reason the HID queue should be emptied (by calling IOHIDQueueCopyNextValueWithTimeout until it returns NULL) before expecting this routine to be called again. Note: HID values are documented in the “HID Value Functions” section. HID Transaction Functions Lower-level APIs such as IOHIDDeviceGetReport, IOHIDDeviceGetReportWithCallback, IOHIDDeviceSetReport, and IOHIDDeviceSetReportWithCallback require you to know how HID device descriptors are used in order to define the reports sent to and received from HID devices. See Listing 2-28 and Listing 2-26 for more information about these functions. HID transactions are an abstraction layered on top of these lower-level APIs. HID transactions allow you to assemble a transaction, add the relevant values, set default values, and commit the transaction (which forces a report to be sent across the USB bus). To build a transaction, you first must create a HID transaction reference by calling the IOHIDTransactionCreate function: IOHIDTransactionRef IOHIDTransactionCreate( CFAllocatorRef inCFAllocatorRef, // Allocator to be used during creation IOHIDDeviceRef inIOHIDDeviceRef, // the HID device for this transaction IOHIDTransactionDirectionType inDirection, // The direction: in or out IOOptionBits inOptions); // options (currently reserved) The first parameter is a CFAllocatorRef allocator to be used when allocating the returned IOHIDTransactionRef object. The second parameter is the HID device to be associated with this transaction. The third parameter is the direction for the transfer (kIOHIDTransactionDirectionTypeInput or kIOHIDTransactionDirectionTypeOutput). The last parameter (options) is currently reserved for future use. Developers should pass kIOHIDOptionsTypeNone (zero) for this parameter. Note: HID transaction references can be used to send and receive multiple element values. The direction used should represent the type of HID elements that you are adding to the transaction. There is no IOHIDTransactionDestroy (or release, free, and so on). Because the HID transaction reference is a Core Foundation object reference, you should call CFRelease to dispose of it. A CFTypeRef object can be verified to be a HID transaction reference by comparing its Core Foundation type against the return value of the IOHIDTransactionGetTypeID function: Listing 2-39 Validating a HID transaction reference if (CFGetTypeID(tCFTypeRef) == IOHIDTransactionGetTypeID()) { // this is a valid HID transaction reference! } There are convenience functions to get the HID device associated with a HID transaction and to get or set the direction for a HID transaction: // Obtain the HID device associated with a transaction IOHIDDeviceRef IOHIDTransactionGetDevice( IOHIDTransactionRef inIOHIDTransactionRef); // HID transaction reference // Obtain the direction of the transaction. IOHIDTransactionDirectionType IOHIDTransactionGetDirection( IOHIDTransactionRef IOHIDTransactionRef); // HID transaction reference // Sets the direction of the transaction void IOHIDTransactionSetDirection(IOHIDTransactionRef IOHIDTransactionRef, // HID transaction reference IOHIDTransactionDirectionType direction); // The direction: in or out Note: The IOHIDTransactionSetDirection function is useful for manipulating bi-direction (feature) elements such that you can set or get element values without having to create an additional transaction object. Once a HID transaction has been created then the HID elements associated with it may be added by using the IOHIDTransactionAddElement function: void IOHIDTransactionAddElement( IOHIDTransactionRef inIOHIDTransactionRef, // HID transaction reference IOHIDElementRef inIOHIDElementRef); // the HID element to associate with this transaction Important: To minimize device traffic, you should only add HID elements that share a common report type and id. HID Elements may be removed from a HID transaction by using the IOHIDTransactionRemoveElement function: void IOHIDTransactionRemoveElement( IOHIDTransactionRef inIOHIDTransactionRef, // HID transaction reference IOHIDElementRef inIOHIDElementRef); // the HID element to associate with this transaction To determine if a HID element is currently associated with a HID transaction the IOHIDTransactionContainsElement function may be used: // Queries the transaction to determine if elemement has been added. Boolean IOHIDTransactionContainsElement( IOHIDTransactionRef inIOHIDTransactionRef, // HID transaction reference IOHIDElementRef inIOHIDElementRef); // the HID element to test for To set the HID values associated with the HID elements in a HID transaction use the IOHIDTransactionSetValue functions: void IOHIDTransactionSetValue(IOHIDTransactionRef inIOHIDTransactionRef, // HID transaction reference IOHIDElementRef inIOHIDElementRef, // the HID element IOHIDValueRef inIOHIDValueRef, // the HID element value IOOptionBits inOptions); // options The HID value set is pended until the transaction is committed. This value is only used if the transaction direction is kIOHIDTransactionDirectionTypeOutput. Use the kIOHIDTransactionOptionDefaultOutputValue option to set the default element values for transactions. To retrieve the HID values associated with the HID elements in a HID transaction, developers may use the IOHIDTransactionGetValue function: // Obtains the HID value for a transaction element. IOHIDValueRef IOHIDTransactionGetValue( IOHIDTransactionRef inIOHIDTransactionRef, // HID transaction reference IOHIDElementRef inIOHIDElementRef, // the HID element IOOptionBits inOptions); // options If the HID transaction direction is kIOHIDTransactionDirectionTypeInput the HID value represents what was obtained from the HID device from the HID transaction. Otherwise, if the transaction direction is kIOHIDTransactionDirectionTypeOutput the HID value represents the pending value to be sent to the HID device. Use the kIOHIDTransactionOptionDefaultOutputValue option to get the default HID value associated with the HID elements of a HID transaction. The values for HID elements associated with a HID transaction can be reset to their default values by using the IOHIDTransactionClear function: // Clears element transaction values. void IOHIDTransactionClear(IOHIDTransactionRef inIOHIDTransactionRef); // HID transaction reference Once all the appropriate HID elements have been added to a HID transaction (and values set for output transactions) then in order to cause the actual bus transaction to occur they should be committed by using one of the two following functions: // Synchronously commits element transaction to the HID device. IOReturn IOHIDTransactionCommit(IOHIDTransactionRef inIOHIDTransactionRef); // HID transaction reference // Asynchronously commits element transaction to the HID device. IOReturn IOHIDTransactionCommitWithCallback( IOHIDTransactionRef inIOHIDTransactionRef, // HID transaction reference CFTimeInterval inTimeout, // timeout duration IOHIDCallback inCallback, // address of the callback routine void * inContext); // Pointer to be passed to the callback For both functions, the first parameter is the HID transaction reference to be committed. For the asynchronous function, the second parameter is a timeout, the third parameter is a callback routine (pass NULL if you want synchronous behavior with a timeout), and the last parameter is a context pointer that is passed to the callback routine. Note: If the direction is set to kIOHIDTransactionDirectionTypeOutput, default element values are used if per-transaction element values are not set. If neither a default value nor a per-transaction value is set, that element is omitted from the commit. After a transaction is committed, the per-transaction element values are cleared, but the default values are preserved. Note: It is possible for elements from different reports to be present in a given transaction, causing a commit to transcend multiple reports. Keep this in mind when setting a appropriate timeout. Note: The HID transaction must be scheduled with a run loop In order for the callback routine to be dispatched. The functions to schedule and unschedule a HID transaction from a run loop are: // Schedule a HID transaction with a runloop void IOHIDTransactionScheduleWithRunLoop( IOHIDTransactionRef inIOHIDTransactionRef, // reference to the HID transaction CFRunLoopRef inRunLoop, // Run loop to be scheduled with CFStringRef inRunLoopMode); // Run loop mode for scheduling // Unschedule a HID transaction from a runloop void IOHIDTransactionUnscheduleFromRunLoop( IOHIDTransactionRef inIOHIDTransactionRef, // reference to the HID transaction CFRunLoopRef inRunLoop, // Run loop to be unscheduling from CFStringRef inRunLoopMode); // Run loop mode for unscheduling Listing 2-40 Scheduling a HID transaction with a run loop IOHIDTransactionScheduleWithRunLoop(inIOHIDTransactionRef, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode); HID Value Functions HID value references are used by the HID Manager and HID device input value callbacks, the HID device get and set value functions and callbacks, and the HID queue copy value functions (with or without timeout). Three functions are available for creating HID value references: IOHIDValueRef IOHIDValueCreateWithIntegerValue( CFAllocatorRef inCFAllocatorRef, // Allocator to be used during creation IOHIDElementRef inIOHIDElementRef, // the HID element to be associated with this value uint64_t inTimeStamp, // OS AbsoluteTime CFIndex inValue); // the integer (32-bit) value used to create this HID value IOHIDValueRef IOHIDValueCreateWithBytes( CFAllocatorRef inCFAllocatorRef, // Allocator to be used during creation IOHIDElementRef inIOHIDElementRef, // the HID element to be associated with this value uint64_t inTimeStamp, // OS AbsoluteTime const uint8_t * inBytes, // a pointer to the data used to create this HID value CFIndex inLength); // the length of the data used to create this HID value IOHIDValueRef IOHIDValueCreateWithBytesNoCopy( CFAllocatorRef inCFAllocatorRef, // Allocator to be used during creation IOHIDElementRef inIOHIDElementRef, // the HID element to be associated with this value uint64_t inTimeStamp, // OS AbsoluteTime const uint8_t * inBytes, // a pointer to the data used to create this HID value CFIndex inLength); // the length of the data used to create this HID value For all three of these functions the first parameter is a CFAllocatorRef object to be used when allocating the returned IOHIDValueRef. The second parameter is the HID element to be associated with this value. The third parameter is a time stamp. For the IOHIDValueCreateWithIntegerValue function, the last parameter is a CFIndex value. For the last two functions, the fourth parameter is a pointer to the data, and the last parameter is the length of the data. Note: For all three of these functions the timeStamp value should represent an OS AbsoluteTime value, not a CFAbsoluteTime value. See for details. Note: For the IOHIDValueCreateWithBytesNoCopy function the data is expected to exist until the HID value reference is released. Any attempt to access the data after it has been released may result in a crash. A CFTypeRef can be verified to be a HID value reference by comparing its Core Foundation type against IOHIDValueGetTypeID: Listing 2-41 Validating a HID value reference if (CFGetTypeID(tCFTypeRef) == IOHIDValueGetTypeID()) { // this is a valid HID value reference! } Convenience functions are provided to access the HID element, time stamp, and integer values associated with HID value objects: // Returns the HID element value associated with this HID value reference. IOHIDElementRef IOHIDValueGetElement(IOHIDValueRef inIOHIDValueRef); // Returns the timestamp value associated with this HID value reference. uint64_t IOHIDValueGetTimeStamp(IOHIDValueRef inIOHIDValueRef); // Returns an integer representation for this HID value reference. CFIndex IOHIDValueGetIntegerValue(IOHIDValueRef inIOHIDValueRef); Additional functions are provided to access the data and the length of the data associated with a HID value object: // Returns the size, in bytes, of the data associated with this HID value reference. CFIndex IOHIDValueGetLength(IOHIDValueRef inIOHIDValueRef); // Returns a byte pointer to the data associated with this HID value reference. const uint8_t * IOHIDValueGetBytePtr(IOHIDValueRef inIOHIDValueRef) One additional function exists to return a scaled representation of a HID value object: // return the scaled value of a HID value reference double_t IOHIDValueGetScaledValue(IOHIDValueRef inIOHIDValueRef, IOHIDValueScaleType inType); There are currently two types of scaling that can be applied: * kIOHIDValueScaleTypePhysical: Scales values using the physical bounds of the HID element. * kIOHIDValueScaleTypeCalibrated: Scales values using the calibration properties of the HID element. Note: Currently there are no calibration properties associated with HID elements by default. Developers are expected to set the appropriate calibration properties for all elements that they want to scale using the IOHIDValueGetScaledValue function with the kIOHIDValueScaleTypeCalibrated scale type. The first two HID element calibration properties define the desired range of the returned scaled value: kIOHIDElementCalibrationMinKey The minimum bounds for a calibrated value (default = -1). kIOHIDElementCalibrationMaxKey The maximum bounds for a calibrated value (default = +1). For example, the actual raw range of a HID element might go from 0-255, but the developer might want the scaled value to be returned with a range of -32.0 to +32.0. In this example, the min and max calibration values would be set to -32.0 and +32.0, respectively. The next two HID element calibration properties define the range of expected values: kIOHIDElementCalibrationSaturationMinKey The minimum value to be used when calibrating a HID value. kIOHIDElementCalibrationSaturationMaxKey The maximum value to be used when calibrating a HID value. Some HID devices may have elements that can’t return the full range of values defined by their logical min and max value limits. For example, the logical values for an element might be defined as ranging from 0 to 255, but the actual device may actually only be able to return values in the range of 5 to 250. This may be caused by digitization errors, mechanical limits on an encoder, and so on. If these calibration properties are set, then logical values within this range are scaled out to the full logical range for the HID device. In this example, the min and max saturation values would be set to 5 and 250, respectively. The next two HID element calibration properties define the range of a dead zone (if it exists): kIOHIDElementCalibrationDeadZoneMinKey The minimum bounds near the midpoint where values are ignored. kIOHIDElementCalibrationDeadZoneMaxKey The maximum bounds near the midpoint where values are ignored. Some HID devices (such as joysticks) have elements that have a mechanical return-to-center feature. Because of mechanical slop, drift, or digitization noise, these elements may not always return the exact same values when the HID element is returned to the center position. For example, an element with a logical range of 0 to 255 might return center values ranging from 124 to 130. If these dead zone properties are set (to 124 and 130, in this case), then any value between these two numbers is returned as the center scaled value (127 in this case). The last HID element calibration property defines a granularity: kIOHIDElementCalibrationGranularityKey The scale or level of detail returned in a calibrated element value. For example, if the granularity property is set to 0.1, the returned values after calibration are exact multiples of 0.1: { 0.0, 0.1, 0.2, 0.3, 0.4, etc. }. Listing 2-42 Setting HID element calibration properties static void IOHIDElement_SetDoubleProperty( IOHIDElementRef inElementRef, // the HID element CFStringRef inKey, // the kIOHIDElement key (as a CFString) double inValue) // the double value to be set { CFNumberRef tCFNumberRef = CFNumberCreate(kCFAllocatorDefault, kCFNumberDoubleType, &inValue); if (tCFNumberRef) { IOHIDElementSetProperty(inElementRef, inKey, tCFNumberRef); CFRelease(tCFNumberRef); } } // These define the range of the returned scaled values IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationMinKey), -32.); IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationMaxKey), +32.); // these define the range of values expected from the device (logical values) IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationSaturationMinKey), 5.); IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationSaturationMaxKey), 250.); // these define the range of the dead zone (logical values) IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationDeadZoneMinKey), 124.); IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationDeadZoneMaxKey), 130.); // this defines the granularity of the returned scaled values IOHIDElement_SetDoubleProperty(elementRef, CFSTR(kIOHIDElementCalibrationGranularityKey), 0.1); Listing 2-43 Pseudo code for the IOHIDValueGetScaledValue function // first a convenience function to access HID element properties stored as doubles: static Boolean IOHIDElement_GetDoubleProperty( IOHIDElementRef inElementRef, // the HID element CFStringRef inKey, // the kIOHIDElement key (as a CFString) double * outValue) // address where to return the output value { Boolean result = FALSE; CFTypeRef tCFTypeRef = IOHIDElementGetProperty(inElementRef, inKey); if (tCFTypeRef) { // if this is a number if (CFNumberGetTypeID() == CFGetTypeID(tCFTypeRef)) { // get its value result = CFNumberGetValue((CFNumberRef) tCFTypeRef, kCFNumberDoubleType, outValue); } } return result; } double_t IOHIDValueGetScaledValue(IOHIDValueRef inValue, IOHIDValueScaleType inType) { IOHIDElementRef element = IOHIDValueGetElement(inValue); double_t logicalValue = IOHIDValueGetIntegerValue(inValue); double_t logicalMin = IOHIDElementGetLogicalMin(element); double_t logicalMax = IOHIDElementGetLogicalMax(element); double_t scaledMin = 0; double_t scaledMax = 0; double_t granularity = 0.; double_t returnValue = 0.; switch (inType) { case kIOHIDValueScaleTypeCalibrated: { double_t calibrateMin = 0.; (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationMinKey), &calibrateMin); double_t calibrateMax = 0.; (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationMaxKey), &calibrateMax); // if there are calibration min/max values... if (calibrateMin != calibrateMax) { // ...use them... scaledMin = calibrateMin; scaledMax = calibrateMax; } else { // ...otherwise use +/- 1.0 scaledMin = -1.; scaledMax = +1.; } double_t saturationMin = 0.; (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationSaturationMinKey), &saturationMin); double_t saturationMax = 0.; (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationSaturationMaxKey), &saturationMax); // if there are saturation min/max values... if (saturationMin != saturationMax) { // .. and the logical value is less than the minimum saturated value... if (logicalValue <= saturationMin) { // ...then return the minimum scaled value return scaledMin; } else // otherwise if the logical value is greater than the maximum saturated value... if (logicalValue >= saturationMax) { // ...return the maximum scaled value. return scaledMax; } else // otherwise use the min/max saturated values for the logical min/max { logicalMin = saturationMin; logicalMax = saturationMax; } } double_t deadzoneMin = 0.; (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationDeadZoneMinKey), &deadzoneMin); double_t deadzoneMax = 0.; (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationDeadZoneMaxKey), &deadzoneMax); // if there are deadzone min/max values... if (deadzoneMin != deadzoneMax) { double_t scaledMid = (scaledMin + scaledMax) / 2.; // if the logical value is less than the deadzone min... if (logicalValue < deadzoneMin) { // ...then use the deadzone min as our logical max... logicalMax = deadzoneMin; // ...and the middle of our scaled range as our scaled max. scaledMax = scaledMid; } // otherwise if the logical value is greater than the deadzone max... else if (logicalValue > deadzoneMax) { // ...then use the deadzone max as our logical min... logicalMin = deadzoneMax; // ...and the middle of our scaled range as our scaled min. scaledMin = scaledMid; } else { // otherwise return the middle of our scaled range return scaledMid; } } (void) IOHIDElement_GetDoubleProperty(element, CFSTR(kIOHIDElementCalibrationGranularityKey), &granularity); break; } case kIOHIDValueScaleTypePhysical: { scaledMin = IOHIDElementGetPhysicalMin(element); scaledMax = IOHIDElementGetPhysicalMax(element); break; } default: { return returnValue; // should be 0.0 } } double_t logicalRange = logicalMax - logicalMin; double_t scaledRange = scaledMax - scaledMin; returnValue = ((logicalValue - logicalMin) * scaledRange / logicalRange) + scaledMin; if (granularity) { returnValue = round(returnValue / granularity) * granularity; } return returnValue; } NextPrevious ______________________________________________________________________________________________________________________ Copyright © 2001, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-10-19 Feedback Sending feedback… We’re sorry, an error has occurred. Please try submitting your feedback later. Thank you for providing feedback! Your input helps improve our developer documentation. How helpful is this document? ^* (*) Very helpful ( ) Somewhat helpful ( ) Not helpful How can we improve this document? [ ] Fix typos or links [ ] Fix incorrect information [ ] Add or update code samples [ ] Add or update illustrations [ ] Add information about... ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ^* ________________________________________________ * Required information [BUTTON Input] (not implemented)____ To submit a product bug or enhancement request, please visit the Bug Reporter page. Please read Apple's Unsolicited Idea Submission Policy before you send us your feedback.