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

IOUSBInterfaceInterface

Declared In:

Overview

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

Discussion

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

Functions

AbortPipe: Aborts any outstanding transactions on the pipe with status kIOReturnAborted.
ClearPipeStall: Clears the halted bit and the data toggle bit on the pipe's endpoint in the controller.
ControlRequest: Sends a USB request on a control pipe.
ControlRequestAsync: Sends an asynchronous USB request on a control pipe.
CreateInterfaceAsyncEventSource: Creates a run loop source for delivery of all asynchronous notifications on this device.
CreateInterfaceAsyncPort: Creates and registers a mach_port_t for asynchronous communications.
GetAlternateSetting: Returns the alternate setting currently selected in this interface.
GetBusFrameNumber: Gets the current frame number of the bus to which the interface and its device are attached.
GetConfigurationValue: Returns the current configuration value set in the device (the interface will be part of that configuration.)
GetDevice: Returns the device of which this interface is part.
GetDeviceProduct: Returns the USB Product ID (idProduct) of the device of which this interface is a part.
GetDeviceReleaseNumber: Returns the Device Release Number (bcdDevice) of the device of which this interface is a part.
GetDeviceVendor: Returns the USB Vendor ID (idVendor) of the device of which this interface is a part.
GetInterfaceAsyncEventSource: Returns the CFRunLoopSourceRef for this IOService instance.
GetInterfaceAsyncPort: Returns the mach_port_t port for this IOService instance.
GetInterfaceClass: Returns the USB Class of the interface (bInterfaceClass).
GetInterfaceNumber: Returns the interface number (zero-based index) of this interface within the current configuration of the device.
GetInterfaceProtocol: Returns the USB Protocol of the interface (bInterfaceProtocol).
GetInterfaceSubClass: Returns the USB Subclass of the interface (bInterfaceSubClass).
GetLocationID: Returns the location ID.
GetNumEndpoints: Returns the number of endpoints in this interface, excluding the control interface (endpoint 0).
GetPipeProperties: Gets the properties for a pipe.
GetPipeStatus: Gets the current status of a pipe.
ReadIsochPipeAsync: Performs a read on an ISOCHRONOUS pipe.
ReadPipe: Reads data on a BULK IN or an INTERRUPT pipe.
ReadPipeAsync: Performs an asynchronous read on a BULK IN or an INTERRUPT pipe.
ResetPipe: Equivalent to ClearPipeStall .
SetAlternateInterface: Changes the AltInterface setting.
USBInterfaceClose: Closes the task's connection to the IOUSBInterface.
USBInterfaceOpen: Opensthe IOUSBInterface for exclusive access.
WriteIsochPipeAsync: Performs an asynchronous write on an ISOCHRONOUS pipe.
WritePipe: Writes data on a BULK OUT or INTERRUPT OUT pipe.
WritePipeAsync: Performs an asynchronous write on a BULK OUT or INTERRUPT OUT pipe.

AbortPipe

Aborts any outstanding transactions on the pipe with status kIOReturnAborted.

IOReturn ( *AbortPipe)(
    void *self,
    UInt8 pipeRef);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints).

Return Value

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

Discussion

If there are outstanding asynchronous transactions on the pipe, the callbacks will happen. Note that this command will also clear the halted bit on the endpoint in the controller, but will NOT clear the data toggle bit. If you want to clear the data toggle bit as well, see ClearPipeStall or ClearPipeStallBothEnds for more information. The interface must be open for the pipe to exist.

ClearPipeStall

Clears the halted bit and the data toggle bit on the pipe's endpoint in the controller.

IOReturn ( *ClearPipeStall)(
    void *self,
    UInt8 pipeRef);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).

Return Value

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

Discussion

This function also returns any outstanding transactions on the pipe with status kIOUSBTransactionReturned. If there are outstanding asynchronous transactions on the pipe, the callbacks will happen. The data toggle may need to be resynchronized. The driver may handle this by sending a ClearFeature(ENDPOINT_HALT) to the default control pipe, specifying the device's endpoint for this pipe. See also ClearPipeStallBothEnds.

ControlRequest

Sends a USB request on a control pipe.

IOReturn ( *ControlRequest)(
    void *self,
    UInt8 pipeRef,
    IOUSBDevRequest *req);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index of the control pipe to use. Use zero for the default control pipe on the device.
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 interface is not open for exclusive access.

Discussion

If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.

ControlRequestAsync

Sends an asynchronous USB request on a control pipe.

IOReturn ( *ControlRequestAsync)(
    void *self,
    UInt8 pipeRef,
    IOUSBDevRequest *req,
    IOAsyncCallback1 callback,
    void *refCon);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index of the control pipe to use. Use zero for the default control pipe on the device.
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 interface is not open for exclusive access, or kIOUSBNoAsyncPortErr if no Async port has been created for this interface.

Discussion

Use pipeRef=0 for the default device control pipe. If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.

CreateInterfaceAsyncEventSource

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

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

Parameters

self: Pointer to the IOUSBInterfaceInterface.
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 failed.

