ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOHIDDevice

Inherits from:	IOService
Declared In:	IOHIDDevice.h

Overview

IOHIDDevice defines a Human Interface Device (HID) object, which will interact with the HID Manager by publishing static properties in the I/O Registry, and also by reporting HID events through shared memory.

Discussion

IOHIDDevice is an abstract class that must be subclassed to support a specific type of HID devices, such as USB HID class devices.

Since most HID devices are expected to be USB devices, IOHIDDevice uses the USB HID specification to define the format of the report descriptor, and also reports that are used to communicate with the hardware via some intervening transport layer. However, there is no mandate that the transport layer must be restricted to USB. A subclass may be created to support legacy ADB joysticks, and issue packets on the ADB bus and translate those packets to USB reports, and vice versa. IOHIDDevice does not care how those reports are generated or consumed by the physical device, as long as the reports abide to the USB specification.

Functions

checkEventDelivery: Check whether events from a HID element will be delivered to the event queue specified.
free: Free the IOHIDDevice object.
getMemoryWithCurrentElementValues: Get a reference to a memory descriptor that describes the memory block containing the current HID element values.
getReport(IOMemoryDescriptor *, IOHIDReportType, IOOptionBits): Get a report from the HID device.
getReport(IOMemoryDescriptor *, IOHIDReportType, IOOptionBits, UInt32, IOHIDCompletion *): Get a report from the HID device.
handleClose: Handle a client close on the interface.
handleIsOpen: Query whether a client has an open on the interface.
handleOpen: Handle a client open on the interface.
handleReport: Handle an asynchronous report received from the HID device.
handleReportWithTime: Handle an asynchronous report received from the HID device.
handleStart: Prepare the hardware and driver to support I/O operations.
handleStop: Quiesce the hardware and stop the driver.
init: Initialize an IOHIDDevice object.
matchPropertyTable: Called by the provider during a match
newCountryCodeNumber: Returns a number object that describes the country code of the HID device.
newLocationIDNumber: Returns a number object that describes the location ID of the HID device.
newManufacturerString: Returns a string object that describes the manufacturer of the HID device.
newPrimaryUsageNumber: Returns a number object that describes the primary usage of the HID device.
newPrimaryUsagePageNumber: Returns a number object that describes the primary usage page of the HID device.
newProductIDNumber: Returns a number object that describes the product ID of the HID device.
newProductString: Returns a string object that describes the product of the HID device.
newReportDescriptor: Create and return a new memory descriptor that describes the report descriptor for the HID device.
newReportInterval: Returns a number object that describes the actual polling interval of the HID device in microseconds.
newReportIntervalNumber: Returns a number object that describes the actual polling interval of the HID device in microseconds.
newSerialNumber: THIS HAS BEEN DEPRECATED. PLEASE USE newSerialNumberString.
newSerialNumberString: Returns a string object that describes the serial number of the HID device.
newTransportString: Returns a string object that describes the transport layer used by the HID device.
newUserClient: Handle a request to create a connection for a non kernel client.
newVendorIDNumber: Returns a number object that describes the vendor ID of the HID device.
newVendorIDSourceNumber: Returns a number object that describes the vendor ID source of the HID device.
newVersionNumber: Returns a number object that describes the version number of the HID device.
postElementValues: Posts element values to a HID device via setReport.
publishProperties: Publish HID properties to the I/O Kit registry.
registerElement: A registration function called by a HID element to register itself, and also to obtain an unique cookie identifier (unique per device, not unique system-wide).
setReport(IOMemoryDescriptor *, IOHIDReportType, IOOptionBits): Send a report to the HID device.
setReport(IOMemoryDescriptor *, IOHIDReportType, IOOptionBits, UInt32, IOHIDCompletion *): Send a report to the HID device.
start: Start up the driver using the given provider.
startEventDelivery: Start delivering events from a HID element to the event queue specified.
stop: Called by a provider (during its termination) before detaching all its clients.
stopEventDelivery: Stop delivering events from one or more HID elements to the event queue specified.
updateElementValues: Updates element values from a HID device via getReport.

