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

IOUSBDeviceInterface

Declared In:

Overview

The object you use to access USB devices from user space, returned by all versions of the IOUSBFamily currently shipping.

Discussion

The functions listed here will work with any version of the IOUSBDeviceInterface, including the one shipped with Mac OS X version 10.0.

Functions

CreateDeviceAsyncEventSource: Creates a run loop source for delivery of all asynchronous notifications on this device.
CreateDeviceAsyncPort: Creates and registers a mach_port_t for asynchronous communications.
CreateInterfaceIterator: Creates an iterator to iterate over some or all of the interfaces of a device.
DeviceRequest: Sends a USB request on the default control pipe.
DeviceRequestAsync: Sends an asynchronous USB request on the default control pipe.
GetBusFrameNumber: Gets the current frame number of the bus to which the device is attached.
GetConfiguration: Returns the currently selected configuration in the device.
GetConfigurationDescriptorPtr: Returns a pointer to a configuration descriptor for a given index.
GetDeviceAddress: Returns the address of the device on its bus.
GetDeviceAsyncEventSource: Returns the CFRunLoopSourceRef for this IOService instance.
GetDeviceAsyncPort: Returns the mach_port_t port for this IOService instance.
GetDeviceBusPowerAvailable: Returns the power available to the device.
GetDeviceClass: Returns the USB Class (bDeviceClass) of the device.
GetDeviceProduct: Returns the USB Product ID (idProduct) of the device.
GetDeviceProtocol: Returns the USB Protocol (bDeviceProtocol) of the interface.
GetDeviceReleaseNumber: Returns the Device Release Number (bcdDevice) of the device.
GetDeviceSpeed: Returns the speed of the device.
GetDeviceSubClass: Returns the USB Subclass (bDeviceSubClass) of the device.
GetDeviceVendor: Returns the USB Vendor ID (idVendor) of the device.
GetLocationID: Returns the location ID.
GetNumberOfConfigurations: Returns the number of supported configurations in this device.
ResetDevice: Tells the IOUSBFamily to issue a reset to the device.
SetConfiguration: Sets the configuration in the device.
USBDeviceClose: Closes the task's connection to the IOUSBDevice.
USBDeviceOpen: Opens the IOUSBDevice for exclusive access.

CreateDeviceAsyncEventSource

Creates a run loop source for delivery of all asynchronous notifications on this device.

IOReturn ( *CreateDeviceAsyncEventSource)(
    void *self,
    CFRunLoopSourceRef *source);

Parameters

self: Pointer to the IOUSBDeviceInterface.
source: Pointer to a CFRunLoopSourceRef to return the newly created run loop event source.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

The Mac OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications (see CreateInterfaceAsyncPort). This routine wraps that port with the appropriate routing code so that the completion notifications can be automatically routed through the client's CFRunLoop.

CreateDeviceAsyncPort

Creates and registers a mach_port_t for asynchronous communications.

IOReturn ( *CreateDeviceAsyncPort)(
    void *self,
    mach_port_t *port);

Parameters

self: Pointer to the IOUSBDeviceInterface.
port: Pointer to a mach_port_t to return the newly created port.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

The Mac OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications on this mach port. After receiving a message on this port the client is obliged to call the IOKitLib.h IODispatchCalloutFromMessage function for decoding the notification message.

CreateInterfaceIterator

Creates an iterator to iterate over some or all of the interfaces of a device.

IOReturn ( *CreateInterfaceIterator)(
    void *self,
    IOUSBFindInterfaceRequest *req,
    io_iterator_t *iter);

Parameters

self: Pointer to the IOUSBDeviceInterface.
req: Pointer an IOUSBFindInterfaceRequest structure describing the desired interfaces.
iter: Pointer to a an io_iterator_t to contain the new iterator.

Return Value

Returns kIOReturnSuccess if successful or kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

DeviceRequest

Sends a USB request on the default control pipe.

IOReturn ( *DeviceRequest)(
    void *self,
    IOUSBDevRequest *req);

Parameters

