ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

---

IOUSBInterface

Overview

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

Discussion

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

---

Functions

DeviceRequest

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

FindNextAltInterface

FindNextAssociatedDescriptor

FindNextPipe

GetAlternateSetting

GetConfigValue

GetDevice

GetEndpointProperties

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

GetInterfaceClass

GetInterfaceNumber

GetInterfaceProtocol

GetInterfaceStringIndex

GetInterfaceSubClass

GetNumEndpoints

GetPipeObj

SetAlternateInterface

---

DeviceRequest

---

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

public

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.

---

FindNextAltInterface

---

public

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

---

public

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

---

public

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.

---

GetAlternateSetting

---

public

virtual UInt8 GetAlternateSetting(); 

Return Value

the alternate setting

Discussion

returns the alternate setting for this interface.

---

GetConfigValue

---

public

virtual UInt8 GetConfigValue(); 

Return Value

The device configuration value.

Discussion

returns the device configuration value for the interface

---

GetDevice

---

public

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.

public

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.

---

GetInterfaceClass

---

public

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

---

public

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

---

public

virtual UInt8 GetInterfaceProtocol(); 

Return Value

the interface index

Discussion

returns the protocol code (assigned by the USB).

---

GetInterfaceStringIndex

---

public

virtual UInt8 GetInterfaceStringIndex(); 

Return Value

the string index

Discussion

returns the index of the string descriptor describing the interface

---

GetInterfaceSubClass

---

public

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

---

public

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

---

public

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

---

SetAlternateInterface

---

public

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.

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: 2008-12-19