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

IOUSBDevice

Inherits from:	IOUSBNub
Declared In:	IOUSBDevice.h

Overview

The IOService object representing a device on the USB bus.

Discussion

This class provides functionality to configure a device and to create IOUSBInterface objects to represent the interfaces of the device.

Functions

CreateInterfaceIterator
DeviceRequest: execute a control request to the default control pipe (pipe zero)
DisplayUserNotification: Will use the KUNCUserNotification mechanism to display a notification to the user.
FindNextInterface
FindNextInterfaceDescriptor
GetAddress
GetBus
GetBusPowerAvailable
GetChildLocationID
GetConfiguration
GetConfigurationDescriptor
GetDeviceRelease
GetDeviceStatus
GetFullConfigurationDescriptor
GetManufacturerStringIndex
GetMaxPacketSize
GetNumConfigs
GetNumConfigurations
GetPipeZero
GetProductID
GetProductStringIndex
GetSerialNumberStringIndex
GetSpeed
GetStringDescriptor
GetVendorID
MakePipe: build a pipe on a given endpoint
ReEnumerateDevice: Instruct the hub to which this device is attached to reset the port to which this device is attached. This causes the IOUSBDevice object and any child objects (IOUSBInterface objects or driver objects) to be terminated, and the device to be completely reenumerated, as if it had been detached and reattached.
ResetDevice
SetConfiguration
SuspendDevice: Instruct the hub to which this device is attached to suspend or resume the port to which the device is attached. Note that if there are any outstanding transactions on any pipes in the device, those transactions will get returned with a kIOReturnNotResponding error.

CreateInterfaceIterator

public

virtual OSIterator *CreateInterfaceIterator(
    IOUSBFindInterfaceRequest *request);

Parameters

request: specifies what properties an interface must have to match.

Return Value

Pointer to an OSIterator.

Discussion

return an OSIterator to iterate through interfaces satisfying the requirements specified in request.

DeviceRequest

execute a control request to the default control pipe (pipe zero)

public

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

Parameters

request: The parameter block to send to the device
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: Function to call when request completes. If omitted then DeviceRequest() executes synchronously, blocking until the request is complete.

DisplayUserNotification

Will use the KUNCUserNotification mechanism to display a notification to the user.

public

virtual void DisplayUserNotification(
    UInt32 notificationType);

Parameters

notificationType: Which notification to display.

FindNextInterface

public

virtual IOUSBInterface *FindNextInterface(
    IOUSBInterface *current, 
    IOUSBFindInterfaceRequest *request);

Parameters

current: interface to start searching from, NULL to start at the beginning of the device's interface list for the current configuration.
request: specifies what properties an interface must have to match.

Return Value

Pointer to a matching IOUSBInterface, or NULL if none match. Note: The IOUSBInterface is NOT retained for the caller. If the caller wishes to continue to use the returned object, it should call retain() on that object.

Discussion

return an pointer to an IOUSBInterface object satisfying the requirements specified in request, or NULL if there aren't any. the device must be configured for there to be any interfaces.

FindNextInterfaceDescriptor

public

virtual IOReturn FindNextInterfaceDescriptor(
    const IOUSBConfigurationDescriptor *configDescIn, 
    const IOUSBInterfaceDescriptor *intfDesc, 
    const IOUSBFindInterfaceRequest *request, 
    IOUSBInterfaceDescriptor **descOut);

Parameters

configDescIn: the configuration descriptor within which to search. obtained from GetFullConfigurationDescriptor(configIndex). use NULL to specify the current configuration's descriptor.
intfDesc: interface descriptor from which to start the search. NULL for the first interface descriptor in the given configuration descriptor
request: IOUSBFindInterfaceRequest specifying the desired interface. Not changed.
descOut: pointer to placeholder for the returned descriptor ptr

Return Value

returns kIOReturnBadArgument if configDesc is not correct, or if configDesc is NULL and the device is not configured, or if intfDesc is not in configDesc. Otherwise returns kIOReturnSuccess or kIOUSBInterfaceNotFound.

Discussion

return a pointer to the next interface descriptor within the given full configuration descriptor satisfying the requirements specified, or NULL if there aren't any.

GetAddress

public

virtual USBDeviceAddress GetAddress(
    void);

Discussion

returns the bus address of the device

GetBus

public

virtual IOUSBController *GetBus(
    void);

Discussion

returns a pointer to the IOUSBController object for the device

GetBusPowerAvailable

public

virtual UInt32 GetBusPowerAvailable(
    void );

Discussion

returns the power available to the device, in units of 2mA

GetChildLocationID

public

virtual UInt32 GetChildLocationID(
    UInt32 parentLocationID,
    int port);

Parameters

parentLocationID: locationID for the hub to which this device is attached.
port: Port number of the hub where this device is attached

Discussion

Get the locationID (UInt32) given the port number and the parent's location

GetConfiguration

public

virtual IOReturn GetConfiguration(
    UInt8 *configNumber);

Parameters

configNum: Pointer to place to store configuration value.

