Mac Developer Library

Developer

IOUSBInterface Class Reference

Options
Deployment Target:

On This Page

IOUSBInterface

The object representing an interface of a device on the USB bus.

This class provides functionality to find the pipes of an interface and to read the descriptors associated with an interface. When an interface is open()ed, all its pipes are created

  • Sends a control request to the default control pipe in the device (pipe zero)

    Declaration

    virtual IOReturn DeviceRequest( IOUSBDevRequest *request, IOUSBCompletion *completion = 0);

    Parameters

    request

    The parameter block to send to the device

    completion

    Function to call when request completes. If omitted then DeviceRequest() executes synchronously, blocking until the request is complete. If the request is asynchronous, the client must make sure that the IOUSBDevRequest is not released until the callback has occurred.

  • Sends a control request to the default control pipe in the device (pipe zero)

    Declaration

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

    Parameters

    request

    The parameter block to send to the device (with the pData as an IOMemoryDesriptor)

    completion

    Function to call when request completes. If omitted then DeviceRequest() executes synchronously, blocking until the request is complete. If the request is asynchronous, the client must make sure that the IOUSBDevRequest is not released until the callback has occurred.

  • Will enable or disable the USB 3.0 remote wake function for the interface

    Declaration

    virtual IOReturn EnableRemoteWake( bool enable);

    Parameters

    enable

    Whether we enable (true) or disable (false) the remote wake..

    Return Value

    returns kIOReturnSuccess if the request is completed successfully, otherwise returns the result of the Device Request to set the feature.

  • Declaration

    virtual const IOUSBInterfaceDescriptor *FindNextAltInterface( const IOUSBInterfaceDescriptor *current, IOUSBFindInterfaceRequest *request);

    Parameters

    current

    interface descriptor to start searching from, NULL to start at alternate interface 0.

    request

    specifies what properties an interface must have to match.

    Return Value

    Pointer to a matching interface descriptor, or NULL if none match.

    Discussion

    return alternate interface descriptor satisfying the requirements specified in request, or NULL if there aren't any. request is updated with the properties of the returned interface.

  • Declaration

    virtual const IOUSBDescriptorHeader * FindNextAssociatedDescriptor( const void *current, UInt8 type);

    Parameters

    current

    Descriptor to start searching from, NULL to start from beginning of list.

    type

    Descriptor type to search for, or kUSBAnyDesc to return any descriptor type.

    Return Value

    Pointer to the descriptor, or NULL if no matching descriptors found.

    Discussion

    Find the next descriptor of the requested type associated with the interface.

  • Declaration

    virtual IOUSBPipe *FindNextPipe( IOUSBPipe *current, IOUSBFindEndpointRequest *request);

    Parameters

    current

    Pipe to start searching from, NULL to start from beginning of list.

    request

    Requirements for pipe to match, updated with the found pipe's properties.

    Return Value

    Pointer to the pipe, or NULL if no pipe matches the request.

    Discussion

    Find a pipe of the interface that matches the requirements, either starting from the beginning of the interface's pipe list or from a specified pipe.

  • Declaration

    virtual IOUSBPipe* FindNextPipe( IOUSBPipe *current, IOUSBFindEndpointRequest *request, bool withRetain);

    Parameters

    current

    Pipe to start searching from, NULL to start from beginning of list.

    request

    Requirements for pipe to match, updated with the found pipe's properties.

    withRetain

    Pass true to retain and the client should release it later after its use.

    Return Value

    Pointer to the pipe, or NULL if no pipe matches the request.

    Discussion

    Find a pipe of the interface that matches the requirements, either starting from the beginning of the interface's pipe list or from a specified pipe.

  • Declaration

    virtual UInt8 GetAlternateSetting();

    Return Value

    the alternate setting

    Discussion

    returns the alternate setting for this interface.

  • Declaration

    virtual UInt8 GetConfigValue();

    Return Value

    The device configuration value.

    Discussion

    returns the device configuration value for the interface

  • Declaration

    virtual IOUSBDevice *GetDevice();

    Return Value

    Pointer to the IOUSBDevice object which is the parent of this IOUSBInterface object.

    Discussion

    returns the device the interface is part of.

  • Returns the properties of an endpoint, possibly in an alternate interface.

    Declaration

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

    Parameters

    alternateSetting

    specifies the desired alternate setting

    endpointNumber

    specifies the endpoint number

    direction

    specifies the direction (kUSBIn, kUSBOut)

    transferType

    a pointer to hold the transfer type (kUSBControl, kUSBBulk, etc.) of the endpoint if found.

    maxPacketSize

    a pointer to hold the maxPacketSize in the endpoint descriptor.

    interval

    a pointer to hold the interval value in the endpoint descriptor.

    Return Value

    returns kIOReturnSuccess if the endpoint is found, and kIOUSBEndpointNotFound if it is not.

  • Returns the properties of an endpoint, possibly in an alternate interface, including any information from the SuperSpeed Companion Descriptor

    Declaration

    virtual IOReturn GetEndpointPropertiesV3( IOUSBEndpointProperties *endpointProperties);

    Parameters

    endpointProperties

    Pointer to a IOUSBEndpointProperties structure that upon success will contain the information for the endpoint. The bVersion field needs to be initialized with the structure version (see USBEndpointVersion enum in USB.h). The bAlternateSetting, bEndpointNumber, and bDirection (kUSBIn, kUSBOut) MUST also be filled in with the values for the desired descriptor. Not that the bMaxStreams value for Bulk endpoints is the value specified by the bmAttributes field in the SuperSpeed companion descriptor.

    Return Value

    returns kIOReturnSuccess if the endpoint is found, and kIOUSBEndpointNotFound if it is not.

  • Declaration

    virtual UInt8 GetInterfaceClass();

    Return Value

    the interface class

    Discussion

    returns the class code for this interface (assigned by the USB) a value of zero is reserved if the value is FFh, the interface class is vendor-specific all other values are reserved for assignment by the USB

  • Declaration

    virtual UInt8 GetInterfaceNumber();

    Return Value

    the interface index

    Discussion

    returns the zero based value identifying the index in the array of concurrent interfaces supported by the current configuration

  • Declaration

    virtual UInt8 GetInterfaceProtocol();

    Return Value

    the interface index

    Discussion

    returns the protocol code (assigned by the USB).

  • Returns the result of issuing a GET_STATUS request on the device for this interface.

    Declaration

    virtual IOReturn GetInterfaceStatus( USBStatus *status);

    Parameters

    status

    Pointer to a USBStatus type which will contain the results of the operation.

    Return Value

    returns kIOReturnSuccess if the request is completed successfully, otherwise returns the result of the Device Request.

  • Declaration

    virtual UInt8 GetInterfaceStringIndex();

    Return Value

    the string index

    Discussion

    returns the index of the string descriptor describing the interface

  • Declaration

    virtual UInt8 GetInterfaceSubClass();

    Return Value

    the interface subclass

    Discussion

    returns the subclass code (assigned by the USB). These codes are qualified by the value returned by GetInterfaceClass

  • Declaration

    virtual UInt8 GetNumEndpoints();

    Return Value

    the number of endpoints

    Discussion

    returns the number of endpoints used by this interface (excluding device endpoint zero. If the value is zero, this interface only uses endpoint zero.

  • Declaration

    virtual IOUSBPipe *GetPipeObj( UInt8 index);

    Parameters

    index

    value from zero to kUSBMaxPipes-1

    Return Value

    The IOUSBPipe object. Note that the client does not own a reference to this pipe, so the client should retain() the IOUSBPipe object if necessary.

    Discussion

    returns a handle to the pipe at the corresponding index

  • Declaration

    virtual IOReturn RecreateStreams( void);

    Return Value

    returns kIOReturnSuccess if sucessful.

    Discussion

    Recreate the remembered streams after a device has been reset.

  • Declaration

    virtual IOReturn RememberStreams( void);

    Return Value

    returns kIOReturnSuccess if sucessful.

    Discussion

    Make a note of which pipes have streams, so they can be recreated later.

  • Declaration

    virtual IOReturn RememberStreams( void);

    Return Value

    returns kIOReturnSuccess if sucessful.

    Discussion

    Make a note of which pipes have streams, so they can be recreated later.

  • Declaration

    virtual IOReturn SetAlternateInterface( IOService *forClient, UInt16 alternateSetting);

    Parameters

    forClient

    The client requesting the alternate setting. This client must have the interface open in order to perform the request.

    alternateSetting

    Alternate setting (from the alternate interface's interface descriptor).

    Return Value

    exclusive access error if the interface is not open. otherwise the result of the transaction

    Discussion

    Select the specified alternate interface.

  • Issues a SET_FEATURE(FUNCTION_SUSPEND) to the interface.

    Declaration

    virtual IOReturn SetFunctionSuspendFeature( UInt8 options);

    Parameters

    options

    The suspend options passed to the Device Request.

    Return Value

    returns kIOReturnSuccess if the request is completed successfully, otherwise returns the result of the Device Request.