Mac Developer Library

Developer

IOHIDDescriptorParser.h Reference

Options
Deployment Target:

On This Page

IOHIDDescriptorParser.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Included Headers

  • <TargetConditionals.h>

  • <IOKit/IOTypes.h>

  • <IOKit/hidsystem/IOHIDUsageTables.h>

Functions

  • Disposes of the memory the parser allocated for the HIDOpenReportDescriptor function.

    Declaration

    Objective-C

    OSStatus HIDCloseReportDescriptor ( HIDPreparsedDataRef preparsedDataRef );

    Parameters

    hidReportDescriptor

    Contains a pointer to the actual HID report descriptor from the USB device's firmware

    preparsedDataRef

    Preparsed data reference for the report that is returned by the HIDOpenReportDescriptor function. After making a call to the HIDCloseReportDescriptor function, the preparsedDataRef is invalid and should not be used.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Returns the button capabilities structures for a HID device based on the given preparsed data.

    Declaration

    Objective-C

    OSStatus HIDGetButtonCapabilities ( HIDReportType reportType, HIDButtonCapabilitiesPtr buttonCaps, UInt32 *buttonCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport

    buttonCaps

    Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCapabilities structures. The structures contain information for all buttons that meet the search criteria

    buttonCapsSize

    Contains the size of the buttonCaps array passed in to the function and is set to the number of elements actually placed in the array after the call completes.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Returns the button capabilities structures for a HID device based on the given preparsed data.

    Declaration

    Objective-C

    OSStatus HIDGetButtonCaps ( HIDReportType reportType, HIDButtonCapsPtr buttonCaps, UInt32 *buttonCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport

    buttonCaps

    Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCaps structures. The structures contain information for all buttons that meet the search criteria

    buttonCapsSize

    Contains the size of the buttonCaps array passed in to the function and is set to the number of elements actually placed in the array after the call completes.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDGetButtons function takes a report from a HID device and gets the current state of the buttons in that report.

    Declaration

    Objective-C

    OSStatus HIDGetButtons ( HIDReportType reportType, UInt32 collection, HIDUsageAndPagePtr usageList, UInt32 *usageListSize, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report, provided in the report parameter, from which to retrieve the buttons. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport

    collection

    Optionally specifies the link collection identifier used to retrieve only specific button states. If this value is non-zero, only the buttons that are part of the given collection are returned.

    usageList

    On return, points to a caller-allocated buffer that contains the usages of all the buttons that are pressed.

    usageListSize

    Is the size, in array elements, of the buffer provided in the usageList parameter. On return, this parameter contains the number of button states that were set by this routine. If the error kHIDBufferToSmallErr was returned, this parameter contains the number of array elements required to hold all button data requested. The maximum number of buttons that can ever be returned for a given type of report can be obtained by calling the HIDMaxUsageListLength function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the length, in bytes, of the report data provided in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Retrieves the button stat information for buttons on a specified usage page.

    Declaration

    Objective-C

    OSStatus HIDGetButtonsOnPage ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage *usageList, UInt32 *usageListSize, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report, provided in the report parameter, from which to retrieve the buttons. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport.

    usagePage

    Specifies the usage page of the buttons for which to retrieve the current state.

    collection

    Optionally specifies the link collection identifier used to retrieve only specific button states. If this value is non-zero, only the buttons that are part of the given collection are returned.

    usageList

    On return, points to a caller-allocated buffer that contains the usages of all the buttons that are perssed and belong to the usage page specified in the usagePage parameter.

    usageListSize

    Is the size, in array elements, of the buffer provided in the usageList parameter. On return, this parameter contains the number of button states that were set by this routine. If the error kHIDBufferTooSmallErr was returned, this parameter contains the number of array elements required to hold all button data requested. The maximum number of buttons that can ever be returned for a given type of report can be obtained by calling the HIDMaxUsageListLength function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data

    reportLength

    Specifies the size, in bytes, of the report data provided in the report parameter

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Returns the capabilities of a HID device based on the given preparsed data.

    Declaration

    Objective-C

    OSStatus HIDGetCapabilities ( HIDPreparsedDataRef preparsedDataRef, HIDCapabilitiesPtr capabilities );

    Parameters

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    capabilities

    Points to a caller allocated buffer, that upon return contains the parsed capability information for this HID device.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Returns the capabilities of a HID device based on the given preparsed data.

    Declaration

    Objective-C

    OSStatus HIDGetCaps ( HIDPreparsedDataRef preparsedDataRef, HIDCapsPtr capabilities );

    Parameters

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    capabilities

    Points to a caller allocated buffer, that upon return contains the parsed capability information for this HID device.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Returns an array of HIDCollectionNode structures that describe the relationships and layout of the link collections within this top level collection.

    Declaration

    Objective-C

    OSStatus HIDGetCollectionNodes ( HIDCollectionNodePtr collectionNodes, UInt32 *collectionNodesSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    collectionNodes

    Points to a caller-allocated array of HIDCollectionNode structures in which this routine returns an entry for each collection within the top level collection. A collection is a group of corresponding HID descriptors containing input, output, and feature items that have some common relationship to one another. For example, a pointer collection contains items for x and y position data, and button data.

    collectionNodesSize

    On input, specifies the length in array elements of the buffer provided at collectionNodes. On output, this parameter is set to the number of entries in the collectionNodes array that were initialized.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The length of the buffer required, in array elements, for an entire collection node array is found in the HIDCaps structure member numberCollectionNodes. You obtain the HIDCaps information by calling the HIDGetCaps function. For information on the relationships of link collections described by the data returned from this routine, see the descripton of the HIDCollectionNode structure.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDGetScaledUsageValue function returns the capabilities for all buttons for a given top level collection.

    Declaration

    Objective-C

    OSStatus HIDGetScaledUsageValue ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, SInt32 *usageValue, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page of the value to be retrieved.

    collection

    Optionally specifies the link collection identifier of the value to be retrieved.

    usage

    Specifies the usage of the scaled value to be retrieved.

    usageValue

    Points to a variable, that on return from this routine holds the scaled value retrieved from the device report.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data

    reportLength

    Specifies the length, in bytes, of the report data provided at report

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    Clients who which to obtain all capabilities for a usage that contains multiple data items for a single usage that corresponds to a HID byte array, must call the HIDGetUsageValueArray function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Retrieves the capabilities for all buttons in a specific type of report that meet the search criteria.

    Declaration

    Objective-C

    OSStatus HIDGetSpecificButtonCapabilities ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, HIDButtonCapabilitiesPtr buttonCaps, UInt32 *buttonCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the button capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only buttons that specify this usage page will be retrieved.

    collection

    Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only buttons that are part of the specified link collection are retrieved.

    usage

    Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only buttons that match the value specified are retrieved.

    buttonCaps

    Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCapabilities structures. The structures contain information for all buttons that meet the search criteria.

    buttonCapsLength

    On input, specifies the length, in array elements, of the buffer provided in the buttonCaps parameter. On output, this parameter is set to the actual number of elements that were returned by the function call, in the buffer provided in the buttonCaps parameter, if the routine completed without error. The correct length necessary to retrieve the button capabilities can be found in the capability data returned for the device by the HIDGetCaps function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetSpecificButtonCapabilities function retrieves capability data for buttons that meet a given search criteria, as opposed to the HIDGetButtonCapabilities function which returns the capability data for all buttons on the device. Calling this routine specifying zero for usagePage, usage and collection is equivalent to calling the HIDGetButtonCapabilities function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Retrieves the capabilities for all buttons in a specific type of report that meet the search criteria.

    Declaration

    Objective-C

    OSStatus HIDGetSpecificButtonCaps ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, HIDButtonCapsPtr buttonCaps, UInt32 *buttonCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the button capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only buttons that specify this usage page will be retrieved.

    collection

    Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only buttons that are part of the specified link collection are retrieved.

    usage

    Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only buttons that match the value specified are retrieved.

    buttonCaps

    Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCaps structures. The structures contain information for all buttons that meet the search criteria.

    buttonCapsLength

    On input, specifies the length, in array elements, of the buffer provided in the buttonCaps parameter. On output, this parameter is set to the actual number of elements that were returned by the function call, in the buffer provided in the buttonCaps parameter, if the routine completed without error. The correct length necessary to retrieve the button capabilities can be found in the capability data returned for the device by the HIDGetCaps function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetSpecificButtonCaps function retrieves capability data for buttons that meet a given search criteria, as opposed to the HIDGetButtonCaps function which returns the capability data for all buttons on the device. Calling this routine specifying zero for usagePage, usage and collection is equivalent to calling the HIDGetButtonCaps function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Retrieves the capabilities for all values in a specific type of report that meet the search criteria.

    Declaration

    Objective-C

    OSStatus HIDGetSpecificValueCapabilities ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, HIDValueCapabilitiesPtr valueCaps, UInt32 *valueCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport.

    usagePage

    Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage page will be retrieved.

    collection

    Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only values that are part of this link collection will be retrieved.

    usage

    Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage will be retrieved.

    valueCaps

    Points to a caller-allocated buffer that will contain, on return, an array of HIDValueCapabilities structures that contain information for all values that meet the search criteria.

    valueCapsSize

    Specifies the length on input, in array elements, of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned by this function call, in the buffer provided in the valueCaps parameter, if the routine completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device from the HIDGetCaps function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetSpecificValueCapabilities function retrieves capability data for values that meet given search criteria, as opposed to the HIDGetValueCapabilities function, which returns the capability data for all values on the device. Calling this routine with a value of zero for usagePage, usage and collection parameters is equivalent to calling the HIDGetValueCapabilities function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • Retrieves the capabilities for all values in a specific type of report that meet the search criteria.

    Declaration

    Objective-C

    OSStatus HIDGetSpecificValueCaps ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, HIDValueCapsPtr valueCaps, UInt32 *valueCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport.

    usagePage

    Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage page will be retrieved.

    collection

    Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only values that are part of this link collection will be retrieved.

    usage

    Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage will be retrieved.

    valueCaps

    Points to a caller-allocated buffer that will contain, on return, an array of HIDValueCaps structures that contain information for all values that meet the search criteria.

    valueCapsSize

    Specifies the length on input, in array elements, of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned by this function call, in the buffer provided in the valueCaps parameter, if the routine completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device from the HIDGetCaps function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetSpecificValueCaps function retrieves capability data for values that meet given search criteria, as opposed to the HIDGetValueCaps function, which returns the capability data for all values on the device. Calling this routine with a value of zero for usagePage, usage and collection parameters is equivalent to calling the HIDGetValueCaps function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDGetUsageValue function returns a value from a device data report given a selected search criteria.

    Declaration

    Objective-C

    OSStatus HIDGetUsageValue ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, SInt32 *usageValue, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report, provided in report, from which to retrieve the value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page of the value to retrieve.

    collection

    Optionally specifies the link collection identifier of the value to be retrieved.

    usage

    Specifies the usage of the value to be retrieved.

    usageValue

    Points to a variable, that on return from this routine holds the value retrieved from the device report.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the size, in bytes, of the report data provided in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetUsageValue function does not sign the value. To have the sign bit automatically applied, use the HIDGetScaledUsageValue function instead. For manually assigning the sign bit, the position of the sign bit can be found in the HIDValueCaps structure for this value. Clients who wish to obtain all data for a usage that contains multiple data items for a single usage, corresponding to a HID byte array, must call the HIDGetUsageValueArray function instead.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDGetUsageValueArray function returns a value from a device data report given a selected search criteria.

    Declaration

    Objective-C

    OSStatus HIDGetUsageValueArray ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, UInt8 *usageValueBuffer, IOByteCount usageValueBufferSize, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report, provided in report, from which to retrieve the value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page of the data to be retrieved.

    collection

    Optionally specifies the link collection identifier of the data to be retrieved.

    usage

    Specifies the usage identifier of the value to be retrieved.

    usageValueBuffer

    Points to a caller-allocated buffer that contains, on output, the data from the device. The correct length for this buffer can be found by multiplying the reportCount and bitSize fields of the HIDValueCaps structure for the value and rounding the resulting value up to the nearest byte.

    usageValueBufferSize

    Specifies the size, in bytes, of the buffer in the usageValueBuffer parameter.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the size, in bytes, of the report data provided in report.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    When the HIDGetUsageValueArray function retrieves the data, it fills in the buffer in little-endian order beginning with the least significant bit of the data for this usage. The data is filled in without regard to byte alignment and is shifted such that the least significant bit is placed as the 1st bit of the given buffer.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDGetValueCapabilities function retrieves the capabilities for all values for a specified top level collection.

    Declaration

    Objective-C

    OSStatus HIDGetValueCapabilities ( HIDReportType reportType, HIDValueCapabilitiesPtr valueCaps, UInt32 *valueCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    valueCaps

    On return, points to a caller-allocated buffer that contains an array of HIDValueCapabilities structures containing information for all values in the top level collection.

    valueCapsSize

    On input, specifies the size in array elements of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned in the buffer provided in the valueCaps parameter, if the function completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device by the HIDGetCapabilities function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetValueCapabilities function retrieves the capability data for all values in a top level collection without regard for the usage, usage page or collection of the value. To retrieve value capabilities for a specific usage, usage page or collection, use the HIDGetSpecificValueCapabilities function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDGetValueCaps function retrieves the capabilities for all values for a specified top level collection.

    Declaration

    Objective-C

    OSStatus HIDGetValueCaps ( HIDReportType reportType, HIDValueCapsPtr valueCaps, UInt32 *valueCapsSize, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    valueCaps

    On return, points to a caller-allocated buffer that contains an array of HIDValueCaps structures containing information for all values in the top level collection.

    valueCapsSize

    On input, specifies the size in array elements of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned in the buffer provided in the valueCaps parameter, if the function completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device by the HIDGetCaps function.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDGetValueCaps function retrieves the capability data for all values in a top level collection without regard for the usage, usage page or collection of the value. To retrieve value capabilities for a specific usage, usage page or collection, use the HIDGetSpecificValueCaps function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDMaxUsageListLength function returns the maximum number of buttons that can be returned from a given report type for the top level collection.

    Declaration

    Objective-C

    UInt32 HIDMaxUsageListLength ( HIDReportType reportType, HIDUsage usagePage, HIDPreparsedDataRef preparsedDataRef );

    Parameters

    reportType

    Specifies the type of report for which to get a maximum usage count. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Optionally specifies the usage page identifier to use as a search criteria. If this parameter is zero, the function returns the number of buttons for the entire top-level collection regardless of the actual value of the usage page.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDOpenReportDescriptor function allocates the memory the parser needs to handle the given report descriptor, and then parses the report descriptor.

    Declaration

    Objective-C

    OSStatus HIDOpenReportDescriptor ( void *hidReportDescriptor, IOByteCount descriptorLength, HIDPreparsedDataRef *preparsedDataRef, UInt32 flags );

    Parameters

    hidReportDescriptor

    Contains a pointer to the actual HID report descriptor from the USB device's firmware

    descriptorLength

    The length of the HID report descriptor

    preparsedDataRef

    Preparsed data reference to be used for subsequent function calls

    flags

    Flags for this runction are kHIDFlag_StrictErrorChecking = 0x00000001

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    When the parsed information is no longer needed, clients should call the HIDCloseReportDescriptor function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDSetButton function takes a report from a HID device and sets the current state of the specified button in that report.

    Declaration

    Objective-C

    OSStatus HIDSetButton ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page identifier of the value to be set in the report.

    collection

    Optionally specifies the link collection identifier to distinguish between buttons. If this parameter is zero, it is ignored.

    usage

    Points to a caller-allocated buffer that contains the button data to be set in the report in the report parameter.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the size, in bytes, of the report data provided in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDSetButtons function takes a report from a HID device and returns the current state of the buttons in that report.

    Declaration

    Objective-C

    OSStatus HIDSetButtons ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage *usageList, UInt32 *usageListSize, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of repor. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page identifier of the value to be set in the report.

    collection

    Optionally specifies the link collection identifier to distinguish between buttons. If this parameter is zero, it is ignored.

    usageList

    Points to a caller-allocated buffer that contains an array of button data to be set in the report in the report parameter.

    usageListSize

    Specifies the size, in array elements, of the buffer provided in the usageList parameter. If an error is returned by a call to this function, the usageListLength parameter contains the location in the array provided in the usageList parameter where the error was encountered. All array entries encountered prior to the error location were successfully set in the report provided in the report parameter.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the size, in bytes, of the report data provided in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDSetScaledUsageValue function takes a signed physical (scaled) number and converts it to the logical, or device representation and inserts it in a given report.

    Declaration

    Objective-C

    OSStatus HIDSetScaledUsageValue ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, SInt32 usageValue, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page identifier of the value to be set in the report.

    collection

    Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it will be ignored.

    usage

    Specifies the usage identifier of the value to be set in the report.

    usageValue

    Specifies the physical, or scaled, value to be set in the value for the given report.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    Specifies

    the length, in bytes of the report data specified in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDSetScaledUsageValue function automatically handles the setting of the signed bit in the data to be sent to the device.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDSetUsageValue function sets a value in a give report.

    Declaration

    Objective-C

    OSStatus HIDSetUsageValue ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, SInt32 usageValue, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page identifier of the value to be set in the report.

    collection

    Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it is ignored.

    usage

    Specifies the usage identifier of the value to be set in the report.

    usageValue

    Specifies the data that is to be set in the value for the given report.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the size, in bytes, of the report data provided in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDSetUsageVlaue function does not automatically handle the sign bit. Clients must either manually set the sign bit, at the position provided in the HIDValueCaps structure for this value, or call the HIDSetScaledUsageValue function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDSetUsageValueArray function sets an array of values in a given report.

    Declaration

    Objective-C

    OSStatus HIDSetUsageValueArray ( HIDReportType reportType, HIDUsage usagePage, UInt32 collection, HIDUsage usage, UInt8 *usageValueBuffer, IOByteCount usageValueBufferLength, HIDPreparsedDataRef preparsedDataRef, void *report, IOByteCount reportLength );

    Parameters

    reportType

    Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.

    usagePage

    Specifies the usage page identifier of the value to be set in the report.

    collection

    Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it is ignored.

    usage

    Specifies the usage identifier of the value to be set in the report.

    usageValueBuffer

    Points to a caller-allocated buffer that contains, on output, the data from the device. The correct length for this buffer can be found by multiplying the reportCount and bitSize fields of the HIDValueCaps structure for this value and rounding the resulting value up to the nearest byte.

    usageValueBufferLength

    Specifies the size, in bytes, of the buffer in the usageValueBuffer parameter.

    preparsedDataRef

    Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

    report

    Points to the caller-allocated buffer that contains the device report data.

    reportLength

    Specifies the size, in bytes, of the report data provided in the report parameter.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Discussion

    The HIDSetUsageValue function does not automatically handle the sign bit. Clients must either manually set the sign bit, at the position provided in the HIDValueCaps structure for this value, or call the HIDSetScaledUsageValue function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDUsageListDifference function compares and provides the differences between two lists of buttons.

    Declaration

    Objective-C

    OSStatus HIDUsageListDifference ( HIDUsage *previousUsageList, HIDUsage *currentUsageList, HIDUsage *breakUsageList, HIDUsage *makeUsageList, UInt32 usageListsSize );

    Parameters

    previousUsageList

    Points to the older button list to be used for comparison.

    currentUsageList

    Points to the newer button list to be used for comparison.

    breakUsageList

    On return, points to a caller-allocated buffer that contains the buttons set in the older list, specified in the previousUsageList parameter, but not set in the new list, specified in the currentUsageList parameter.

    makeUsageList

    On return, points to a caller-allocated buffer that contains the buttons set in the new list, specified in the currentUsageList parameter, but not set in the old list, specified in the previousUsageList parameter.

    usageListsLength

    Specifies the length, in array elements, of the buffers provided in the currentUsageList and previousUssageList parameters.

    Return Value

    OSStatus Returns an error code if an error was encountered or noErr on success.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

Data Types

See the Overview section above for header-level documentation.

  • The HIDCaps data structure is used by HID clients to hold the capabilities of a HID device.

    Declaration

    Objective-C

    typedef struct HIDCaps HIDCaps, * HIDCapsPtr;

    Discussion

    This structure holds the parsed capabilities and data maximums returned for a device by the HIDGetCaps function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDCaps data structure is used by HID clients to hold the capabilities of a HID device.

    Declaration

    Objective-C

    typedef struct HIDCaps HIDCaps, * HIDCapsPtr;

    Discussion

    This structure holds the parsed capabilities and data maximums returned for a device by the HIDGetCaps function.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDUsageAndPage data structure is used by HID clients when obtaining status of buttons to hold the usage page and usage of a button that is down.

    Declaration

    Objective-C

    typedef struct HIDUsageAndPage HIDUsageAndPage, *HIDUsageAndPagePtr;

    Discussion

    Clients use the HIDUSageAndPage structure with the HIDGetButtonsEx function to obtain both the usage page and usage identifiers of each button that is down.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDUsageAndPage data structure is used by HID clients when obtaining status of buttons to hold the usage page and usage of a button that is down.

    Declaration

    Objective-C

    typedef struct HIDUsageAndPage HIDUsageAndPage, *HIDUsageAndPagePtr;

    Discussion

    Clients use the HIDUSageAndPage structure with the HIDGetButtonsEx function to obtain both the usage page and usage identifiers of each button that is down.

    Import Statement

    Objective-C

    #include <IOHIDDescriptorParser.h>;

    Availability

    Available in OS X v10.0 and later.

  • The HIDCaps data structure is used by HID clients to hold the capabilities of a HID device.

    Declaration

    Objective-C

    struct HIDCaps { HIDUsage usage; HIDUsage usagePage; IOByteCount inputReportByteLength; IOByteCount outputReportByteLength; IOByteCount featureReportByteLength; UInt32 numberCollectionNodes; UInt32 numberInputButtonCaps; UInt32 numberInputValueCaps; UInt32 numberOutputButtonCaps; UInt32 numberOutputValueCaps; UInt32 numberFeatureButtonCaps; UInt32 numberFeatureValueCaps; };

    Fields

    usage

    Specifies the specific class of functionality that this device provides. This value is dependent and specific to the value provided in the usagePage field. For example, a keyboard could have a usagePage of kHIDUsagePage_Generic and a usage of kHIDUsage_Generic_Keyboard.

    usagePage

    Specifies the usage page identifier for this top level collection.

    inputReportByteLength

    Specifies the maximum length, in bytes, of an input report for this device, including the report ID which is unilaterally prepended to the device data.

    outputReportByteLength

    Specifies the maximum length, in bytes, of an output report for this device, including the report ID which is unilaterally prepended to the device data.

    featureReportByteLength

    Specifies the maximum length, in bytes, of a feature report for this device, including the report ID which is unilaterally prepended to the device data.

    numberCollectionNodes

    Specifies the number of HIDCollectionNode structures that are returned for this top level collection by the HIDGetConnectionNodes function.

    numberInputButtonCaps

    Specifies the number of input buttons.

    numberInputValueCaps

    Specifies the number of input values.

    numberOutputButtonCaps

    Specifies the number of output buttons.

    numberOutputValueCaps

    Specifies the number of output values

    numberFeatureButtonCaps

    Specifies the number of feature buttons.

    numberFeatureValueCaps

    Specifies the number of feature values.

    Discussion

    This structure holds the parsed capabilities and data maximums returned for a device by the HIDGetCaps function.

  • The HIDUsageAndPage data structure is used by HID clients when obtaining status of buttons to hold the usage page and usage of a button that is down.

    Declaration

    Objective-C

    struct HIDUsageAndPage { HIDUsage usage; HIDUsage usagePage; };

    Fields

    usage

    Specifies the usage identifier within the usage page specified by usagePage of a button that is down.

    usagePage

    Specifies the usage page identifier of a button that is down.

    Discussion

    Clients use the HIDUSageAndPage structure with the HIDGetButtonsEx function to obtain both the usage page and usage identifiers of each button that is down.