Discussion

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). This routine wraps that port with the appropriate routing code so that the completion notifications can be automatically routed through the client's CFRunLoop.

CreateInterfaceAsyncPort

Creates and registers a mach_port_t for asynchronous communications.

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

Parameters

self: Pointer to the IOUSBInterfaceInterface.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if failed.

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.

GetAlternateSetting

Returns the alternate setting currently selected in this interface.

IOReturn ( *GetAlternateSetting)(
    void *self,
    UInt8 *intfAltSetting);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
intfAltSetting: Pointer to UInt8 to hold the alternate setting value.

Return Value

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

Discussion

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

GetBusFrameNumber

Gets the current frame number of the bus to which the interface and its device are attached.

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

Parameters

self: Pointer to the IOUSBInterfaceInterface.
frame: Pointer to UInt64 to hold the frame number.
atTime: Pointer to an AbsoluteTime, which should be within 1ms of the time when the bus frame number was attained.

Return Value

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

Discussion

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

GetConfigurationValue

Returns the current configuration value set in the device (the interface will be part of that configuration.)

IOReturn ( *GetConfigurationValue)(
    void *self,
    UInt8 *configVal);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
configVal: 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 interface does not have to be open to use this function.

GetDevice

Returns the device of which this interface is part.

IOReturn ( *GetDevice)(
    void *self,
    io_service_t *device);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
device: Pointer to io_service_t to hold the result.

Return Value

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

Discussion

The interface does not have to be open to use this function. The returned device can be used to create a CFPlugin to talk to the device.

GetDeviceProduct

Returns the USB Product ID (idProduct) of the device of which this interface is a part.

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

Parameters

self: Pointer to the IOUSBInterfaceInterface.
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 interface does not have to be open to use this function.

GetDeviceReleaseNumber

Returns the Device Release Number (bcdDevice) of the device of which this interface is a part.

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

Parameters

self: Pointer to the IOUSBInterfaceInterface.
devRelNum: Pointer to UInt16 to hold the Release Number.

Return Value

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

Discussion

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

GetDeviceVendor

Returns the USB Vendor ID (idVendor) of the device of which this interface is a part.

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

Parameters

self: Pointer to the IOUSBInterfaceInterface.
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 interface does not have to be open to use this function.

GetInterfaceAsyncEventSource

Returns the CFRunLoopSourceRef for this IOService instance.

CFRunLoopSourceRef ( *GetInterfaceAsyncEventSource)(
    void *self);

Parameters

self: Pointer to the IOUSBInterfaceInterface.

Return Value

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

GetInterfaceAsyncPort

Returns the mach_port_t port for this IOService instance.

mach_port_t ( *GetInterfaceAsyncPort)(
    void *self);

Parameters

self: Pointer to the IOUSBInterfaceInterface.

Return Value

Returns the port if one exists, 0 otherwise.

GetInterfaceClass

Returns the USB Class of the interface (bInterfaceClass).

IOReturn ( *GetInterfaceClass)(
    void *self,
    UInt8 *intfClass);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
intfClass: Pointer to UInt8 to hold the interface Class.

Return Value

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

Discussion

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

GetInterfaceNumber

Returns the interface number (zero-based index) of this interface within the current configuration of the device.

IOReturn ( *GetInterfaceNumber)(
    void *self,
    UInt8 *intfNumber);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
intfNumber: Pointer to UInt8 to hold the interface number.

Return Value

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

Discussion

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

GetInterfaceProtocol

Returns the USB Protocol of the interface (bInterfaceProtocol).

IOReturn ( *GetInterfaceProtocol)(
    void *self,
    UInt8 *intfProtocol);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
intfProtocol: Pointer to UInt8 to hold the interface Protocol.

Return Value

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

Discussion

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

GetInterfaceSubClass

Returns the USB Subclass of the interface (bInterfaceSubClass).

IOReturn ( *GetInterfaceSubClass)(
    void *self,
    UInt8 *intfSubClass);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
intfSubClass: Pointer to UInt8 to hold the interface Subclass.

Return Value

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

Discussion

The interface 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 IOUSBInterfaceInterface.
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 interface does not have to be open to use this function.

GetNumEndpoints

Returns the number of endpoints in this interface, excluding the control interface (endpoint 0).

IOReturn ( *GetNumEndpoints)(
    void *self,
    UInt8 *intfNumEndpoints);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
intfNumEndpoints: Pointer to UInt8 to hold the number of endpoints.

Return Value

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

Discussion

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

GetPipeProperties

Gets the properties for a pipe.

IOReturn ( *GetPipeProperties)(
    void *self,
    UInt8 pipeRef,
    UInt8 *direction,
    UInt8 *number,
    UInt8 *transferType,
    UInt16 *maxPacketSize,
    UInt8 *interval);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints).
direction: Pointer to an UInt8 to get the direction of the pipe.
number: Pointer to an UInt8 to get the pipe number.
transferType: Pointer to an UInt8 to get the transfer type of the pipe.
maxPacketSize: Pointer to an UInt16 to get the maxPacketSize of the pipe.
interval: Pointer to an UInt8 to get the interval for polling the pipe for data (in milliseconds).

