Mac Developer Library

Developer

IOHIDDevice Class Reference

Options
Deployment Target:

On This Page
Language:

IOHIDDevice

Inheritance


  • IOHIDDevice

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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.

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

    Declaration

    C++

    virtual IOReturn checkEventDelivery( IOHIDEventQueue *queue, IOHIDElementCookiecookie, 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 the IOHIDDevice object.

    Declaration

    C++

    virtual void free();

    Discussion

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

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

    Declaration

    C++

    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.

  • Get a report from the HID device.

    Declaration

    C++

    virtual IOReturn getReport( IOMemoryDescriptor *report, IOHIDReportTypereportType, IOOptionBitsoptions );

    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.

  • Get a report from the HID device.

    Declaration

    C++

    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.

  • Handle a client close on the interface.

    Declaration

    C++

    virtual void handleClose( IOService *client, IOOptionBitsoptions);

    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.

  • Query whether a client has an open on the interface.

    Declaration

    C++

    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.

  • Handle a client open on the interface.

    Declaration

    C++

    virtual bool handleOpen( IOService *client, IOOptionBitsoptions, 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.

  • Handle an asynchronous report received from the HID device.

    Declaration

    C++

    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.

  • Handle an asynchronous report received from the HID device.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Quiesce the hardware and stop the driver.

    Declaration

    C++

    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.

  • Initialize an IOHIDDevice object.

    Declaration

    C++

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

  • Called by the provider during a match

    Declaration

    C++

    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.

  • Receives messages delivered from an attached provider.

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual OSNumber * newCountryCodeNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSArray * newDeviceUsagePairs();

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newLocationIDNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSString * newManufacturerString() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newPrimaryUsageNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newPrimaryUsagePageNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newProductIDNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSString * newProductString() const;

    Return Value

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

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual OSNumber * newReportIntervalNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newReportIntervalNumber() const;

    Return Value

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

  • THIS HAS BEEN DEPRECATED. PLEASE USE newSerialNumberString.

    Declaration

    C++

    virtual OSNumber * newSerialNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSString * newSerialNumberString() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSString * newTransportString() const;

    Return Value

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

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

    Declaration

    C++

    virtual IOReturn newUserClient( task_towningTask, void *security_id, UInt32type, 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.

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

    Declaration

    C++

    virtual OSNumber * newVendorIDNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newVendorIDSourceNumber() const;

    Return Value

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

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

    Declaration

    C++

    virtual OSNumber * newVersionNumber() const;

    Return Value

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

  • Posts element values to a HID device via setReport.

    Declaration

    C++

    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.

  • Publish HID properties to the I/O Kit registry.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Send a report to the HID device.

    Declaration

    C++

    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.

  • Send a report to the HID device.

    Declaration

    C++

    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 up the driver using the given provider.

    Declaration

    C++

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

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

    Declaration

    C++

    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.

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

    Declaration

    C++

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

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

    Declaration

    C++

    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.

  • Updates element values from a HID device via getReport.

    Declaration

    C++

    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 for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;