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

IOUSBInterfaceInterface182

Inherits from:	IOUSBInterfaceInterface
Declared In:	IOUSBLib.h

Overview

The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.8.2 and above.

Discussion

The functions listed here include all of the functions defined for the IOUSBInterfaceInterface and some new functions that are available on Mac OS X version 10.0.4 and later.

Functions

ControlRequestAsyncTO: Sends an asynchronous USB request on a control pipe.
ControlRequestTO: Sends a USB request on a control pipe.
ReadPipeAsyncTO: Performs an asynchronous read on a BULK IN pipe, with specified timeout values.
ReadPipeTO: Performs a read on a BULK IN pipe, specifying timeout values.
USBInterfaceGetStringIndex: Returns the string index in the interface descriptor.
WritePipeAsyncTO: Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.
WritePipeTO: Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.

ControlRequestAsyncTO

Sends an asynchronous USB request on a control pipe.

IOReturn ( *ControlRequestAsyncTO)(
    void *self,
    UInt8 pipeRef,
    IOUSBDevRequestTO *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 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.

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 IOUSBDevRequestTO structure allows the client to specify timeout values for this request. 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.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

ControlRequestTO

Sends a USB request on a control pipe.

IOReturn ( *ControlRequestTO)(
    void *self,
    UInt8 pipeRef,
    IOUSBDevRequestTO *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 IOUSBDevRequestTO 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

The IOUSBDevRequestTO structure allows the client to specify timeout values for this request. 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.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

ReadPipeAsyncTO

Performs an asynchronous read on a BULK IN pipe, with specified timeout values.

IOReturn ( *ReadPipeAsyncTO)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 size,
    UInt32 noDataTimeout,
    UInt32 completionTimeout,
    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.
noDataTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.
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. Returns kIOReturnBadArgument if timeout values are specified for an interrupt pipe.

Discussion

The interface must be open for the pipe to exist.

If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds .

Timeouts do not apply to interrupt pipes, so you should use the ReadPipeAsync call to perform an asynchronous read from an interrupt pipe.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

ReadPipeTO

Performs a read on a BULK IN pipe, specifying timeout values.

IOReturn ( *ReadPipeTO)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 *size,
    UInt32 noDataTimeout,
    UInt32 completionTimeout);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
pipeRef: Index for the desired pipe (1 - GetNumEndpoints ).
buf: Buffer to hold the data.
size: Pointer to the size of the buffer pointed to by buf.
noDataTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.

Return Value

Discussion

The interface must be open for the pipe to exist.

If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds .

Timeouts do not apply to interrupt pipes, so you should use the ReadPipe call to perform a read from an interrupt pipe.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

USBInterfaceGetStringIndex

Returns the string index in the interface descriptor.

IOReturn ( *USBInterfaceGetStringIndex)(
    void *self,
    UInt8 *si);

Parameters

self: Pointer to the IOUSBInterfaceInterface.
si: Pointer to UInt8 to hold the string index.

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.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

WritePipeAsyncTO

Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.

IOReturn ( *WritePipeAsyncTO)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 size,
    UInt32 noDataTimeout,
    UInt32 completionTimeout,
    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.
noDataTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.
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.

If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

WritePipeTO

Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.

IOReturn ( *WritePipeTO)(
    void *self,
    UInt8 pipeRef,
    void *buf,
    UInt32 size,
    UInt32 noDataTimeout,
    UInt32 completionTimeout);

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.
noDataTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout: Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.

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.

If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.

Availability: This function is only available with IOUSBInterfaceInterface182 and above.

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