Return Value

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

Discussion

Once an interface is opened, all of the pipes in that interface get created by the kernel. The number of pipes can be retrieved by GetNumEndpoints. The client can then get the properties of any pipe using an index of 1 to GetNumEndpoints. Pipe 0 is the default control pipe in the device.

GetPipeStatus

Gets the current status of a pipe.

IOReturn ( *GetPipeStatus)(
    void *self,
    UInt8 pipeRef);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).

Return Value

Returns kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Otherwise, the status of the pipe is returned. Returns kIOUSBPipeStalled if the pipe is stalled. See ClearPipeStall or ClearPipeStallBothEnds for more information.

Discussion

The interface must be open for the pipe to exist.

ReadIsochPipeAsync

Performs a read on an ISOCHRONOUS pipe.

IOReturn ( *ReadIsochPipeAsync)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt64 frameStart,
    UInt32 numFrames,
    IOUSBIsocFrame *frameList, 
    IOAsyncCallback1 callback,
    void *refcon);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
frameStart: The bus frame number on which to start the read (obtained from GetBusFrameNumber).
numFrames: The number of frames for which to transfer data.
frameList: A pointer to an array of IOUSBIsocFrame structures describing the frames.
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, or kIOReturnNotOpen if the interface is not open for exclusive access.

Discussion

The interface must be open for the pipe to exist.

ReadPipe

Reads data on a BULK IN or an INTERRUPT pipe.

IOReturn ( *ReadPipe)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 *size);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
size: On entry: a pointer to the size of the buffer pointed to by buf. On exit: a pointer to the number of bytes actually read from the device.

Return Value

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

Discussion

The interface must be open for the pipe to exist.

ReadPipeAsync

Performs an asynchronous read on a BULK IN or an INTERRUPT pipe.

IOReturn ( *ReadPipeAsync)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 size,
    IOAsyncCallback1 callback,
    void *refcon);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
size: The size of the buffer pointed to by buf.
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, or kIOReturnNotOpen if the interface is not open for exclusive access.

Discussion

The interface must be open for the pipe to exist.

ResetPipe

Equivalent to ClearPipeStall.

IOReturn ( *ResetPipe)(
    void *self,
    UInt8 pipeRef);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).

Return Value

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

Discussion

The interface must be open for the pipe to exist.

SetAlternateInterface

Changes the AltInterface setting.

IOReturn ( *SetAlternateInterface)(
    void *self,
    UInt8 alternateSetting);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
alternateSetting: The new alternate setting for the interface.

Return Value

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

Discussion

The interface must be open to use this function.

USBInterfaceClose

Closes the task's connection to the IOUSBInterface.

IOReturn ( *USBInterfaceClose)(
    void *self);

Parameters

self: Pointer to the IOUSBInterfaceInterface.

Return Value

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

Discussion

Releases the client's exclusive access to the IOUSBInterface.

USBInterfaceOpen

Opensthe IOUSBInterface for exclusive access.

IOReturn ( *USBInterfaceOpen)(
    void *self);

Parameters

self: Pointer to the IOUSBInterfaceInterface.

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 transfer data to and from the interface, it must have succeeded in opening the interface. This establishes an exclusive link between the client's task and the actual interface device. Opening the interface causes pipes to be created on each endpoint contained in the interface. If the interface contains isochronous endpoints, an attempt is made to allocate bandwidth on the bus for each of those pipes. If there is not enough bandwidth available, an isochronous pipe may be created with a bandwidth of zero. The software must then call SetPipePolicy to change the size of that pipe before it can be used for I/O.

WriteIsochPipeAsync

Performs an asynchronous write on an ISOCHRONOUS pipe.

IOReturn ( *WriteIsochPipeAsync)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt64 frameStart,
    UInt32 numFrames,
    IOUSBIsocFrame *frameList, 
    IOAsyncCallback1 callback,
    void *refcon);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
frameStart: The bus frame number on which to start the write (obtained from GetBusFrameNumber).
numFrames: The number of frames for which to transfer data.
frameList: A pointer to an array of IOUSBIsocFrame structures describing the frames.
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, or kIOReturnNotOpen if the interface is not open for exclusive access.

Discussion

The interface must be open for the pipe to exist.

WritePipe

Writes data on a BULK OUT or INTERRUPT OUT pipe.

IOReturn ( *WritePipe)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 size);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
size: The size of the data buffer.

Return Value

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

Discussion

The interface must be open for the pipe to exist.

WritePipeAsync

Performs an asynchronous write on a BULK OUT or INTERRUPT OUT pipe.

IOReturn ( *WritePipeAsync)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 size,
    IOAsyncCallback1 callback,
    void *refcon);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
size: The size of the buffer pointed to by buf.
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, or kIOReturnNotOpen if the interface is not open for exclusive access.

Discussion

The interface must be open for the pipe to exist.

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