self: Pointer to the IOUSBDeviceInterface.
req: Pointer to an IOUSBDevRequest containing the request.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the device is not open for exclusive access.

Discussion

The device must be open to issue this call. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.

DeviceRequestAsync

Sends an asynchronous USB request on the default control pipe.

IOReturn ( *DeviceRequestAsync)(
    void *self,
    IOUSBDevRequest *req,
    IOAsyncCallback1 callback,
    void *refCon);

Parameters

self: Pointer to the IOUSBDeviceInterface.
req: Pointer to an IOUSBDevRequest containing the request.
callback: An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refCon: Arbitrary pointer which is passed as a parameter to the callback routine.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNotOpen if the device is not open for exclusive access, or kIOUSBNoAsyncPortErr if no Async port has been created for this interface.

Discussion

The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.

GetBusFrameNumber

Gets the current frame number of the bus to which the device is attached.

IOReturn ( *GetBusFrameNumber)(
    void *self,
    UInt64 *frame,
    AbsoluteTime *atTime);

Parameters

self: Pointer to the IOUSBDeviceInterface.
frame: Pointer to UInt64 to hold the frame number.
atTime: Pointer to a returned AbsoluteTime, which is the system time ("wall time") when the frame number register was read. This system time could be the time at the beginning, middle, or end of the given frame.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetConfiguration

Returns the currently selected configuration in the device.

IOReturn ( *GetConfiguration)(
    void *self,
    UInt8 *configNum);

Parameters

self: Pointer to the IOUSBDeviceInterface.
configNum: Pointer to UInt8 to hold the configuration value.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetConfigurationDescriptorPtr

Returns a pointer to a configuration descriptor for a given index.

IOReturn ( *GetConfigurationDescriptorPtr)(
    void *self,
    UInt8 configIndex,
    IOUSBConfigurationDescriptorPtr *desc);

Parameters

self: Pointer to the IOUSBDeviceInterface.
configIndex: The index (zero based) of the desired config descriptor.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

Note that this will point to the data as received from the USB bus and hence will be in USB bus order (i.e. little endian). The device does not have to be open to use this function.

GetDeviceAddress

Returns the address of the device on its bus.

IOReturn ( *GetDeviceAddress)(
    void *self,
    USBDeviceAddress *addr);

Parameters

self: Pointer to the IOUSBDeviceInterface.
addr: Pointer to USBDeviceAddress to hold the result.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceAsyncEventSource

Returns the CFRunLoopSourceRef for this IOService instance.

CFRunLoopSourceRef ( *GetDeviceAsyncEventSource)(
    void *self);

Parameters

self: Pointer to the IOUSBDeviceInterface.

Return Value

Returns the run loop source if one has been created, 0 otherwise.

GetDeviceAsyncPort

Returns the mach_port_t port for this IOService instance.

mach_port_t ( *GetDeviceAsyncPort)(
    void *self);

Parameters

self: Pointer to the IOUSBDeviceInterface.

Return Value

Returns the port if one exists, 0 otherwise.

GetDeviceBusPowerAvailable

Returns the power available to the device.

IOReturn ( *GetDeviceBusPowerAvailable)(
    void *self,
    UInt32 *powerAvailable);

Parameters

self: Pointer to the IOUSBDeviceInterface.
powerAvailable: Pointer to UInt32 to hold the power available (in 2 mA increments).

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceClass

Returns the USB Class (bDeviceClass) of the device.

IOReturn ( *GetDeviceClass)(
    void *self,
    UInt8 *devClass);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devClass: Pointer to UInt8 to hold the device Class.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceProduct

Returns the USB Product ID (idProduct) of the device.

IOReturn ( *GetDeviceProduct)(
    void *self,
    UInt16 *devProduct);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devProduct: Pointer to UInt16 to hold the ProductID.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceProtocol

Returns the USB Protocol (bDeviceProtocol) of the interface.

IOReturn ( *GetDeviceProtocol)(
    void *self,
    UInt8 *devProtocol);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devProtocol: Pointer to UInt8 to hold the device Protocol.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceReleaseNumber

