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

IOHIDManager

Includes:

Overview

IOHIDManager defines an Human Interface Device (HID) managment object. It provides global interaction with managed HID devices such as discovery/removal and receiving input events. IOHIDManager is also 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 n 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 IOHIDManager.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDManager.h.

Functions

IOHIDDeviceScheduleWithRunLoop: Schedules HID manager with run loop.
IOHIDDeviceUnscheduleFromRunLoop: Unschedules HID manager with run loop.
IOHIDManagerClose: Closes the IOHIDManager.
IOHIDManagerCopyDevices: Obtains currently enumerated devices.
IOHIDManagerCreate: Creates an IOHIDManager object.
IOHIDManagerGetProperty: Obtains a property of an IOHIDManager.
IOHIDManagerGetTypeID: Returns the type identifier of all IOHIDManager instances.
IOHIDManagerOpen: Opens the IOHIDManager.
IOHIDManagerRegisterDeviceMatchingCallback: Registers a callback to be used a device is enumerated.
IOHIDManagerRegisterDeviceRemovalCallback: Registers a callback to be used when any enumerated device is removed.
IOHIDManagerRegisterInputReportCallback: Registers a callback to be used when an input report is issued by any enumerated device.
IOHIDManagerRegisterInputValueCallback: Registers a callback to be used when an input value is issued by any enumerated device.
IOHIDManagerScheduleWithRunLoop: Schedules HID manager with run loop.
IOHIDManagerSetDeviceMatching: Sets matching criteria for device enumeration.
IOHIDManagerSetDeviceMatchingMultiple: Sets multiple matching criteria for device enumeration.
IOHIDManagerSetInputValueMatching: Sets matching criteria for input values received via IOHIDManagerRegisterInputValueCallback.
IOHIDManagerSetInputValueMatchingMultiple: Sets multiple matching criteria for input values received via IOHIDManagerRegisterInputValueCallback.
IOHIDManagerSetProperty: Sets a property for an IOHIDManager.
IOHIDManagerUnscheduleFromRunLoop: Unschedules HID manager with run loop.

IOHIDDeviceScheduleWithRunLoop

Schedules HID manager with run loop.

CF_EXPORT void IOHIDManagerScheduleWithRunLoop( 
    IOHIDManagerRef manager, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode) ;

Parameters

manager: Reference to an IOHIDManager.
runLoop: RunLoop to be used when scheduling any asynchronous activity.
runLoopMode: Run loop mode to be used when scheduling any asynchronous activity.

Discussion

Formally associates manager with client's run loop. Scheduling this device with the run loop is necessary before making use of any asynchronous APIs. This will propagate to current and future devices that are enumerated.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceUnscheduleFromRunLoop

Unschedules HID manager with run loop.

CF_EXPORT void IOHIDManagerUnscheduleFromRunLoop( 
    IOHIDManagerRef manager, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode) ;

Parameters

manager: Reference to an IOHIDManager.
runLoop: RunLoop to be used when unscheduling any asynchronous activity.
runLoopMode: Run loop mode to be used when unscheduling any asynchronous activity.

Discussion

Formally disassociates device with client's run loop. This will propagate to current devices that are enumerated.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerClose

Closes the IOHIDManager.

CF_EXPORT IOReturn IOHIDManagerClose( 
    IOHIDManagerRef manager, 
    IOOptionBits options) ;

Parameters

manager: Reference to an IOHIDManager.
options: Option bits to be sent down to the manager and device.

Return Value

Returns kIOReturnSuccess if successful.

Discussion

This will also close all devices that are currently enumerated.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerCopyDevices

Obtains currently enumerated devices.

CF_EXPORT CFSetRef IOHIDManagerCopyDevices( 
    IOHIDManagerRef manager) ;

Parameters

manager: Reference to an IOHIDManager.

Return Value

CFSetRef containing IOHIDDeviceRefs.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerCreate

Creates an IOHIDManager object.

