|
ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference
|
IOUSBLib.h |
| Include Path : | <IOKit/usb> |
| Path: | /System/Library/Frameworks/IOKit.framework/Versions/A/Headers/usb/IOUSBLib.h |
| Includes: |
<IOKit/usb/USB.h> <IOKit/IOKitLib.h> <CoreFoundation/CFRunLoop.h> <CoreFoundation/CFPlugIn.h> <CoreFoundation/CFPlugInCOM.h> <sys/cdefs.h> |
This documentation describes the details of the programming interface for accessing USB devices and USB interfaces from code running in user space. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications.
For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications.
This documentation also assumes you have read USB Device Interface Guide. Please review that document before using this reference.
Note that each succeeding version of an interface object, such as IOUSBDeviceInterface197, contains all the functions of all previous versions of that object and adds a few new functions. When you view the documentation for these objects, notice that each version is documented separately. For example, the documentation for IOUSBDeviceInterface197 contains information about the two new functions introduced in this version, but does not repeat the documentation for the functions introduced in IOUSBDeviceInterface187, IOUSBDeviceInterface182, and IOUSBDeviceInterface, even though IOUSBDeviceInterface197 provides access to all the functions contained in the earlier interface objects. For more information about determining which version of an interface object to use, see USB Device Interface Guide.
All of the information described in this document is contained in the header file IOUSBLib.h found at /System/Library/Frameworks/IOKit.framework/Headers/usb/IOUSBLib.h.
The object you use to access USB devices from user space, returned by all versions of the IOUSBFamily currently shipping.
The object you use to access USB devices from user space, returned by the IOUSBFamily version 1.8.2 and above.
The object you use to access USB devices from user space, returned by the IOUSBFamily version 1.8.7 and above.
The object you use to access USB devices from user space, returned by the IOUSBFamily version 1.9.7 and above.
The object you use to access USB devices from user space, returned by the IOUSBFamily version 2.4.5 and above.
The object you use to access USB devices from user space, returned by the IOUSBFamily version 3.0.0 and above.
The object you use to access a USB device interface from user space, returned by all versions of the IOUSBFamily currently shipping.
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.8.2 and above.
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.8.3 and above.
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.9 and above.
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.9.2 and above.
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.9.7 and above.
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 2.2.0 and above.
Gets a recent frame number of the bus to which the device is attached, along with a system time corresponding to the start of that frame
GetBusFrameNumberWithTime |
Gets a recent frame number of the bus to which the device is attached, along with a system time corresponding to the start of that frame
IOReturn ( *GetBusFrameNumberWithTime)( void *self, UInt64 *frame, AbsoluteTime *atTime);
selfPointer to the IOUSBInterfaceInterface.
framePointer to UInt64 to hold the frame number.
atTimePointer to a returned AbsoluteTime, which is the system time ("wall time") as close as possible to the beginning of that USB frame. The jitter on this value may be as much as 200 microseconds.
Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnUnsupported is the bus doesn't support this function.
The device does not have to be open to use this function.
kIOUSBDeviceInterfaceID |
#define kIOUSBDeviceInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x5c, 0x81, 0x87, 0xd0, 0x9e, 0xf3, 0x11, 0xD4, \ 0x8b, 0x45, 0x00, 0x0a, 0x27, 0x05, 0x28, 0x61)
This UUID constant is used to obtain a device interface corresponding to an IOUSBDevice user client in the kernel. The type of this device interface is IOUSBDeviceInterface. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBDeviceInterface is returned by all versions of the IOUSBFamily currently shipping. However, there are some functions that are available only in IOUSBFamily version 1.8.2 and above. Access to these functions, in addition to the functions contained in IOUSBDeviceInterface, can be obtained by using one of the other UUIDs listed in this header.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBDeviceInterface **dev; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID),
(LPVOID *)&dev);
kIOUSBDeviceInterfaceID182 |
#define kIOUSBDeviceInterfaceID182 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x15, 0x2f, 0xc4, 0x96, 0x48, 0x91, 0x11, 0xD5, \ 0x9d, 0x52, 0x00, 0x0a, 0x27, 0x80, 0x1e, 0x86)
This UUID constant is used to obtain a device interface corresponding to an IOUSBDevice user client in the kernel. The type of this device interface is IOUSBDeviceInterface182. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBDeviceInterface182 is returned only by version 1.8.2 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.0.4. If your software is running on an earlier version of Mac OS X, you will need to use the UUID kIOUSBDeviceInterfaceID and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBDeviceInterface182 **dev; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID182),
(LPVOID *)&dev);
kIOUSBDeviceInterfaceID187 |
#define kIOUSBDeviceInterfaceID187 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x3C, 0x9E, 0xE1, 0xEB, 0x24, 0x02, 0x11, 0xB2, \ 0x8E, 0x7E, 0x00, 0x0A, 0x27, 0x80, 0x1E, 0x86)
This UUID constant is used to obtain a device interface corresponding to an IOUSBDevice user client in the kernel. The type of this device interface is IOUSBDeviceInterface187. This device interface is obtained after the device interface for the service itself has been obtained (see kIOUSBDeviceUserClientTypeID ).
Note: The IOUSBDeviceInterface187 is returned only by version 1.8.7 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.1.2. If your software is running on an earlier version of Mac OS X you will need to use UUID kIOUSBDeviceInterfaceID or kIOUSBDeviceInterfaceID182 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBDeviceInterface187 **dev; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID187),
(LPVOID *)&dev);
kIOUSBDeviceInterfaceID197 |
#define kIOUSBDeviceInterfaceID197 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0xC8, 0x09, 0xB8, 0xD8, 0x08, 0x84, 0x11, 0xD7, \ 0xBB, 0x96, 0x00, 0x03, 0x93, 0x3E, 0x3E, 0x3E)
This UUID constant is used to obtain a device interface corresponding to an IOUSBDevice user client in the kernel. The type of this device interface is IOUSBDeviceInterface197. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBDeviceInterface197 is returned only by version 1.9.7 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.2.3. If your software is running on an earlier version of Mac OS X you will need to use UUID kIOUSBDeviceInterfaceID, kIOUSBDeviceInterfaceID182, or kIOUSBDeviceInterfaceID187 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBDeviceInterface197 **dev; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID197),
(LPVOID *)&dev);
kIOUSBDeviceInterfaceID300 |
#define kIOUSBDeviceInterfaceID300 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x39, 0x61, 0x04, 0xF7, 0x94, 0x3D, 0x48, 0x93, \ 0x90, 0xF1, 0x69, 0xBD, 0x6C, 0xF5, 0xC2, 0xEB)
This UUID constant is used to obtain a device interface corresponding to an IOUSBDevice user client in the kernel. The type of this device interface is IOUSBDeviceInterface300. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBDeviceInterface300 is returned only by version 3.0.0 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.5. If your software is running on an earlier version of Mac OS X you will need to use UUID kIOUSBDeviceInterfaceID, kIOUSBDeviceInterfaceID182, kIOUSBDeviceInterfaceID187, kIOUSBDeviceInterfaceID197, or kIOUSBDeviceInterfaceID245 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBDeviceInterface300 **dev; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBDeviceInterfaceID300),
(LPVoid)&dev);
kIOUSBDeviceUserClientTypeID |
#define kIOUSBDeviceUserClientTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x9d, 0xc7, 0xb7, 0x80, 0x9e, 0xc0, 0x11, 0xD4, \ 0xa5, 0x4f, 0x00, 0x0a, 0x27, 0x05, 0x28, 0x61)
This UUID constant is used to obtain a device interface corresponding to an io_service_t corresponding to an IOUSBDevice in the kernel. Once you have obtained the device interface for the service, you must use the QueryInterface function to obtain the device interface for the user client itself.
Example:
io_service_t usbDeviceRef; // obtained earlier
IOCFPlugInInterface **iodev; // fetching this now
SInt32 score; // not used
IOReturn err;
err = IOCreatePlugInInterfaceForService(usbDeviceRef,
kIOUSBDeviceUserClientTypeID,
kIOCFPlugInInterfaceID,
&iodev,
&score);
kIOUSBFactoryID |
#define kIOUSBFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x45, 0x47, 0xa8, 0xaa, 0x9e, 0xf3, 0x11, 0xD4, \ 0xa9, 0xbd, 0x00, 0x0a, 0x27, 0x05, 0x28, 0x61)
This UUID constant is used internally by the system, and should not have to be used by any driver code to access the device interfaces.
kIOUSBInterfaceInterfaceID |
#define kIOUSBInterfaceInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x73, 0xc9, 0x7a, 0xe8, 0x9e, 0xf3, 0x11, 0xD4, \ 0xb1, 0xd0, 0x00, 0x0a, 0x27, 0x05, 0x28, 0x61)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface is returned by all versions of the IOUSBFamily currently shipping. However, there are some functions which are available only in IOUSBFamily version 1.8.2 and above. Access to these functions, as well as to all of the functions contained in IOUSBInterfaceInterface, can be obtained by using one of the other UUIDs listed in this header.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID182 |
#define kIOUSBInterfaceInterfaceID182 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x49, 0x23, 0xac, 0x4c, 0x48, 0x96, 0x11, 0xD5, \ 0x92, 0x08, 0x00, 0x0a, 0x27, 0x80, 0x1e, 0x86)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface182. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface182 is returned only by version 1.8.2 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.0.4. If your software is running on an earlier version of Mac OS X, you will need to use the UUID kIOUSBInterfaceInterfaceID and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface182 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID182),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID183 |
#define kIOUSBInterfaceInterfaceID183 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x1c, 0x43, 0x83, 0x56, 0x74, 0xc4, 0x11, 0xD5, \ 0x92, 0xe6, 0x00, 0x0a, 0x27, 0x80, 0x1e, 0x86)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface183. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface183 is returned only by version 1.8.3 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.1. If your software is running on a version of Mac OS X prior to 10.1 you will need to use the UUID kIOUSBInterfaceInterfaceID or kIOUSBInterfaceInterfaceID182 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface183 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID183),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID190 |
#define kIOUSBInterfaceInterfaceID190 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x8f, 0xdb, 0x84, 0x55, 0x74, 0xa6, 0x11, 0xD6, \ 0x97, 0xb1, 0x00, 0x30, 0x65, 0xd3, 0x60, 0x8e)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface190. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface190 is returned only by version 1.9 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.2. If your software is running on a version of Mac OS X prior to 10.2 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, or kIOUSBInterfaceInterfaceID183 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface190 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID190),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID192 |
#define kIOUSBInterfaceInterfaceID192 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x6C, 0x79, 0x8A, 0x6E, 0xD6, 0xE9, 0x11, 0xD6, \ 0xAD, 0xD6, 0x00, 0x03, 0x93, 0x3E, 0x3E, 0x3E)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface192. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface192 is returned only by version 1.9.2 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.2.3. If your software is running on a version of Mac OS X prior to 10.2.3 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, or kIOUSBInterfaceInterfaceID190 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface192 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID192),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID197 |
#define kIOUSBInterfaceInterfaceID197 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0xC6, 0x3D, 0x3C, 0x92, 0x08, 0x84, 0x11, 0xD7, \ 0x96, 0x92, 0x00, 0x03, 0x93, 0x3E, 0x3E, 0x3E)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface197. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface197 is returned only by version 1.9.7 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.2.5. If your software is running on a version of Mac OS X prior to 10.2.5 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, or kIOUSBInterfaceInterfaceID192 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface197 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID197),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID220 |
#define kIOUSBInterfaceInterfaceID220 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x77, 0x0D, 0xE6, 0x0C, 0x2F, 0xE8, 0x11, 0xD8, \ 0xA5, 0x82, 0x00, 0x03, 0x93, 0xDC, 0xB1, 0xD0)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface197. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface220 is returned only by version 2.2.0 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.4. If your software is running on a version of Mac OS X prior to 10.4 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, kIOUSBInterfaceInterfaceID192, or kIOUSBInterfaceInterfaceID197 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface220 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID220),
(LPVOID *)&intf);
kIOUSBInterfaceInterfaceID245 |
#define kIOUSBInterfaceInterfaceID245 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x64, 0xBA, 0xBD, 0xD2, 0x0F, 0x6B, 0x4B, 0x4F, \ 0x8E, 0x3E, 0xDC, 0x36, 0x04, 0x69, 0x87, 0xAD)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface245. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface245 is returned only by version 2.4.5 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.4.5. This version does not add any new functions. It is used to allow us to fix a leak in our termination without affecting any current drivers: In previous versions, we would not release a reference to the IOUSBDevice. For IOUSBInterfaceInterfaceID245 clients we will now release that reference.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface245 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID245),
(LPVoid)&intf);
kIOUSBInterfaceInterfaceID300 |
#define kIOUSBInterfaceInterfaceID300 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0xBC, 0xEA, 0xAD, 0xDC, 0x88, 0x4D, 0x4F, 0x27, \ 0x83, 0x40, 0x36, 0xD6, 0x9F, 0xAB, 0x90, 0xF6)
This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface300. This device interface is obtained after the device interface for the service itself has been obtained.
Note: The IOUSBInterfaceInterface300 is returned only by version 3.0.0 or above of the IOUSBFamily. This version of IOUSBFamily shipped with Mac OS X version 10.5. If your software is running on a version of Mac OS X prior to 10.5 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, kIOUSBInterfaceInterfaceID192, kIOUSBInterfaceInterfaceID197, kIOUSBInterfaceInterfaceID220, or kIOUSBInterfaceInterfaceID245 and you will not have access to some functions.
Example:
IOCFPluginInterface **iodev; // obtained earlier
IOUSBInterfaceInterface300 **intf; // fetching this now
IOReturn err;
err = (*iodev)->QueryInterface(iodev,
CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID300),
(LPVoid)&intf);
kIOUSBInterfaceUserClientTypeID |
#define kIOUSBInterfaceUserClientTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x2d, 0x97, 0x86, 0xc6, 0x9e, 0xf3, 0x11, 0xD4, \ 0xad, 0x51, 0x00, 0x0a, 0x27, 0x05, 0x28, 0x61)
This UUID constant is used to obtain a device interface corresponding to an io_service_t corresponding to an IOUSBInterface in the kernel. Once you have obtained the device interface for the service, you must use the QueryInterface function to obtain the device interface for the user client itself.
Example:
io_service_t usbInterfaceRef; // obtained earlier
IOCFPlugInInterface **iodev; // fetching this now
SInt32 score; // not used
IOReturn err;
err = IOCreatePlugInInterfaceForService(usbInterfaceRef,
kIOUSBInterfaceUserClientTypeID,
kIOCFPlugInInterfaceID,
&iodev,
&score);
|
Last Updated: 2009-02-23