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

---

IOUSBInterfaceInterface190

Overview

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

Discussion

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

---

Functions

ClearPipeStallBothEnds

Equivalent to ClearPipeStall .

GetBandwidthAvailable

Returns the amount of bandwidth available (in bytes per 1ms frame) on the bus for allocation to isochronous pipes.

GetEndpointProperties

Returns the transfer type, max packet size, and interval of a specified endpoint, whether or not the endpoint has a pipe currently established.

SetPipePolicy

Changes the size of the reserved bandwidth for an isochronous pipe.

---

ClearPipeStallBothEnds

---

Equivalent to ClearPipeStall.

IOReturn ( *ClearPipeStallBothEnds)(
    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 is equivalent to ClearPipeStall except that it also attempts to clear the halt and toggle bits on the device's endpoint for the pipe by sending a ClearFeature(ENDPOINT_HALT) to the default control pipe in the device, specifying the endpoint for the pipe represented by pipeRef. For most devices, this resynchronizes the data toggle between the two endpoints to ensure that there is no loss of data.

Availability

This function is only available with IOUSBInterfaceInterface190 and above.

---

GetBandwidthAvailable

---

Returns the amount of bandwidth available (in bytes per 1ms frame) on the bus for allocation to isochronous pipes.

IOReturn ( *GetBandwidthAvailable)(
    void *self,
    UInt32 *bandwidth);  

Parameters

self

Pointer to the IOUSBInterfaceInterface.

bandwidth

Pointer to UInt32 to hold the amount of bandwidth available (in bytes per 1ms frame).

Return Value

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

Discussion

This function is useful for determining the correct AltInterface setting as well as for using SetPipePolicy .

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

Availability

This function is only available with IOUSBInterfaceInterface190 and above.

---

GetEndpointProperties

---

Returns the transfer type, max packet size, and interval of a specified endpoint, whether or not the endpoint has a pipe currently established.

IOReturn ( *GetEndpointProperties)(
    void *self,
    UInt8 alternateSetting,
    UInt8 endpointNumber,
    UInt8 direction,
    UInt8 *transferType,
    UInt16 *maxPacketSize,
    UInt8 *interval);  

Parameters

self

Pointer to the IOUSBInterfaceInterface.

alternateSetting

Specifies the alternate setting within the current interface.

endpointNumber

Specifies the desired endpoint number.

direction

Specifies the desired direction.

transferType

Pointer to UInt8 to hold the endpoint's transfer type (kUSBControl, kUSBIsoc, etc).

maxPacketSize

Pointer to UInt16 to hold the maxPacketSize of the endpoint.

interval

Pointer to UInt8 to hold the polling interval for interrupt endpoints.

Return Value

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

Discussion

This function may be useful for determining which alternate interface to select when trying to balance bandwidth allocations among isochronous pipes.

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

Availability

This function is only available with IOUSBInterfaceInterface190 and above.

---

SetPipePolicy

---

Changes the size of the reserved bandwidth for an isochronous pipe.

IOReturn ( *SetPipePolicy)(
    void *self,
    UInt8 pipeRef,
    UInt16 maxPacketSize,
    UInt8 maxInterval);  

Parameters

self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints ).

maxPacketSize

The desired size for the isochronous pipe. Valid values are 0 through the maxPacketSize defined in the endpoint descriptor.

maxInterval

Currently ignored.

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. May also return kIOReturnNoBandwidth if there is not enough bandwidth available on the bus, or kIOReturnBadArgument if the desired maxPacketSize is outside of the allowed range.

Discussion

The pipe may be made smaller or larger (up to the maxPacketSize specified in the endpoint descriptor). When an interface is first opened, all pipes are created with their descriptor-supplied maxPacketSize. For isochronous pipes, if there is not enough bandwidth on the bus to allocate to the pipe, the pipe is created with a reserved bandwidth of zero. Any attempts to transfer data on a pipe with zero bandwidth will result in a kIOReturnNoBandwidth error. The pipe must first be given some bandwidth using this call.

The interface must be open for the pipe to exist.

Availability

This function is only available with IOUSBInterfaceInterface190 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