IOUSBInterface

Inherits from
IOUSBNub
Availability
Available in OS X v10.0 and later.
Declared in
IOUSBInterface.h

Overview

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

Tasks

Miscellaneous

Instance Methods

DeviceRequest(IOUSBDevRequest *, IOUSBCompletion *)

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

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.

DeviceRequest(IOUSBDevRequestDesc *, IOUSBCompletion *)

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

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.

EnableRemoteWake

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

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.

FindNextAltInterface

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.

FindNextAssociatedDescriptor

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.

FindNextPipe(IOUSBPipe *, IOUSBFindEndpointRequest *)

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.

FindNextPipe(IOUSBPipe *, IOUSBFindEndpointRequest *, bool)

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.

GetAlternateSetting

virtual UInt8 GetAlternateSetting();
Return Value

the alternate setting

Discussion

returns the alternate setting for this interface.

GetConfigValue

virtual UInt8 GetConfigValue();
Return Value

The device configuration value.

Discussion

returns the device configuration value for the interface

GetDevice

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.

GetEndpointProperties

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

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.

GetEndpointPropertiesV3

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

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.

GetInterfaceClass

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

GetInterfaceNumber

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

GetInterfaceProtocol

virtual UInt8 GetInterfaceProtocol();
Return Value

the interface index

Discussion

returns the protocol code (assigned by the USB).

GetInterfaceStatus

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

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.

GetInterfaceStringIndex

virtual UInt8 GetInterfaceStringIndex();
Return Value

the string index

Discussion

returns the index of the string descriptor describing the interface

GetInterfaceSubClass

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

GetNumEndpoints

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.

GetPipeObj

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

RecreateStreams

virtual IOReturn RecreateStreams( void);
Return Value

returns kIOReturnSuccess if sucessful.

Discussion

Recreate the remembered streams after a device has been reset.

RememberStreams

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.

RememberStreams.

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.

SetAlternateInterface

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.

SetFunctionSuspendFeature

Issues a SET_FEATURE(FUNCTION_SUSPEND) to the interface.

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.