ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOHIDValue

Includes:

Overview

IOHIDValue defines a value at a given time from an parsed item (IOHIDElement) contained within a Human Interface Device (HID) object. It is used to obtain either integer or data element values along with scaled values based on physical or calibrated settings. IOHIDValue is a CFType object and as such conforms to all the conventions expected such object.

This documentation assumes that you have 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 dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications.

This documentation also assumes you have read Human Interface Device & Force Feedback. Please review documentation before using this reference.

All of the information described in this document is contained in the header file IOHIDValue.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDValue.h.

Functions

IOHIDValueCreateWithBytes: Creates a new element value using byte data.
IOHIDValueCreateWithBytesNoCopy: Creates a new element value using byte data without performing a copy.
IOHIDValueCreateWithIntegerValue: Creates a new element value using an integer value.
IOHIDValueGetBytePtr: Returns a byte pointer to the value contained in this IOHIDValueRef.
IOHIDValueGetElement: Returns the element value associated with this IOHIDValueRef.
IOHIDValueGetIntegerValue: Returns an integer representaion of the value contained in this IOHIDValueRef.
IOHIDValueGetLength: Returns the size, in bytes, of the value contained in this IOHIDValueRef.
IOHIDValueGetScaledValue: Returns an scaled representaion of the value contained in this IOHIDValueRef based on the scale type.
IOHIDValueGetTimeStamp: Returns the timestamp value contained in this IOHIDValueRef.
IOHIDValueGetTypeID: Returns the type identifier of all IOHIDValue instances.

IOHIDValueCreateWithBytes

Creates a new element value using byte data.

CF_EXPORT IOHIDValueRef IOHIDValueCreateWithBytes(
    CFAllocatorRef allocator,
    IOHIDElementRef element,
    uint64_t timeStamp,
    const uint8_t *bytes,
    CFIndex length) ;

Parameters

allocator: The CFAllocator which should be used to allocate memory for the value. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
element: IOHIDElementRef associated with this value.
timeStamp: OS absolute time timestamp for this value.
bytes: Pointer to a buffer of uint8_t to be copied to this object.
length: Number of bytes in the passed buffer.

Return Value

Returns a reference to a new IOHIDValueRef.

Discussion

IOHIDValueGetTimeStamp should represent OS AbsoluteTime, not CFAbsoluteTime. To obtain the OS AbsoluteTime, please reference the APIs declared in

Availability: Introduced in Mac OS X v10.5.

IOHIDValueCreateWithBytesNoCopy

Creates a new element value using byte data without performing a copy.

CF_EXPORT IOHIDValueRef IOHIDValueCreateWithBytesNoCopy(
    CFAllocatorRef allocator,
    IOHIDElementRef element,
    uint64_t timeStamp,
    const uint8_t *bytes,
    CFIndex length) ;

Parameters

allocator: The CFAllocator which should be used to allocate memory for the value. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
element: IOHIDElementRef associated with this value.
timeStamp: OS absolute time timestamp for this value.
bytes: Pointer to a buffer of uint8_t to be referenced by this object.
length: Number of bytes in the passed buffer.

Return Value

Returns a reference to a new IOHIDValueRef.

Discussion

The timestamp value passed should represent OS AbsoluteTime, not CFAbsoluteTime. To obtain the OS AbsoluteTime, please reference the APIs declared in

Availability: Introduced in Mac OS X v10.5.

IOHIDValueCreateWithIntegerValue

Creates a new element value using an integer value.

CF_EXPORT IOHIDValueRef IOHIDValueCreateWithIntegerValue(
    CFAllocatorRef allocator,
    IOHIDElementRef element,
    uint64_t timeStamp,
    CFIndex value) ;

Parameters

allocator: The CFAllocator which should be used to allocate memory for the value. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
element: IOHIDElementRef associated with this value.
timeStamp: OS absolute time timestamp for this value.
value: Integer value to be copied to this object.

Return Value

Returns a reference to a new IOHIDValueRef.

Discussion

IOHIDValueGetTimeStamp should represent OS AbsoluteTime, not CFAbsoluteTime. To obtain the OS AbsoluteTime, please reference the APIs declared in

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetBytePtr

Returns a byte pointer to the value contained in this IOHIDValueRef.

CF_EXPORT const uint8_t * IOHIDValueGetBytePtr(
    IOHIDValueRef value) ;

Parameters

value: The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.

Return Value

Returns a pointer to the value.

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetElement

Returns the element value associated with this IOHIDValueRef.

CF_EXPORT IOHIDElementRef IOHIDValueGetElement(
    IOHIDValueRef value) ;

Parameters

value: The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.

Return Value

Returns a IOHIDElementRef referenced by this value.

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetIntegerValue

Returns an integer representaion of the value contained in this IOHIDValueRef.

CF_EXPORT CFIndex IOHIDValueGetIntegerValue(
    IOHIDValueRef value) ;

Parameters

value: The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.

Return Value

Returns an integer representation of the value.

Discussion

The value is based on the logical element value contained in the report returned by the device.

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetLength

Returns the size, in bytes, of the value contained in this IOHIDValueRef.

CF_EXPORT CFIndex IOHIDValueGetLength(
    IOHIDValueRef value) ;

Parameters

value: The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.

Return Value

Returns length of the value.

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetScaledValue

Returns an scaled representaion of the value contained in this IOHIDValueRef based on the scale type.

CF_EXPORT double_t IOHIDValueGetScaledValue(
    IOHIDValueRef value,
    IOHIDValueScaleType type) ;

Parameters

value: The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
type: The type of scaling to be performed.

Return Value

Returns an scaled floating point representation of the value.

Discussion

The scaled value is based on the range described by the scale type's min and max, such that:
scaledValue = ((value - min) * (scaledMax - scaledMin) / (max - min)) + scaledMin
Note:
There are currently two types of scaling that can be applied:

kIOHIDValueScaleTypePhysical: Scales element value using the physical bounds of the device such that scaledMin = physicalMin and scaledMax = physicalMax.
kIOHIDValueScaleTypeCalibrated: Scales element value such that scaledMin = -1 and scaledMax = 1. This value will also take into account the calibration properties associated with this element.

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetTimeStamp

Returns the timestamp value contained in this IOHIDValueRef.

CF_EXPORT uint64_t IOHIDValueGetTimeStamp(
    IOHIDValueRef value) ;

Parameters

value: The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.

Return Value

Returns a uint64_t representing the timestamp of this value.

Discussion

The timestamp value returned represents OS AbsoluteTime, not CFAbsoluteTime.

Availability: Introduced in Mac OS X v10.5.

IOHIDValueGetTypeID

Returns the type identifier of all IOHIDValue instances.

CF_EXPORT CFTypeID IOHIDValueGetTypeID(
    void) ;

Availability: Introduced in Mac OS X v10.5.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11