IOUSBDevice

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

Overview

The IOService object representing a device on the USB bus.

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

Tasks

Miscellaneous

Instance Methods

CreateInterfaceIterator

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(IOUSBDevRequest *, UInt32, UInt32, IOUSBCompletion *)

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

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. If the request is asynchronous, the client must make sure that the IOUSBDevRequest is not released until the callback has occurred.

DeviceRequest(IOUSBDevRequestDesc *, UInt32, UInt32, IOUSBCompletion *)

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

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

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

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. If the request is asynchronous, the client must make sure that the IOUSBDevRequest is not released until the callback has occurred.

DisplayUserNotification

Will use the Notification Center to display a notification to the user. Only Low Power and Overcurrent notifications are supported.

virtual void DisplayUserNotification( UInt32 notificationType);
Parameters
notificationType

Which notification to display.

DoLocationOverrideAndModelMatch

Will look for a kOverrideIfAtLocationID array proerty with locationID entries and a "MacModel" property. If any of the locationIDs match to the Mac Model, will return true. If there is no kOverrideAtLocationID property, it will also return true.

virtual bool DoLocationOverrideAndModelMatch();
Return Value

True if we have a match, false otherwise

FindNextInterface

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

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

virtual USBDeviceAddress GetAddress( void);
Discussion

returns the bus address of the device

GetBus

virtual IOUSBController *GetBus( void);
Discussion

returns a pointer to the IOUSBController object for the device

GetBusPowerAvailable

virtual UInt32 GetBusPowerAvailable( void );
Discussion

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

GetChildLocationID

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

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

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.

GetDeviceInformation

Returns status information about the USB device, such as whether the device is captive or whether it is in the suspended state.

virtual IOReturn GetDeviceInformation( UInt32 *info);
Parameters
requestedPower

The desired amount of power that the client wishes to reserve

Return Value

Actual power that was reserved

GetDeviceRelease

virtual UInt16 GetDeviceRelease( void);
Discussion

returns the DeviceRelease information

GetDeviceStatus

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.

GetExtraPowerAllocated

Clients can use this API to ask how much extra power has already been reserved by this device. Units are milliAmps (mA).

virtual UInt32 GetExtraPowerAllocated( UInt32 type);
Parameters
type

Indicates whether the allocated power was to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)

Return Value

Amount of power allocated, in mA.

GetFullConfigurationDescriptor

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.

GetHubParent

Used by the hub driver to give the nub a pointer to its HubPolicyMaker object

virtual IOUSBHubPolicyMaker* GetHubParent();
Parameters
hubPolicyMaker

The object representing the Hub driver

GetManufacturerStringIndex

virtual UInt8 GetManufacturerStringIndex( void );
Discussion

returns the index of string descriptor describing manufacturer

GetMaxPacketSize

virtual UInt8 GetMaxPacketSize( void);
Discussion

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

GetNumConfigurations

virtual UInt8 GetNumConfigurations( void);
Discussion

returns the number of configs in the device config descriptor

GetPipeZero

virtual IOUSBPipe * GetPipeZero( void);
Discussion

returns a pointer to the device's default control pipe

GetProductID

virtual UInt16 GetProductID( void);
Discussion

returns the Product ID of the device

GetProductStringIndex

virtual UInt8 GetProductStringIndex( void );
Discussion

returns the index of string descriptor describing product

GetSerialNumberStringIndex

virtual UInt8 GetSerialNumberStringIndex( void );
Discussion

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

GetSpeed

virtual UInt8 GetSpeed( void);
Discussion

returns the speed of the device

GetStringDescriptor

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

virtual UInt16 GetVendorID( void);
Discussion

returns the Vendor ID of the device

MakePipe

build a pipe on a given endpoint

virtual IOUSBPipeV2* MakePipe( const IOUSBEndpointDescriptor *ep, IOUSBSuperSpeedEndpointCompanionDescriptor *sscd, IOUSBInterface *interface);
Parameters
ep

A description of the endpoint

sscd

The SuperSpeed Companion Descriptor, if any (NULL if none)

interface

The IOUSBInterface object requesting the pipe returns the desired IOUSBPipe object

OpenOrCloseAllInterfacePipes

Iterates over all interfaces and either opens all the pipes, or closes them all

virtual void OpenOrCloseAllInterfacePipes( bool open);
Parameters
open,

if true pipes are opened, else closed

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.

virtual IOReturn ReEnumerateDevice( UInt32 options );
Parameters
options

Reserved for future use.

RequestExtraPower

Clients can use this API to reserve extra power for use by this device while the machine is asleep or while it is awake. Units are milliAmps (mA).

virtual UInt32 RequestExtraPower( UInt32 type, UInt32 requestedPower);
Parameters
type

Indicates whether the power is to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)

requestedPower

Amount of power desired, in mA

Return Value

Amount of power actually reserved, in mA. It can be less than the requested or zero.

ResetDevice

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.

ReturnExtraPower

Clients can use this API to tell the system that they will not use power that was previously reserved by using the RequestExtraPower API.

virtual IOReturn ReturnExtraPower( UInt32 type, UInt32 returnedPower);
Parameters
type

Indicates whether the power is to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)

returnedPower

Amount of power that is no longer needed, in mA

Return Value

If the returnedPower was not previously allocated, an error will be returned. This will include the case for power that was requested for sleep but was returned for wake.

SetAddress

virtual void SetAddress( USBDeviceAddress address);
Parameters
Sets

the bus address of the device

SetConfiguration(IOService *, UInt8, bool)

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.

SetConfiguration(IOService *, UInt8, bool, bool)

virtual IOReturn SetConfiguration( IOService *forClient, UInt8 configValue, bool startInterfaceMatching, bool issueRemoteWakeup);
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

issueRemoteWakeup

A boolean specifying whether we should issue the SetFeature(kUSBFeatureDeviceRemoteWakeup) immediately after setting the configuration, before loading any drivers. 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.

SetHubParent

Used by the hub driver to give the nub a pointer to its HubPolicyMaker object

virtual void SetHubParent( IOUSBHubPolicyMaker *hubParent);
Parameters
hubPolicyMaker

The object representing the Hub driver

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.

virtual IOReturn SuspendDevice( bool suspend);
Parameters
suspend

Boolean value. true = suspend, false = resume.