Functions

# 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 IOUSBDeviceInterfaceXXX structure which shipped with subsequent versions of Mac OS X. Functions which were not available in the original API are 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 delivers 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 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.

#### 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 asynchronous 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 asynchronous 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.

### GetBusMicroFrameNumber

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

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

>      IOReturn(*GetBusMicroFrameNumber)(void *self, UInt64 *microFrame, AbsoluteTime *atTime);

The device does not have to be open.

#### Parameters

Name | Description
--- | ---
`self` | Pointer to the IOUSBDeviceInterface
`microFrame` | Pointer to UInt64 to hold the microframe number.
`atTime` | Pointer to an AbsoluteTime, which should be within 1ms of the time when the bus frame number was acquired.

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

     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 (bDeviceClass) 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 USB Product ID (idProduct) 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 (bDeviceProtocol) 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 Device Release Number (bcdDevice) 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 Device 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, kUSBDeviceSpeedFull or kUSBDeviceSpeedHigh)

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

### GetDeviceSubClass

Abstract: Return the USB Subclass (bDeviceSubClass) 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 USB Vendor ID (idVendor) 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.

### GetIOUSBLibVersion

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

Abstract: Returns the version of the IOUSBLib and the version of the IOUSBFamily.

>      IOReturn(*GetIOUSBLibVersion)(void *self, NumVersion *ioUSBLibVersion, NumVersion *usbFamilyVersion);

The device does not have to be open.

#### Parameters

Name | Description
--- | ---
`self` | Pointer to the IOUSBDeviceInterface
`ioUSBLibVersion` | Pointer to a NumVersion structure that on return will contain the version of the IOUSBLib.
`usbFamilyVersion` | Pointer to a NumVersion structure that on return will contain the version of the IOUSBFamily.

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, and which 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-2003 Apple Computer, Inc. — (Last Updated May 7, 2003)