IOUSBDeviceInterface Functions

The function pointers described here are accessed using any of the IOUSBDeviceInterface structures. This includes the original IOUSBDeviceInterface structure which shipped with the original Mac OS X, as well as IOUSBDeviceInterface182 structure which shipped with Mac OS X 10.0.4 (available as a Software Update). Functions which were not available in the original API will be documented as such.


CreateDeviceAsyncEventSource

Abstract: Create a run loop source for delivery of all asynchronous notifications on this device.

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

The Mac OS X kernel does not spawn a thread to callback to the client. Instead it deliveres completion notifications on a mach port (see createInterfaceAsyncPort below). This routine wraps that port with the appropriate routing code so that the completion notifications can be automatically routed through the clients CFRunLoop.

Parameters

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

Result: Returns kIOReturnSuccess if successful or a kern_return_t if failed.


CreateDeviceAsyncPort

Abstract: Create and register a mach_port_t for asynchronous communications.

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

The Mac OS X kernel does not spawn a thread to callback to the client. Instead it deliveres 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.

Parameters

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

Result: Returns kIOReturnSuccess if successful or a kern_return_t if failed.


CreateInterfaceIterator

Abstract: 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);

The device does not have to be open.

Parameters

Name Description
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.

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


DeviceRequest

Abstract: Sends a USB request on the default control pipe.

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

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.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
req Pointer to an IOUSBDevRequest containing the request.

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


DeviceRequestAsync

Abstract: Sends an asyncronous USB request on the default control pipe.

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

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.

Parameters

Name Description
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.

Result: 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.


DeviceRequestAsyncTO

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Sends an asyncronous USB request on the default control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request.

IOReturn(*DeviceRequestAsyncTO)(void *self, IOUSBDevRequestTO *req, IOAsyncCallback1 callback, void *refCon);

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.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
req Pointer to an IOUSBDevRequestTO 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.

Result: 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.


DeviceRequestTO

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Sends a USB request on the default control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request.

IOReturn(*DeviceRequestTO)(void *self, IOUSBDevRequestTO *req);

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.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
req Pointer to an IOUSBDevRequestTO containing the request.

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


GetBusFrameNumber

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

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
frame Pointer to UInt64 to hold the frame number.
atTime Pointer to a returned AbsoluteTime, which should be within 1ms of the time when the bus frame number was attained.

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


GetConfiguration

Abstract: Return the currently selected configuration in the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
configNum Pointer to UInt8 to hold the configuration value.

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


GetConfigurationDescriptorPtr

Abstract: Return a pointer to a configuration descriptor for a given index.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
configIndex The index (zero based) of the desired config descriptor.
desc Pointer to an IOUSBConfigurationDescriptorPtr to hold the result.

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


GetDeviceAddress

Abstract: Return the address of the device on its bus.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
addr Pointer to USBDeviceAddress to hold the result.

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


GetDeviceAsyncEventSource

Abstract: Return the CFRunLoopSourceRef for this IOService instance.

CFRunLoopSourceRef(*GetDeviceAsyncEventSource)(void *self);

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

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


GetDeviceAsyncPort

Abstract: Return the mach_port_t port for this IOService instance.

mach_port_t(*GetDeviceAsyncPort)(void *self);

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

Result: Returns the port if one exists, 0 otherwise.


GetDeviceBusPowerAvailable

Abstract: Return the power available to the device.

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

The device does not have to be open.

Parameters

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

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


GetDeviceClass

Abstract: Return the USB Class of the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devClass Pointer to UInt8 to hold the device Class

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


GetDeviceProduct

Abstract: Return the ProductID of the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devProduct Pointer to UInt16 to hold the ProductID

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


GetDeviceProtocol

Abstract: Return the USB Protocol of the interface.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devProtocol Pointer to UInt8 to hold the device Protocol

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


 

GetDeviceReleaseNumber

Abstract: Return the Release Number of the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devRelNum Pointer to UInt16 to hold the Release Number

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


GetDeviceSpeed

