Mac Developer Library

Developer

IOUSBPipe Class Reference

Options
Deployment Target:

On This Page
Language:

IOUSBPipe

The object representing an open pipe for a device. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Declaration

    C++

    virtual IOReturn Abort( void);

    Discussion

    This method causes all outstanding I/O on a pipe to complete with return code kIOReturnAborted. It clears the halted bit but does NOT clear the toggle bit on the endpoint in the controller. If you wish to clear the toggle bit, see ClearPipeStall

    Import Statement

  • Declaration

    C++

    virtual IOReturn ClearPipeStall( boolwithDeviceRequest);

    Parameters

    withDeviceRequest

    if true, a ClearFeature(ENDPOINT_HALT) is sent to the appropriate endpoint on the device after the transactions on the controllers endpoint are returned and the toggle bit on the controllers endpoint is cleared. if this parameter is false, then this is equivalent to the pre-1.9 API. This means that the endpoint on the controller is cleared, but no DeviceRequest is sent to the device's endpoint.

    Discussion

    AVAILABLE ONLY IN VERSION 1.9 AND ABOVE This method causes all outstanding I/O on a pipe to complete with return code kIOUSBTransactionReturned. It also clears both the halted bit and the toggle bit on the endpoint in the controller. The driver may need to reset the data toggle within the device to avoid losing any data. If the device correctly handles the ClearFeature(ENDPOINT_HALT) device request, then this API will handle that by sending the correct request to the device.

    Import Statement

  • Declaration

    C++

    virtual IOReturn ClearStall( void);

    Discussion

    This method is equivalent to ClearPipeStall(false). This method is available before version 1.9.

    Import Statement

  • Declaration

    C++

    virtual IOReturn ControlRequest( IOUSBDevRequestDesc *request, IOUSBCompletion *completion = 0);

    Parameters

    request

    parameter block for the control request

    completion

    describes action to take when the request has been executed

    Discussion

    Make a control request There are two versions of this method, one uses a simple void * to point to the data portion of the transfer, the other uses an IOMemoryDescriptor to point to the data.

    Import Statement

  • Declaration

    C++

    virtual IOReturn ControlRequest( IOUSBDevRequestDesc *request, UInt32 noDataTimeout, UInt32 completionTimeout, IOUSBCompletion *completion = 0);

    Parameters

    request

    parameter block for the control request

    noDataTimeout

    Specifies an amount of time (in ms) after which the command will be aborted if no data has been transferred on the bus.

    completionTimeout

    Specifies an amount of time (in ms) after which the command will be aborted if the entire command has not been completed.

    completion

    describes action to take when the request has been executed

    Discussion

    Make a control request. There are two versions of this method, one uses a simple void * to point to the data portion of the transfer, the other uses an IOMemoryDescriptor to point to the data.

    Import Statement

  • Declaration

    C++

    virtual UInt8 GetDirection();

    Discussion

    returns the direction of the pipe:kUSBOut/kUSBIn for a bulk or interrupt pipe, kUSBAnyDirn for a control pipe.

    Import Statement

  • Declaration

    C++

    virtual const IOUSBController::Endpoint * GetEndpoint();

    Discussion

    returns a pointer to the Endpoint structure for the pipe.

    Import Statement

  • Declaration

    C++

    virtual const IOUSBEndpointDescriptor * GetEndpointDescriptor();

    Discussion

    returns the endpoint descriptor for the pipe.

    Import Statement

  • Declaration

    C++

    virtual UInt8 GetEndpointNumber();

    Discussion

    returns the endpoint number in the device that the pipe is connected to.

    Import Statement

  • Declaration

    C++

    virtual IOReturn GetPipeStatus( void);

    Discussion

    Returns the status of the pipe (kIOUSBPipeStalled of the pipe is stalled, else kIOReturnSuccess)

    Import Statement

  • Declaration

    C++

    virtual UInt8 GetStatus( void);

    Discussion

    This method does NOT work. Do not call it. See GetPipeStatus for the correct method. GetStatus will always return 0.

    Import Statement

  • Declaration

    C++

    virtual UInt8 GetType();

    Discussion

    returns the pipe type: kUSBControl, kUSBBulk or kUSBInterrupt.

    Import Statement

  • Declaration

    C++

    virtual IOReturn Read( IOMemoryDescriptor *buffer, UInt32 noDataTimeout, UInt32 completionTimeout, IOByteCount reqCount, IOUSBCompletion *completion = 0, IOByteCount *bytesRead = 0);

    Parameters

    buffer

    place to put the transferred data

    noDataTimeout

    number of milliseconds of no bus activity until transaction times out. Note that if a tranasction times out the driver software may have to resynchronize the data toggle. See ClearPipeStall.

    completionTimeout

    number of milliseconds from the time the transaction is placed on the bus until it times out

    reqCount

    requested number of bytes to transfer. must be <= buffer->getLength()

    completion

    describes action to take when buffer has been filled

    bytesRead

    returns total bytes read for synchronous reads

    Discussion

    Read from an interrupt or bulk endpoint

    Import Statement

  • Declaration

    C++

    virtual IOReturn Read( IOMemoryDescriptor *buffer, UInt32 noDataTimeout, UInt32 completionTimeout, IOByteCount reqCount, IOUSBCompletionWithTimeStamp *completion = 0, IOByteCount *bytesRead = 0);

    Parameters

    buffer

    place to put the transferred data

    noDataTimeout

    number of milliseconds of no bus activity until transaction times out. Note that if a tranasction times out the driver software may have to resynchronize the data toggle. See ClearPipeStall.

    completionTimeout

    number of milliseconds from the time the transaction is placed on the bus until it times out

    reqCount

    requested number of bytes to transfer. must be <= buffer->getLength()

    completion

    describes action to take when buffer has been filled

    bytesRead

    returns total bytes read for synchronous reads

    Discussion

    Read from an interrupt or bulk endpoint

    Import Statement

  • Declaration

    C++

    virtual IOReturn Read( IOMemoryDescriptor *buffer, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOUSBIsocCompletion *completion = 0);

    Parameters

    buffer

    place to put the transferred data

    frameStart

    USB frame number of the frame to start transfer

    numFrames

    Number of frames to transfer

    frameList

    Bytes to transfer and result for each frame

    completion

    describes action to take when buffer has been filled

    Discussion

    Read from an isochronous endpoint

    Import Statement

  • Declaration

    C++

    virtual IOReturn Read( IOMemoryDescriptor *buffer, UInt64 frameStart, UInt32 numFrames, IOUSBLowLatencyIsocFrame *frameList, IOUSBLowLatencyIsocCompletion *completion = 0, UInt32 updateFrequency = 0);

    Parameters

    buffer

    place to put the transferred data

    frameStart

    USB frame number of the frame to start transfer. For SuperSpeed Isoc devices, if the frameStart is kAppleUSBSSIsocContinuousFrame, then just continue after the last transfer which was called.

    numFrames

    Number of frames to transfer

    frameList

    Bytes to transfer, result, and time stamp for each frame

    completion

    describes action to take when buffer has been filled

    updateFrequency

    describes how often (in milliseconds) should the frame list be processed

    Discussion

    AVAILABLE ONLY IN VERSION 1.9.2 AND ABOVE Read from an isochronous endpoint and process the IOUSBLowLatencyIsocFrame fields at hardware interrupt time

    Import Statement

  • Declaration

    C++

    virtual IOReturn Reset( void);

    Discussion

    This method is identical to ClearPipeStall(false). The use of that API is preferred.

    Import Statement

  • Declaration

    C++

    virtual IOReturn SetPipePolicy( UInt16maxPacketSize, UInt8maxInterval);

    Parameters

    maxPacketSize

    specifies the maximum number of bytes to be used in any one millisecond frame by this pipe. The value must be less than or equal to the maxPacketSize specified in the endpoint descriptor.

    maxInterval

    not currently used. reserved for future expansion

    Discussion

    AVAILABLE ONLY IN VERSION 1.9 AND ABOVE This method allows a driver to change the maxPacketSize of an Isochronous pipe, or the polling interval for an interrupt pipe. There is a limited amount of bandwidth on any single bus, and isochronous pipes tend to use much of this bandwidth. The driver may know, however, that there will never be as much bandwidth used as is specified in the pipe's endpoint descriptor. Therefore, the driver may return some of this bandwidth to the system by using this method. Additionally, if on an open of an IOUSBInterface any of the Isochronous pipes is unable to be opened because of a lack of bandwidth, the pipe will be created with a bandwidth of zero, and the driver may get some of the limited bandwidth remaining by using this call. This method returns kIOReturnBadArgument if the pipe is a bulk on control pipe, or if the maxPacketSize parameter is larger than the amount specified in the endpoint descriptor. It returns kIOReturnNoBandwidth if the bandwidth requested cannot be allocated. Otherwise it returns kIOReturnSuccess.

    Import Statement

  • Declaration

    C++

    virtual IOReturn Write( IOMemoryDescriptor *buffer, UInt64 frameStart, UInt32 numFrames, IOUSBLowLatencyIsocFrame *frameList, IOUSBLowLatencyIsocCompletion *completion = 0, UInt32 updateFrequency = 0);

    Parameters

    buffer

    place to get the data to transfer

    frameStart

    USB frame number of the frame to start transfer. For SuperSpeed Isoc devices, if the frameStart is kAppleUSBSSIsocContinuousFrame, then just continue after the last transfer which was called.

    numFrames

    Number of frames to transfer

    frameList

    Pointer to list of frames indicating bytes to transfer and result for each frame

    completion

    describes action to take when buffer has been emptied

    updateFrequency

    describes how often (in milliseconds) should the frame list be processed

    Discussion

    AVAILABLE ONLY IN VERSION 1.9.2 AND ABOVE Write to an isochronous endpoint

    Import Statement

  • Declaration

    C++

    virtual IOReturn Write( IOMemoryDescriptor *buffer, UInt32 noDataTimeout, UInt32 completionTimeout, IOByteCount reqCount, IOUSBCompletion *completion = 0);

    Parameters

    buffer

    place to get the transferred data

    noDataTimeout

    number of milliseconds of no bus activity until transaction times out. Note that if a tranasction times out the driver software may have to resynchronize the data toggle. See ClearPipeStall.

    completionTimeout

    number of milliseconds from the time the transaction is placed on the bus until it times out

    reqCount

    requested number of bytes to transfer. must be <= buffer->getLength()

    completion

    describes action to take when buffer has been emptied

    Discussion

    Write to an interrupt or bulk endpoint

    Import Statement

  • Declaration

    C++

    virtual IOReturn Write( IOMemoryDescriptor *buffer, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOUSBIsocCompletion *completion = 0);

    Parameters

    buffer

    place to get the transferred data

    frameStart

    USB frame number of the frame to start transfer

    numFrames

    Number of frames to transfer

    frameList

    Bytes to transfer and result for each frame

    completion

    describes action to take when buffer has been emptied

    Discussion

    Write to an isochronous endpoint

    Import Statement