Returns the Device Release Number (bcdDevice) of the device.

IOReturn ( *GetDeviceReleaseNumber)(
    void *self,
    UInt16 *devRelNum);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devRelNum: Pointer to UInt16 to hold the Device Release Number.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceSpeed

Returns the speed of the device.

IOReturn ( *GetDeviceSpeed)(
    void *self,
    UInt8 *devSpeed);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devSpeed: Pointer to UInt8 to hold the speed (kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, or kUSBDeviceSpeedHigh).

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceSubClass

Returns the USB Subclass (bDeviceSubClass) of the device.

IOReturn ( *GetDeviceSubClass)(
    void *self,
    UInt8 *devSubClass);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devSubClass: Pointer to UInt8 to hold the device Subclass.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetDeviceVendor

Returns the USB Vendor ID (idVendor) of the device.

IOReturn ( *GetDeviceVendor)(
    void *self,
    UInt16 *devVendor);

Parameters

self: Pointer to the IOUSBDeviceInterface.
devVendor: Pointer to UInt16 to hold the vendorID.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

GetLocationID

Returns the location ID.

IOReturn ( *GetLocationID)(
    void *self,
    UInt32 *locationID);

Parameters

self: Pointer to the IOUSBDeviceInterface.
locationID: Pointer to UInt32 to hold the location ID.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The location ID is a 32 bit number which is unique among all USB devices in the system, and which will not change on a system reboot unless the topology of the bus itself changes. The device does not have to be open to use this function.

GetNumberOfConfigurations

Returns the number of supported configurations in this device.

IOReturn ( *GetNumberOfConfigurations)(
    void *self,
    UInt8 *numConfig);

Parameters

self: Pointer to the IOUSBDeviceInterface.
numConfig: Pointer to UInt8 to hold the number of configurations.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

The device does not have to be open to use this function.

ResetDevice

Tells the IOUSBFamily to issue a reset to the device.

IOReturn ( *ResetDevice)(
    void *self);

Parameters

self: Pointer to the IOUSBDeviceInterface.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the device is not open for exclusive access.

Discussion

It will not reenumerate the device, which means that the cached device descriptor values will not be updated after the reset. (If you want the IOUSBFamily to reload the cached values, use the call USBDeviceReEnumerate ). Prior to version 1.8.5 of the IOUSBFamily, this call also sent a message to all clients of the IOUSBDevice (IOUSBInterfaces and their drivers). The device must be open to use this function.

This behavior was eliminated in version 1.8.5 of the IOUSBFamily.

SetConfiguration

Sets the configuration in the device.

IOReturn ( *SetConfiguration)(
    void *self,
    UInt8 configNum);

Parameters

self: Pointer to the IOUSBDeviceInterface.
configNum: The value of the desired configuration (from IOUSBConfigurationDescriptor.bConfigurationValue).

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the device is not open for exclusive access.

Discussion

Note that setting the configuration causes any existing IOUSBInterface objects attached to the IOUSBDevice to be destroyed, and all of the interfaces in the new configuration to be instantiated as new IOUSBInterface objects. The device must be open to use this function.

USBDeviceClose

Closes the task's connection to the IOUSBDevice.

IOReturn ( *USBDeviceClose)(
    void *self);

Parameters

self: Pointer to the IOUSBDeviceInterface.

Return Value

Returns kIOReturnSuccess if successful, some other mach error if the connection is no longer valid.

Discussion

Releases the client's exclusive access to the IOUSBDevice.

USBDeviceOpen

Opens the IOUSBDevice for exclusive access.

IOReturn ( *USBDeviceOpen)(
    void *self);

Parameters

self: Pointer to the IOUSBDeviceInterface.

Return Value

Returns kIOReturnExclusiveAccess if some other task has the device opened already, kIOReturnError if the connection with the kernel cannot be established or kIOReturnSuccess if successful.

Discussion

Before the client can issue commands that change the state of the device, it must have succeeded in opening the device. This establishes an exclusive link between the client's task and the actual device.

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: 2009-02-23