Discussion

Gets the current configuration from the IOUSBDevice object. Note that this call will send a control request on the bus to get the current configuration from the physical device.

GetConfigurationDescriptor

public

virtual IOReturn GetConfigurationDescriptor(
    UInt8 configValue,
    void *data,
    UInt32 len);

Parameters

configValue: The configuration value
data: Buffer to copy data into
len: number of bytes to copy

Discussion

Copy the specified amount of data for a configuration into the suppled buffer.

GetDeviceRelease

public

virtual UInt16 GetDeviceRelease(
    void);

Discussion

returns the DeviceRelease information

GetDeviceStatus

public

virtual IOReturn GetDeviceStatus(
    USBStatus *status);

Parameters

status: Pointer to place to store the status.

Discussion

Gets the device's status. Note that this sends a control request to the physical device.

GetFullConfigurationDescriptor

public

virtual const IOUSBConfigurationDescriptor *GetFullConfigurationDescriptor(UInt8 configIndex);

Parameters

configIndex: The configuration index (not the configuration value)

Return Value

Pointer to the descriptors, which are cached in the IOUSBDevice object.

Discussion

return a pointer to all the descriptors for the requested configuration.

GetManufacturerStringIndex

public

virtual UInt8 GetManufacturerStringIndex(
    void );

Discussion

returns the index of string descriptor describing manufacturer

GetMaxPacketSize

public

virtual UInt8 GetMaxPacketSize(
    void);

Discussion

returns the maximum packet size for endpoint zero (only 8, 16, 32, 64 are valid)

GetNumConfigs

public

virtual UInt8 GetNumConfigurations(
    void);

Discussion

returns the number of configs in the device config descriptor

GetNumConfigurations

public

virtual UInt8 GetNumConfigurations(
    void);

Discussion

returns the number of configs in the device config descriptor

GetPipeZero

public

virtual IOUSBPipe * GetPipeZero(
    void);

Discussion

returns a pointer to the device's default control pipe

GetProductID

public

virtual UInt16 GetProductID(
    void);

Discussion

returns the Product ID of the device

GetProductStringIndex

public

virtual UInt8 GetProductStringIndex(
    void );

Discussion

returns the index of string descriptor describing product

GetSerialNumberStringIndex

public

virtual UInt8 GetSerialNumberStringIndex(
    void );

Discussion

returns the index of string descriptor describing the device's serial number

GetSpeed

public

virtual UInt8 GetSpeed(
    void);

Discussion

returns the speed of the device

GetStringDescriptor

public

virtual IOReturn GetStringDescriptor(
    UInt8 index,
    char *buf,
    int maxLen,
    UInt16 lang=0x409);

Parameters

index: Index of the string descriptor to get.
buf: Pointer to place to store ASCII string
maxLen: Size of buffer pointed to by buf
lang: Language to get string in (default is US English)

Discussion

Get a string descriptor as ASCII, in the specified language (default is US English)

GetVendorID

public

virtual UInt16 GetVendorID(
    void);

Discussion

returns the Vendor ID of the device

MakePipe

build a pipe on a given endpoint

public

virtual IOUSBPipe* MakePipe(
    const IOUSBEndpointDescriptor *ep,
    IOUSBInterface *interface);

Parameters

ep: A description of the endpoint
interface: The IOUSBInterface object requesting the pipe returns the desired IOUSBPipe object

ReEnumerateDevice

Instruct the hub to which this device is attached to reset the port to which this device is attached. This causes the IOUSBDevice object and any child objects (IOUSBInterface objects or driver objects) to be terminated, and the device to be completely reenumerated, as if it had been detached and reattached.

public

virtual IOReturn ReEnumerateDevice(
    UInt32 options );

Parameters

options: Reserved for future use.

ResetDevice

public

virtual IOReturn ResetDevice();

Discussion

Reset the device, returning it to the addressed, unconfigured state. This is useful if a device has got badly confused. Note that the AppleUSBComposite driver will automatically reconfigure the device if it is a composite device.

SetConfiguration

public

virtual IOReturn SetConfiguration(
    IOService *forClient,
    UInt8 configValue,
    bool startInterfaceMatching=true);

Parameters

forClient: The client requesting the configuration change
configValue: The desired configuration value.
startInterfaceMatching: A boolean specifying whether IOKit should begin the process of finding matching drivers for the new IOUSBInterface objects.

Discussion

Do a USB SetConfiguration call to the device. The caller must have the device open() in order to actually cause a configuration change. If the device is currently configured, all IOUSBInterface objects associated with the device are freed. After the new configuration has been set, all of its IOUSBInterface objects are instantiated automatically.

SuspendDevice

Instruct the hub to which this device is attached to suspend or resume the port to which the device is attached. Note that if there are any outstanding transactions on any pipes in the device, those transactions will get returned with a kIOReturnNotResponding error.

public

virtual IOReturn SuspendDevice(
    bool suspend);

Parameters

suspend: Boolean value. true = suspend, false = resume.

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