CF_EXPORT IOHIDManagerRef IOHIDManagerCreate( 
    CFAllocatorRef allocator, 
    IOOptionBits options) ;

Parameters

allocator: Allocator to be used during creation.
options: Reserved for future use.

Return Value

Returns a new IOHIDManagerRef.

Discussion

The IOHIDManager object is meant as a global management system for communicating with HID devices.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerGetProperty

Obtains a property of an IOHIDManager.

CF_EXPORT CFTypeRef IOHIDManagerGetProperty( 
    IOHIDManagerRef manager, 
    CFStringRef key) ;

Parameters

manager: Reference to an IOHIDManager.
key: CFStringRef containing key to be used when querying the manager.

Return Value

Returns CFTypeRef containing the property.

Discussion

Property keys are prefixed by kIOHIDDevice and declared in .

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerGetTypeID

Returns the type identifier of all IOHIDManager instances.

CF_EXPORT CFTypeID IOHIDManagerGetTypeID(
    void) ;

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerOpen

Opens the IOHIDManager.

CF_EXPORT IOReturn IOHIDManagerOpen( 
    IOHIDManagerRef manager, 
    IOOptionBits options) ;

Parameters

manager: Reference to an IOHIDManager.
options: Option bits to be sent down to the manager and device.

Return Value

Returns kIOReturnSuccess if successful.

Discussion

This will open both current and future devices that are enumerated. To establish an exclusive link use the kIOHIDOptionsTypeSeizeDevice option.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerRegisterDeviceMatchingCallback

Registers a callback to be used a device is enumerated.

CF_EXPORT void IOHIDManagerRegisterDeviceMatchingCallback( 
    IOHIDManagerRef manager, 
    IOHIDDeviceCallback callback, 
    void *context) ;

Parameters

manager: Reference to an IOHIDManagerRef.
callback: Pointer to a callback method of type IOHIDDeviceCallback.
context: Pointer to data to be passed to the callback.

Discussion

Only device matching the set criteria will be enumerated.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerRegisterDeviceRemovalCallback

Registers a callback to be used when any enumerated device is removed.

CF_EXPORT void IOHIDManagerRegisterDeviceRemovalCallback( 
    IOHIDManagerRef manager, 
    IOHIDDeviceCallback callback, 
    void *context) ;

Parameters

manager: Reference to an IOHIDManagerRef.
callback: Pointer to a callback method of type IOHIDDeviceCallback.
context: Pointer to data to be passed to the callback.

Discussion

In most cases this occurs when a device is unplugged.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerRegisterInputReportCallback

Registers a callback to be used when an input report is issued by any enumerated device.

CF_EXPORT void IOHIDManagerRegisterInputReportCallback( 
    IOHIDManagerRef manager, 
    IOHIDReportCallback callback, 
    void *context) ;

Parameters

manager: Reference to an IOHIDManagerRef.
callback: Pointer to a callback method of type IOHIDReportCallback.
context: Pointer to data to be passed to the callback.

Discussion

An input report is an interrupt driver report issued by a device.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerRegisterInputValueCallback

Registers a callback to be used when an input value is issued by any enumerated device.

CF_EXPORT void IOHIDManagerRegisterInputValueCallback( 
    IOHIDManagerRef manager, 
    IOHIDValueCallback callback, 
    void *context) ;

Parameters

manager: Reference to an IOHIDManagerRef.
callback: Pointer to a callback method of type IOHIDValueCallback.
context: Pointer to data to be passed to the callback.

Discussion

An input element refers to any element of type kIOHIDElementTypeInput and is usually issued by interrupt driven reports.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerScheduleWithRunLoop

Schedules HID manager with run loop.

CF_EXPORT void IOHIDManagerScheduleWithRunLoop( 
    IOHIDManagerRef manager, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode) ;

Parameters

manager: Reference to an IOHIDManager.
runLoop: RunLoop to be used when scheduling any asynchronous activity.
runLoopMode: Run loop mode to be used when scheduling any asynchronous activity.