checkEventDelivery

Check whether events from a HID element will be delivered to the event queue specified.

public

virtual IOReturn checkEventDelivery(
    IOHIDEventQueue *queue, 
    IOHIDElementCookie cookie, 
    bool *isActive );

Parameters

queue: The event queue.
cookie: The cookie for a HID element published by the HID device.
isActive: Pointer to the return value that is set to true if events generated by the HID element will be delivered to the queue, or false otherwise. This return value is set only if kIOReturnSuccess is returned.

Return Value

kIOReturnSuccess on success, or kIOReturnBadArgument if one or more of the arguments provided are invalid.

free

Free the IOHIDDevice object.

protected

virtual void free();

Discussion

Release all resources that were previously allocated, then call super::free() to propagate the call to our superclass.

getMemoryWithCurrentElementValues

Get a reference to a memory descriptor that describes the memory block containing the current HID element values.

public

virtual IOMemoryDescriptor * getMemoryWithCurrentElementValues() const;

Return Value

A reference to a memory descriptor that describes the current element values, or 0 to indicate a resource shortage.

Discussion

Each HID element that can contribute to an input, output, or feature report, is assigned an area of memory from a common memory block allocated by IOHIDDevice. Each element will use its assigned memory area to store its current value, defined by an IOHIDElementValue structure. The memory described by the memory descriptor may be mapped to user space to allow the HID Manager to poll the current element value without the cost of a user-kernel transition. Subclasses should not override this method.

getReport(IOMemoryDescriptor *, IOHIDReportType, IOOptionBits)

Get a report from the HID device.

public

virtual IOReturn getReport(
    IOMemoryDescriptor *report, 
    IOHIDReportType reportType, 
    IOOptionBits options );

Parameters

report: A memory descriptor that describes the memory to store the report read from the HID device.
reportType: The report type.
options: The lower 8 bits will represent the Report ID. The other 24 bits are options to specify the request.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A completion parameter may be added in the future.

getReport(IOMemoryDescriptor , IOHIDReportType, IOOptionBits, UInt32, IOHIDCompletion )

Get a report from the HID device.

public

virtual IOReturn getReport(
    IOMemoryDescriptor *report, 
    IOHIDReportType reportType, 
    IOOptionBits options, 
    UInt32 completionTimeout, 
    IOHIDCompletion *completion = 0);

Parameters

report: A memory descriptor that describes the memory to store the report read from the HID device.
reportType: The report type.
options: The lower 8 bits will represent the Report ID. The other 24 bits are options to specify the request.
completionTimeout: Specifies an amount of time (in ms) after which the command will be aborted if the entire command has not been completed.
completion: Function to call when request completes. If omitted then getReport() executes synchronously, blocking until the request is complete.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A completion parameter may be added in the future.

handleClose

Handle a client close on the interface.

protected

virtual void handleClose(
    IOService *client,
    IOOptionBits options);

Parameters

client: The client object that requested the close.
options: Options passed to IOService::close().

Discussion

This method is called by IOService::close() with the arbitration lock held. This method will in turn call handleClientClose() to notify interested subclasses about the client close. If this represents the last close, then the interface will also close the controller before this method returns. The controllerWillClose() method will be called before closing the controller. Subclasses should not override this method.

handleIsOpen

Query whether a client has an open on the interface.

protected

virtual bool handleIsOpen(
    const IOService * client) const;

Return Value

true if the specified client, or any client if none (0) is specified, presently has an open on this object.

Discussion

This method is always called by IOService with the arbitration lock held. Subclasses should not override this method.

handleOpen

Handle a client open on the interface.

protected

virtual bool handleOpen(
    IOService *client, 
    IOOptionBits options, 
    void *argument);

Parameters

client: The client object that requested the open.
options: Options passed to IOService::open().
argument: Argument passed to IOService::open().

Return Value

true to accept the client open, false otherwise.

