Mac Developer Library

Developer

IOUSBInterface Class Reference

Options
Deployment Target:

On This Page
Language:

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Sends a control request to the default control pipe in the device (pipe zero)

    Declaration

    C++

    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

    C++

    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

    C++

    virtual IOReturn EnableRemoteWake( boolenable);

    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

    C++

    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

    C++

    virtual const IOUSBDescriptorHeader * FindNextAssociatedDescriptor( const void *current, UInt8type);

    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

    C++

    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

    C++

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

    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

    C++

    virtual UInt8 GetAlternateSetting();

    Return Value

    the alternate setting

    Discussion

    returns the alternate setting for this interface.

  • Declaration

    C++

    virtual UInt8 GetConfigValue();

    Return Value

    The device configuration value.

    Discussion

    returns the device configuration value for the interface

  • Declaration

    C++

    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

    C++

    virtual IOReturn GetEndpointProperties( UInt8alternateSetting, UInt8endpointNumber, UInt8direction, 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

    C++

    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

    C++

    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

    C++

    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

    C++

    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

    C++

    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

    C++

    virtual UInt8 GetInterfaceStringIndex();

    Return Value

    the string index

    Discussion

    returns the index of the string descriptor describing the interface

  • Declaration

    C++

    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

    C++

    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

    C++

    virtual IOUSBPipe *GetPipeObj( UInt8index);

    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

    C++

    virtual IOReturn RecreateStreams( void);

    Return Value

    returns kIOReturnSuccess if sucessful.

    Discussion

    Recreate the remembered streams after a device has been reset.

  • Declaration

    C++

    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

    C++

    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

    C++

    virtual IOReturn SetAlternateInterface( IOService *forClient, UInt16alternateSetting);

    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

    C++

    virtual IOReturn SetFunctionSuspendFeature( UInt8options);

    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.