Mac Developer Library

Developer

IOUSBDevice Class Reference

Options
Deployment Target:

On This Page
Language:

IOUSBDevice

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual void DisplayUserNotification( UInt32notificationType);

    Parameters

    notificationType

    Which notification to display.

  • 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.

    Declaration

    C++

    virtual bool DoLocationOverrideAndModelMatch();

    Return Value

    True if we have a match, false otherwise

  • Declaration

    C++

    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.

  • Declaration

    C++

    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.

  • Declaration

    C++

    virtual USBDeviceAddress GetAddress( void);

    Discussion

    returns the bus address of the device

  • Declaration

    C++

    virtual IOUSBController *GetBus( void);

    Discussion

    returns a pointer to the IOUSBController object for the device

  • Declaration

    C++

    virtual UInt32 GetBusPowerAvailable( void );

    Discussion

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

  • Declaration

    C++

    virtual UInt32 GetChildLocationID( UInt32parentLocationID, intport);

    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

  • Declaration

    C++

    virtual IOReturn GetConfiguration( UInt8 *configNum);

    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.

  • Declaration

    C++

    virtual IOReturn GetConfigurationDescriptor( UInt8configValue, void *data, UInt32len);

    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.

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

    Declaration

    C++

    virtual IOReturn GetDeviceInformation( UInt32 *requestedPower);

    Parameters

    requestedPower

    The desired amount of power that the client wishes to reserve

    Return Value

    Actual power that was reserved

  • Declaration

    C++

    virtual UInt16 GetDeviceRelease( void);

    Discussion

    returns the DeviceRelease information

  • Declaration

    C++

    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.

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

    Declaration

    C++

    virtual UInt32 GetExtraPowerAllocated( UInt32type);

    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.

  • Declaration

    C++

    virtual const IOUSBConfigurationDescriptor *GetFullConfigurationDescriptor( UInt8configIndex);

    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.

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

    Declaration

    C++

    virtual IOUSBHubPolicyMaker* GetHubParent();

    Parameters

    hubPolicyMaker

    The object representing the Hub driver

  • Declaration

    C++

    virtual UInt8 GetManufacturerStringIndex( void );

    Discussion

    returns the index of string descriptor describing manufacturer

  • Declaration

    C++

    virtual UInt8 GetMaxPacketSize( void);

    Discussion

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

  • Declaration

    C++

    virtual UInt8 GetNumConfigurations( void);

    Discussion

    returns the number of configs in the device config descriptor

  • Declaration

    C++

    virtual IOUSBPipe * GetPipeZero( void);

    Discussion

    returns a pointer to the device's default control pipe

  • Declaration

    C++

    virtual UInt16 GetProductID( void);

    Discussion

    returns the Product ID of the device

  • Declaration

    C++

    virtual UInt8 GetProductStringIndex( void );

    Discussion

    returns the index of string descriptor describing product

  • Declaration

    C++

    virtual UInt8 GetSerialNumberStringIndex( void );

    Discussion

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

  • Declaration

    C++

    virtual UInt8 GetSpeed( void);

    Discussion

    returns the speed of the device

  • Declaration

    C++

    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)

  • Declaration

    C++

    virtual UInt16 GetVendorID( void);

    Discussion

    returns the Vendor ID of the device

  • build a pipe on a given endpoint

    Declaration

    C++

    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

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

    Declaration

    C++

    virtual void OpenOrCloseAllInterfacePipes( boolopen,);

    Parameters

    open,

    if true pipes are opened, else closed

  • 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.

    Declaration

    C++

    virtual IOReturn ReEnumerateDevice( UInt32options );

    Parameters

    options

    Reserved for future use.

  • 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).

    Declaration

    C++

    virtual UInt32 RequestExtraPower( UInt32type, UInt32requestedPower);

    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.

  • Declaration

    C++

    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.

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

    Declaration

    C++

    virtual IOReturn ReturnExtraPower( UInt32type, UInt32returnedPower);

    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.

  • Declaration

    C++

    virtual void SetAddress( USBDeviceAddressSets);

    Parameters

    Sets

    the bus address of the device

  • Declaration

    C++

    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.

  • Declaration

    C++

    virtual IOReturn SetConfiguration( IOService *forClient, UInt8configValue, boolstartInterfaceMatching, boolissueRemoteWakeup);

    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.

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

    Declaration

    C++

    virtual void SetHubParent( IOUSBHubPolicyMaker *hubPolicyMaker);

    Parameters

    hubPolicyMaker

    The object representing the Hub driver

  • 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.

    Declaration

    C++

    virtual IOReturn SuspendDevice( boolsuspend);

    Parameters

    suspend

    Boolean value. true = suspend, false = resume.