Discussion

This method is called by IOService::open() with the arbitration lock held, and must return true to accept the client open. This method will in turn call handleClientOpen() to qualify the client requesting the open.

handleReport

Handle an asynchronous report received from the HID device.

public

virtual IOReturn handleReport( 
    IOMemoryDescriptor *report, 
    IOHIDReportType reportType = kIOHIDReportTypeInput, 
    IOOptionBits options = 0 );

Parameters

report: A memory descriptor that describes the report.
reportType: The type of report.
options: Options to specify the request. No options are currently defined, and the default value is 0.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

handleReportWithTime

Handle an asynchronous report received from the HID device.

public

virtual IOReturn handleReportWithTime( 
    AbsoluteTime timeStamp, 
    IOMemoryDescriptor *report, 
    IOHIDReportType reportType = kIOHIDReportTypeInput, 
    IOOptionBits options = 0);

Parameters

timeStamp: The timestamp of report.
report: A memory descriptor that describes the report.
reportType: The type of report. Currently, only kIOHIDReportTypeInput report type is handled.
options: Options to specify the request. No options are currently defined, and the default value is 0.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

handleStart

Prepare the hardware and driver to support I/O operations.

protected

virtual bool handleStart(
    IOService *provider );

Parameters

provider: The provider argument passed to start().

Return Value

True on success, or false otherwise. Returning false will cause start() to fail and return false.

Discussion

IOHIDDevice will call this method from start() before any I/O operations are issued to the concrete subclass. Methods such as newReportDescriptor() are only called after handleStart() has returned true. A subclass that overrides this method should begin its implementation by calling the version in super, and then check the return value.

handleStop

Quiesce the hardware and stop the driver.

protected

virtual void handleStop(
    IOService *provider );

Parameters

provider: The provider argument passed to stop().

Discussion

IOHIDDevice will call this method from stop() to signal that the hardware should be quiesced and the driver stopped. A subclass that overrides this method should end its implementation by calling the version in super.

init

Initialize an IOHIDDevice object.

public

virtual bool init(
    OSDictionary *dictionary = 0 );

Parameters

A: dictionary A property table associated with this IOHIDDevice instance.

Return Value

True on sucess, or false otherwise.

Discussion

Prime the IOHIDDevice object and prepare it to support a probe() or a start() call. This implementation will simply call super::init().

matchPropertyTable

Called by the provider during a match

public

virtual bool matchPropertyTable(
    OSDictionary *table,
    SInt32 *score);

Parameters

table: The property table that this device will match against

Discussion

Compare the properties in the supplied table to this object's properties.

newCountryCodeNumber

Returns a number object that describes the country code of the HID device.

public

virtual OSNumber * newCountryCodeNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newLocationIDNumber

Returns a number object that describes the location ID of the HID device.

public

virtual OSNumber * newLocationIDNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newManufacturerString

Returns a string object that describes the manufacturer of the HID device.

public

virtual OSString * newManufacturerString() const;

Return Value

A string object. The caller must decrement the retain count on the object returned.

newPrimaryUsageNumber

Returns a number object that describes the primary usage of the HID device.

public

virtual OSNumber * newPrimaryUsageNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newPrimaryUsagePageNumber

Returns a number object that describes the primary usage page of the HID device.

public

virtual OSNumber * newPrimaryUsagePageNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newProductIDNumber

Returns a number object that describes the product ID of the HID device.

public

virtual OSNumber * newProductIDNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newProductString

Returns a string object that describes the product of the HID device.

public

virtual OSString * newProductString() const;

Return Value

A string object. The caller must decrement the retain count on the object returned.

newReportDescriptor

Create and return a new memory descriptor that describes the report descriptor for the HID device.

public

virtual IOReturn newReportDescriptor( 
    IOMemoryDescriptor **descriptor ) const = 0;

Parameters

descriptor: Pointer to the memory descriptor returned. This memory descriptor will be released by the caller.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A subclass must override this pure virtual function, and return a memory descriptor that describes the HID report descriptor as defined by the USB Device Class Definition for Human Interface Devices Version 1.1 specification.