Abstract: Return the speed of the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devSpeed Pointer to UInt8 to hold the speed (kUSBDeviceSpeedLow or kUSBDeviceSpeedFull)

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


GetDeviceSubClass

Abstract: Return the USB Subclass of the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devSubClass Pointer to UInt8 to hold the device Subclass

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


GetDeviceVendor

Abstract: Return the VendorID of the device.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
devVendor Pointer to UInt16 to hold the vendorID

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


GetLocationID

Abstract: Return the location ID. This is a 32 bit number which is unique among all USB devices in the system, andwhich will not change on a system reboot unless the topology of the bus itself changes.

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

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
locationID Pointer to UInt32 to hold the location ID.

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


GetNumberOfConfigurations

Abstract: Return the number of supported configurations in this device.

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

The device does not have to be open.

Parameters

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

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


ResetDevice

Abstract: Tells the IOUSBFamily to issue a reset to the device. 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). This behavior was eliminated with version 1.8.5 of the IOUSBFamily.

IOReturn(*ResetDevice)(void *self);

The device must be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

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


SetConfiguration

Abstract: Sets the configuration in the device. 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.

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

The device must be open.

Parameters

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

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


USBDeviceAbortPipeZero

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Abort a transaction on the default control pipe.

IOReturn(*USBDeviceAbortPipeZero)(void *self);

The device must be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

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


USBDeviceClose

Abstract: Close the task's connection to the IOUSBDevice.

IOReturn(*USBDeviceClose)(void *self);

Release the clients exclusive access to the IOUSBDevice.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

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


USBDeviceOpen

Abstract: Open up the IOUSBDevice for exclusive access.

IOReturn(*USBDeviceOpen)(void *self);

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

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

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


USBDeviceOpenSeize

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Open up the IOUSBDevice for exclusive access. If another client has the device opened, an attempt is made to get that client to close it before returning.

IOReturn(*USBDeviceOpenSeize)(void *self);

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

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface

Result: Returns kIOReturnExclusiveAccess if some other task has the device opened already and refuses to close it, kIOReturnError if the connection with the kernel can not be established or kIOReturnSuccess if successful.


USBDeviceReEnumerate

Note: This function is only available with IOUSBDeviceInterface187 and above.

Abstract: Tells the IOUSBFamily to reenumerate the device. This will send a terminate message to all clients of the IOUSBDevice (such as IOUSBInterfaces and their drivers, as well as the current User Client), emulating an unplug of the device. The IOUSBFamily will then enumerate the device as if it had just been plugged in. This call should be used by clients wishing to take advantage of the Device Firmware Update Class specification.

IOReturn(*USBDeviceReEnumerate)(void *self,UInt32 options);

The device must be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
options A UInt32 reserved for future use. Ignored in current implementation. Set to zero.

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


USBDeviceSuspend

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Tell the USB Family to either suspend or resume the port to which a device is attached.

IOReturn(*USBDeviceSuspend)(void *self, Boolean suspend);

The device must be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
suspend TRUE to cause the port to be suspended, FALSE to cause it to be resumed

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


USBGetManufacturerStringIndex

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Return the manufacturer string index in the device descriptor.

IOReturn(*USBGetManufacturerStringIndex)(void *self, UInt8 *msi);

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
msi Pointer to UInt8 to hold the string index

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


USBGetProductStringIndex

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Return the product string index in the device descriptor.

IOReturn(*USBGetProductStringIndex)(void *self, UInt8 *psi);

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
psi Pointer to UInt8 to hold the string index

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


USBGetSerialNumberStringIndex

Note: This function is only available with IOUSBDeviceInterface182 and above.

Abstract: Return the serial number string index in the device descriptor.

IOReturn(*USBGetSerialNumberStringIndex)(void *self, UInt8 *snsi);

The device does not have to be open.

Parameters

Name Description
self Pointer to the IOUSBDeviceInterface
snsi Pointer to UInt8 to hold the string index

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

 


© 2001 Apple Computer, Inc. — (Last Updated Nov 7, 2001)