Discussion

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerSetDeviceMatching

Sets matching criteria for device enumeration.

CF_EXPORT void IOHIDManagerSetDeviceMatching( 
    IOHIDManagerRef manager, 
    CFDictionaryRef matching) ;

Parameters

manager: Reference to an IOHIDManager.
matching: CFDictionaryRef containg device matching criteria.

Discussion

Matching keys are prefixed by kIOHIDDevice and declared in . Passing a NULL dictionary will result in all devices being enumerated. Any subsequent calls will cause the hid manager to release previously enumerated devices and restart the enuerate process using the revised criteria. If interested in multiple, specific device classes, please defer to using IOHIDManagerSetDeviceMatchingMultiple.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerSetDeviceMatchingMultiple

Sets multiple matching criteria for device enumeration.

CF_EXPORT void IOHIDManagerSetDeviceMatchingMultiple( 
    IOHIDManagerRef manager, 
    CFArrayRef multiple) ;

Parameters

manager: Reference to an IOHIDManager.
multiple: CFArrayRef containing multiple CFDictionaryRef objects containg device matching criteria.

Discussion

Matching keys are prefixed by kIOHIDDevice and declared in . This method is useful if interested in multiple, specific device classes.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerSetInputValueMatching

Sets matching criteria for input values received via IOHIDManagerRegisterInputValueCallback.

CF_EXPORT void IOHIDManagerSetInputValueMatching( 
    IOHIDManagerRef manager, 
    CFDictionaryRef matching) ;

Parameters

manager: Reference to an IOHIDManager.
matching: CFDictionaryRef containg device matching criteria.

Discussion

Matching keys are prefixed by kIOHIDElement and declared in . Passing a NULL dictionary will result in all devices being enumerated. Any subsequent calls will cause the hid manager to release previously matched input elements and restart the matching process using the revised criteria. If interested in multiple, specific device elements, please defer to using IOHIDManagerSetInputValueMatchingMultiple.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerSetInputValueMatchingMultiple

Sets multiple matching criteria for input values received via IOHIDManagerRegisterInputValueCallback.

CF_EXPORT void IOHIDManagerSetInputValueMatchingMultiple( 
    IOHIDManagerRef manager, 
    CFArrayRef multiple) ;

Parameters

manager: Reference to an IOHIDManager.
multiple: CFArrayRef containing multiple CFDictionaryRef objects containg input element matching criteria.

Discussion

Matching keys are prefixed by kIOHIDElement and declared in . This method is useful if interested in multiple, specific elements .

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerSetProperty

Sets a property for an IOHIDManager.

CF_EXPORT Boolean IOHIDManagerSetProperty( 
    IOHIDManagerRef manager, 
    CFStringRef key, 
    CFTypeRef value) ;

Parameters

manager: Reference to an IOHIDManager.
key: CFStringRef containing key to be used when modifiying the device property.
property: CFTypeRef containg the property to be set.

Return Value

Returns TRUE if successful.

Discussion

Property keys are prefixed by kIOHIDDevice and kIOHIDManager and declared in . This method will propagate any relevent properties to current and future devices that are enumerated.

Availability: Introduced in Mac OS X v10.5.

IOHIDManagerUnscheduleFromRunLoop

Unschedules HID manager with run loop.

CF_EXPORT void IOHIDManagerUnscheduleFromRunLoop( 
    IOHIDManagerRef manager, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode) ;

Parameters

manager: Reference to an IOHIDManager.
runLoop: RunLoop to be used when unscheduling any asynchronous activity.
runLoopMode: Run loop mode to be used when unscheduling any asynchronous activity.

Discussion

Formally disassociates device with client's run loop. This will propagate to current devices that are enumerated.

Availability: Introduced in Mac OS X v10.5.

Typedefs

IOHIDManagerRef

This is the type of a reference to the IOHIDManager.

typedef struct __IOHIDManager * IOHIDManagerRef;

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