newReportInterval

Returns a number object that describes the actual polling interval of the HID device in microseconds.

public

virtual OSNumber * newReportIntervalNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newReportIntervalNumber

Returns a number object that describes the actual polling interval of the HID device in microseconds.

public

virtual OSNumber * newReportIntervalNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newSerialNumber

THIS HAS BEEN DEPRECATED. PLEASE USE newSerialNumberString.

public

virtual OSNumber * newSerialNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newSerialNumberString

Returns a string object that describes the serial number of the HID device.

public

virtual OSString * newSerialNumberString() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newTransportString

Returns a string object that describes the transport layer used by the HID device.

public

virtual OSString * newTransportString() const;

Return Value

A string object. The caller must decrement the retain count on the object returned.

newUserClient

Handle a request to create a connection for a non kernel client.

protected

virtual IOReturn newUserClient(
    task_t owningTask, 
    void *security_id, 
    UInt32 type, 
    OSDictionary *properties, 
    IOUserClient **handler );

Parameters

owningTask: The mach task requesting the connection.
security_id: A token representing the access level for the task.
type: A constant specifying the type of connection to be created.
properties: A dictionary of additional properties for the connection.
handler: The IOUserClient object returned.

Return Value

The return from IOService::newUserClient() is returned.

Discussion

Create a new IOUserClient, or a subclass of IOUserClient, to service a connection to a non kernel client. This implementation will simply call the implementation in IOService to handle the call.

newVendorIDNumber

Returns a number object that describes the vendor ID of the HID device.

public

virtual OSNumber * newVendorIDNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newVendorIDSourceNumber

Returns a number object that describes the vendor ID source of the HID device.

public

virtual OSNumber * newVendorIDSourceNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

newVersionNumber

Returns a number object that describes the version number of the HID device.

public

virtual OSNumber * newVersionNumber() const;

Return Value

A number object. The caller must decrement the retain count on the object returned.

postElementValues

Posts element values to a HID device via setReport.

public

virtual IOReturn postElementValues(
    IOHIDElementCookie *cookies,
    UInt32 cookieCount = 1);

Parameters

cookies: A list of element cookies who's values need to be set on the device.
cookieCount: The number of element cookies.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A completion parameter may be added in the future.

publishProperties

Publish HID properties to the I/O Kit registry.

protected

virtual bool publishProperties(
    IOService *provider );

Parameters

provider: The provider argument passed to start().

Return Value

True to indicate that all properties were discovered and published to the registry, false otherwise. Returning false will cause start() to fail and return false.

Discussion

Called by the start() method to fetch and publish all HID properties to the I/O Kit registry. These properties will allow the HID Manager to identify all HID device(s) in the system, by iterating through objects that are subclasses of IOHIDDevice, and then fetch their published property values. The implementation in IOHIDDevice will call methods to get each individual HID property, and subclasses will not normally need to override this method.

registerElement

A registration function called by a HID element to register itself, and also to obtain an unique cookie identifier (unique per device, not unique system-wide).

public

virtual bool registerElement(
    IOHIDElementPrivate *element, 
    IOHIDElementCookie *cookie );

Parameters

element: The element that is requesting registration with its owner.
cookie: Pointer to the returned cookie assigned to this element.

Return Value

True on success, or false otherwise.

Discussion

An internal data type, an IOHIDElementPrivate, is created to represent each HID element discovered by parsing the HID report descriptor. Each element created will call this method to register itself with its owner (IOHIDDevice), and also to obtain an element cookie that is used by HID Manager to specify and identify the element. Subclasses should not override this method.

setReport(IOMemoryDescriptor *, IOHIDReportType, IOOptionBits)

Send a report to the HID device.

public

virtual IOReturn setReport(
    IOMemoryDescriptor *report, 
    IOHIDReportType reportType, 
    IOOptionBits options = 0 );

