IOHIDDevice

Inherits from
IOService
Availability
Available in OS X v10.0 and later.
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 registry, and also by reporting HID events through shared memory. 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.

Tasks

Miscellaneous

Instance Methods

checkEventDelivery

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

message

Receives messages delivered from an attached provider.

virtual IOReturn message( UInt32 type, IOService *provider, void *argument = 0 );
Parameters
type

A type defined in IOMessage.h.

provider

The provider from which the message originates.

argument

An argument defined by the message type.

Return Value

An IOReturn code defined by the message type.

Discussion

Handles the kIOMessageDeviceSignaledWakeup message from a provider identifying the IOHIDDevice as the wakeup source.

newCountryCodeNumber

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

virtual OSNumber * newCountryCodeNumber() const;
Return Value

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

newDeviceUsagePairs

Returns an array of usage dictionaries. IOHIDDevice creates create this from the actual report descriptor, and that should be the base for any subclass override.

virtual OSArray * newDeviceUsagePairs();
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

Instance Variables

reserved

ExpansionData * _reserved;

Reserved for future use. (Internal use only)

See Also

_reserved

ExpansionData * _reserved;

Reserved for future use. (Internal use only)

See Also