Parameters

report: A memory descriptor that describes the report to send to the HID device.
reportType: The report type.
options: The lower 8 bits will represent the Report ID. The other 24 bits are options to specify the request.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A completion parameter may be added in the future.

setReport(IOMemoryDescriptor , IOHIDReportType, IOOptionBits, UInt32, IOHIDCompletion )

Send a report to the HID device.

public

virtual IOReturn setReport(
    IOMemoryDescriptor *report, 
    IOHIDReportType reportType, 
    IOOptionBits options, 
    UInt32 completionTimeout, 
    IOHIDCompletion *completion = 0);

Parameters

report: A memory descriptor that describes the report to send to the HID device.
reportType: The report type.
options: The lower 8 bits will represent the Report ID. The other 24 bits are options to specify the request.
completionTimeout: Specifies an amount of time (in ms) after which the command will be aborted if the entire command has not been completed.
completion: Function to call when request completes. If omitted then setReport() executes synchronously, blocking until the request is complete.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A completion parameter may be added in the future.

start

Start up the driver using the given provider.

public

virtual bool start(
    IOService *provider );

Parameters

provider: The provider that the driver was matched to, and selected to run with.

Return Value

True on success, or false otherwise.

Discussion

IOHIDDevice will allocate resources, then call handleStart() before fetching the report descriptor through newReportDescriptor(), and publishing HID properties to the registry. Before returning true to indicate success, registerService() is called to trigger client matching. Subclasses are recommended to override handleStart().

startEventDelivery

Start delivering events from a HID element to the event queue specified.

public

virtual IOReturn startEventDelivery(
    IOHIDEventQueue *queue, 
    IOHIDElementCookie cookie, 
    IOOptionBits options = 0 );

Parameters

queue: The event queue that is interested in receiving events generated by the HID element specified. The retain count on the queue will be incremented by one.
cookie: The cookie for a HID element published by the HID device.
options: Options to specify the request. No options are currently defined, and the default value is zero.

Return Value

kIOReturnSuccess on success, or kIOReturnBadArgument if the queue or the cookie argument specified is invalid, or kIOReturnNoMemory if a resource shortage was encountered.

Discussion

Clients of IOHIDDevice may create an IOHIDEventQueue, and then call this method to register for delivery of events generated by one or more HID elements to that event queue. Subclasses should not override this method.

stop

Called by a provider (during its termination) before detaching all its clients.

public

virtual void stop(
    IOService *provider );

Parameters

provider: The provider that the driver was started on.

Discussion

IOHIDDevice will call handleStop(), then release allocated resources. Subclasses are recommended to override handleStop().

stopEventDelivery

Stop delivering events from one or more HID elements to the event queue specified.

public

virtual IOReturn stopEventDelivery(
    IOHIDEventQueue *queue, 
    IOHIDElementCookie cookie = 0 );

Parameters

queue: The event queue that no longer wishes to receive events generated by the HID element specified.
cookie: The cookie for a HID element published by the HID device. The default value of zero indicates that the queue should be removed from the event dispatch list of all HID elements published by the HID device. Subclasses should not override this method.

Return Value

kIOReturnSuccess if the queue was removed from the event dispatch list for one or more HID elements, or kIOReturnBadArgument if the queue or the cookie argument specified is invalid, or kIOReturnNotFound if the queue was not found.

Discussion

Clients that called startEventDelivery() must eventually call this method to stop event delivery to its queue from one or more HID elements.

updateElementValues

Updates element values from a HID device via getReport.

public

virtual IOReturn updateElementValues(
    IOHIDElementCookie *cookies,
    UInt32 cookieCount = 1);

Parameters

cookies: A list of element cookies who's values need to be set on the device.
cookieCount: The number of element cookies.

Return Value

kIOReturnSuccess on success, or an error return otherwise.

Discussion

A completion parameter may be added in the future.

Member Data

_reserved

See Also:

reserved

private

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

reserved

See Also:

_reserved

private

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

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-12-19