DeviceInterface.html [plain text]
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="Adobe GoLive 4">
<title>Functions</title>
</head>
<body bgcolor="white">
<h1><font face="Geneva,Arial,Helvtica">IOUSBDeviceInterface Functions</font></h1>
<p>The function pointers described here are accessed using any of the IOUSBDeviceInterface structures. This includes the original IOUSBDeviceInterface structure which shipped with the original Mac OS X, as well as IOUSBDeviceInterface<i>XXX</i> structure which shipped with subsequent versions of Mac OS X. Functions which were <i><b>not</b></i> available in the original API are documented as such.</p>
<hr>
<h3><a name="CreateDeviceAsyncEventSource"></a>CreateDeviceAsyncEventSource</h3>
<p><b>Abstract:</b> Create a run loop source for delivery of all asynchronous notifications on this device.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*CreateDeviceAsyncEventSource)(void *self, CFRunLoopSourceRef *source);</tt></blockquote>
</pre>
<p>The Mac OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications on a mach port (see createInterfaceAsyncPort below). This routine wraps that port with the appropriate routing code so that the completion notifications can be automatically routed through the clients CFRunLoop.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>source</tt></td>
<td>Pointer to a CFRunLoopSourceRef to return the newly created run loop event source.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful or a <font face="Courier New,Courier,Monaco">kern_return_t</font> if failed. <hr>
<h3><a name="CreateDeviceAsyncPort"></a>CreateDeviceAsyncPort</h3>
<p><b>Abstract:</b> Create and register a mach_port_t for asynchronous communications.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*CreateDeviceAsyncPort)(void *self, mach_port_t *port);</tt>
<br>
</blockquote>
</pre>
<p>The Mac OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications on this mach port. After receiving a message on this port the client is obliged to call the IOKitLib.h: IODispatchCalloutFromMessage() function for decoding the notification message.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>port</tt></td>
<td>Pointer to a mach_port_t to return the newly created port.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful or a <font face="Courier New,Courier,Monaco">kern_return_t</font> if failed. <hr>
<h3><a name="CreateInterfaceIterator"></a>CreateInterfaceIterator</h3>
<p><b>Abstract:</b> Creates an iterator to iterate over some or all of the interfaces of a device.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*CreateInterfaceIterator)(void *self, IOUSBFindInterfaceRequest *req, io_iterator_t *iter);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>req</tt></td>
<td>Pointer an IOUSBFindInterfaceRequest structure describing the desired interfaces.</td>
</tr>
<tr>
<td align="center"><tt>iter</tt></td>
<td>Pointer to a an io_iterator_t to contain the new iterator.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful or <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="DeviceRequest"></a>DeviceRequest</h3>
<p><b>Abstract:</b> Sends a USB request on the default control pipe.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*DeviceRequest)(void *self, IOUSBDevRequest *req);</tt></blockquote>
</pre>
<p>The device must be open to issue this call. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequest containing the request.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful or <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access. <hr>
<h3><a name="DeviceRequestAsync"></a>DeviceRequestAsync</h3>
<p><b>Abstract:</b> Sends an asynchronous USB request on the default control pipe. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*DeviceRequestAsync)(void *self, IOUSBDevRequest *req, IOAsyncCallback1 callback, void *refCon);</tt></blockquote>
</pre>
<p>The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td></td>
<td></td>
</tr>
<tr>
<td align="center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequest containing the request.</td>
</tr>
<tr>
<td align="center"><tt>callback</tt></td>
<td>An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.</td>
</tr>
<tr>
<td align="center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access, or <font face="Courier New,Courier,Monaco">kIOUSBNoAsyncPortErr</font> if no Async port has been created for this interface. <hr>
<h3><a name="DeviceRequestAsyncTO"></a>DeviceRequestAsyncTO</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Sends an asynchronous USB request on the default control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*DeviceRequestAsyncTO)(void *self, IOUSBDevRequestTO *req, IOAsyncCallback1 callback, void *refCon);</tt></blockquote>
</pre>
<p>The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequestTO containing the request.</td>
</tr>
<tr>
<td align="center"><tt>callback</tt></td>
<td>An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.</td>
</tr>
<tr>
<td align="center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access, or <font face="Courier New,Courier,Monaco">kIOUSBNoAsyncPortErr</font> if no Async port has been created for this interface. <hr>
<h3><a name="DeviceRequestTO"></a>DeviceRequestTO</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Sends a USB request on the default control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*DeviceRequestTO)(void *self, IOUSBDevRequestTO *req);</tt></blockquote>
</pre>
<p>The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequestTO containing the request.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access. <hr>
<h3><a name="GetBusFrameNumber"></a>GetBusFrameNumber</h3>
<p><b>Abstract:</b> Gets the current frame number of the bus to which the device is attached.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetBusFrameNumber)(void *self, UInt64 *frame, AbsoluteTime *atTime);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>frame</tt></td>
<td>Pointer to UInt64 to hold the frame number.</td>
</tr>
<tr>
<td align="center"><tt>atTime</tt></td>
<td>Pointer to a returned AbsoluteTime, which should be within 1ms of the time when the bus frame number was attained.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService.
<hr>
<h3><a name="GetBusMicroFrameNumber"></a>GetBusMicroFrameNumber</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface197 and above.</b></p>
<b>Abstract:</b> Gets the current micro frame number of the bus to which the device is attached.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetBusMicroFrameNumber)(void *self, UInt64 *microFrame, AbsoluteTime *atTime);</tt></pre>
</blockquote>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>microFrame</tt></td>
<td>Pointer to UInt64 to hold the microframe number.</td>
</tr>
<tr>
<td align="center"><tt>atTime</tt></td>
<td>Pointer to an AbsoluteTime, which should be within 1ms of the time when the bus frame number was acquired.</td>
</tr>
</table>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService.</p>
<hr>
<h3><a name="GetConfiguration"></a>GetConfiguration</h3>
<p><b>Abstract:</b> Return the currently selected configuration in the device.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetConfiguration)(void *self, UInt8 *configNum);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>configNum</tt></td>
<td>Pointer to UInt8 to hold the configuration value.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetConfigurationDescriptorPtr"></a>GetConfigurationDescriptorPtr</h3>
<p><b>Abstract:</b> Return a pointer to a configuration descriptor for a given index. Note that this will point to the data as received from the USB bus and hence will be in USB bus order (i.e. little endian). <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetConfigurationDescriptorPtr)(void *self, UInt8 configIndex, IOUSBConfigurationDescriptorPtr *desc);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>configIndex</tt></td>
<td>The index (zero based) of the desired config descriptor.</td>
</tr>
<tr>
<td align="center"><tt>desc</tt></td>
<td>Pointer to an <tt>IOUSBConfigurationDescriptorPtr</tt> to hold the result.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceAddress"></a>GetDeviceAddress</h3>
<p><b>Abstract:</b> Return the address of the device on its bus.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceAddress)(void *self, USBDeviceAddress *addr);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>addr</tt></td>
<td>Pointer to USBDeviceAddress to hold the result.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceAsyncEventSource"></a>GetDeviceAsyncEventSource</h3>
<p><b>Abstract:</b> Return the CFRunLoopSourceRef for this IOService instance.
<pre>
<blockquote>
<tt> <b>CFRunLoopSourceRef</b>(*GetDeviceAsyncEventSource)(void *self);</tt></blockquote>
</pre>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns the run loop source if one has been created, 0 otherwise.
<hr>
<h3><a name="GetDeviceAsyncPort"></a>GetDeviceAsyncPort</h3>
<p><b>Abstract:</b> Return the mach_port_t port for this IOService instance.
<pre>
<blockquote>
<tt> <b>mach_port_t</b>(*GetDeviceAsyncPort)(void *self);</tt></blockquote>
</pre>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns the port if one exists, 0 otherwise.
<hr>
<h3><a name="GetDeviceBusPowerAvailable"></a>GetDeviceBusPowerAvailable</h3>
<p><b>Abstract:</b> Return the power available to the device.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceBusPowerAvailable)(void *self, UInt32 *powerAvailable);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>powerAvailable</tt></td>
<td>Pointer to UInt32 to hold the power available (in 2 mA increments).</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceClass"></a>GetDeviceClass</h3>
<p><b>Abstract:</b> Return the USB Class (<font face="Courier New,Courier,Monaco">bDeviceClass</font>) of the device. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceClass)(void *self, UInt8 *devClass);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devClass</tt></td>
<td>Pointer to UInt8 to hold the device Class</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceProduct"></a>GetDeviceProduct</h3>
<p><b>Abstract:</b> Return the USB Product ID (<font face="Courier New,Courier,Monaco">idProduct</font>) of the device. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceProduct)(void *self, UInt16 *devProduct);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devProduct</tt></td>
<td>Pointer to UInt16 to hold the ProductID</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceProtocol"></a>GetDeviceProtocol</h3>
<p><b>Abstract:</b> Return the USB Protocol (<font face="Courier New,Courier,Monaco">bDeviceProtocol</font>) of the interface. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceProtocol)(void *self, UInt8 *devProtocol);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devProtocol</tt></td>
<td>Pointer to UInt8 to hold the device Protocol</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3> </h3>
<h3><a name="GetDeviceReleaseNumber"></a>GetDeviceReleaseNumber</h3>
<p><b>Abstract:</b> Return the Device Release Number (<font face="Courier New,Courier,Monaco">bcdDevice</font>) of the device. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceReleaseNumber)(void *self, UInt16 *devRelNum);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devRelNum</tt></td>
<td>Pointer to UInt16 to hold the Device Release Number</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceSpeed"></a>GetDeviceSpeed</h3>
<p><b>Abstract:</b> Return the speed of the device.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceSpeed)(void *self, UInt8 *devSpeed);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devSpeed</tt></td>
<td>Pointer to UInt8 to hold the speed (<font face="Courier New,Courier,Monaco">kUSBDeviceSpeedLow</font>, <font face="Courier New,Courier,Monaco">kUSBDeviceSpeedFull</font> or <font face="Courier New,Courier,Monaco">kUSBDeviceSpeedHigh</font>)</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceSubClass"></a>GetDeviceSubClass</h3>
<p><b>Abstract:</b> Return the USB Subclass (<font face="Courier New,Courier,Monaco">bDeviceSubClass</font>) of the device. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceSubClass)(void *self, UInt8 *devSubClass);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devSubClass</tt></td>
<td>Pointer to UInt8 to hold the device Subclass</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetDeviceVendor"></a>GetDeviceVendor</h3>
<p><b>Abstract:</b> Return the USB Vendor ID (<font face="Courier New,Courier,Monaco">idVendor</font>) of the device. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetDeviceVendor)(void *self, UInt16 *devVendor);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>devVendor</tt></td>
<td>Pointer to UInt16 to hold the vendorID</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService.
<hr>
<h3><a name="GetIOUSBLibVersion"></a>GetIOUSBLibVersion</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface197 and above.</b></p>
<b>Abstract:</b> Returns the version of the IOUSBLib and the version of the IOUSBFamily.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetIOUSBLibVersion)(void *self, NumVersion *ioUSBLibVersion, NumVersion *usbFamilyVersion);</tt></pre>
</blockquote>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>ioUSBLibVersion</tt></td>
<td>Pointer to a NumVersion structure that on return will contain the version of the IOUSBLib.</td>
</tr>
<tr>
<td align="center"><tt>usbFamilyVersion</tt></td>
<td>Pointer to a NumVersion structure that on return will contain the version of the IOUSBFamily.</td>
</tr>
</table>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. </p>
<hr>
<h3><a name="GetLocationID"></a>GetLocationID</h3>
<p><b>Abstract:</b> Return the location ID. This is a 32 bit number which is unique among all USB devices in the system, and which will not change on a system reboot unless the topology of the bus itself changes. <pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetLocationID)(void *self, UInt32 *locationID);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>locationID</tt></td>
<td>Pointer to UInt32 to hold the location ID.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="GetNumberOfConfigurations"></a>GetNumberOfConfigurations</h3>
<p><b>Abstract:</b> Return the number of supported configurations in this device.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*GetNumberOfConfigurations)(void *self, UInt8 *numConfig);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>numConfig</tt></td>
<td>Pointer to UInt8 to hold the number of configurations.</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="ResetDevice"></a>ResetDevice</h3>
<p><b>Abstract:</b> Tells the IOUSBFamily to issue a reset to the device. It will not reenumerate the device, which means that the cached device descriptor values will not be updated after the reset. (If you want the IOUSBFamily to reload the cached values, use the call <a href="#USBDeviceReEnumerate">USBDeviceReEnumerate</a>). Prior to version 1.8.5 of the IOUSBFamily, this call also sent a message to all clients of the IOUSBDevice (IOUSBInterfaces and their drivers). This behavior was eliminated with version 1.8.5 of the IOUSBFamily.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*ResetDevice)(void *self);</tt></blockquote>
</pre>
<p>The device must be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access. <hr>
<h3><a name="SetConfiguration"></a>SetConfiguration</h3>
<p><b>Abstract:</b> Sets the configuration in the device. Note that setting the configuration causes any existing IOUSBInterface objects attached to the IOUSBDevice to be destroyed, and all of the interfaces in the new configuration to be instantiated as new IOUSBInterface objects.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*SetConfiguration)(void *self, UInt8 configNum);</tt></blockquote>
</pre>
<p>The device must be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>configNum</tt></td>
<td>The value of the desired configuration (from IOUSBConfigurationDescriptor.bConfigurationValue).</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access. <hr>
<h3><a name="USBDeviceAbortPipeZero"></a>USBDeviceAbortPipeZero</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Abort a transaction on the default control pipe.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBDeviceAbortPipeZero)(void *self);</tt></blockquote>
</pre>
<p>The device must be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access. <hr>
<h3><a name="USBDeviceClose"></a>USBDeviceClose</h3>
<p><b>Abstract:</b> Close the task's connection to the IOUSBDevice.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBDeviceClose)(void *self);</tt></blockquote>
</pre>
<p>Release the clients exclusive access to the IOUSBDevice.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, some other mach error if the connection is no longer valid. <hr>
<h3><a name="USBDeviceOpen"></a>USBDeviceOpen</h3>
<p><b>Abstract:</b> Open up the IOUSBDevice for exclusive access.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBDeviceOpen)(void *self);</tt></blockquote>
</pre>
<p>Before the client can issue commands which change the state of the device, it must have succeeded in opening the device. This establishes an exclusive link between the clients task and the actual device.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnExclusiveAccess</font> if some other task has the device opened already, <font face="Courier New,Courier,Monaco">kIOReturnError</font> if the connection with the kernel can not be established or <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful.
<hr>
<h3><a name="USBDeviceOpenSeize"></a>USBDeviceOpenSeize</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Open up the IOUSBDevice for exclusive access. If another client
has the device opened, an attempt is made to get that client to close it before
returning.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBDeviceOpenSeize)(void *self);</tt></blockquote>
</pre>
<p>Before the client can issue commands which change the state of the device,
it must have succeeded in opening the device. This establishes an exclusive
link between the clients task and the actual device.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnExclusiveAccess</font> if some other task has the device opened already and refuses to close it, <font face="Courier New,Courier,Monaco">kIOReturnError</font> if the connection with the kernel can not be established or <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful.
<hr>
<p></p>
<h3><a name="USBDeviceReEnumerate"></a>USBDeviceReEnumerate</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface187 and above.</b></p>
<p><b>Abstract:</b> Tells the IOUSBFamily to reenumerate the device. This will
send a terminate message to all clients of the IOUSBDevice (such as IOUSBInterfaces
and their drivers, as well as the current User Client), emulating an unplug
of the device. The IOUSBFamily will then enumerate the device as if it had just
been plugged in. This call should be used by clients wishing to take advantage
of the Device Firmware Update Class specification. </p>
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBDeviceReEnumerate)(void *self,UInt32 options);</tt></blockquote>
</pre>
<p>The device must be open.</p>
<p><b>Parameters</b></p>
<blockquote>
<p>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>options</tt></td>
<td>A UInt32 reserved for future use. Ignored in current implementation.
Set to zero.</td>
</tr>
</table>
<p></p>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access.
<hr>
<h3><a name="USBDeviceSuspend"></a>USBDeviceSuspend</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Tell the USB Family to either suspend or resume the port to which a device is attached.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBDeviceSuspend)(void *self, Boolean suspend);</tt></blockquote>
</pre>
<p>The device must be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>suspend</tt></td>
<td>TRUE to cause the port to be suspended, FALSE to cause it to be resumed</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the device is not open for exclusive access. <hr>
<h3><a name="USBGetManufacturerStringIndex"></a>USBGetManufacturerStringIndex</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Return the manufacturer string index in the device descriptor.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBGetManufacturerStringIndex)(void *self, UInt8 *msi);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>msi</tt></td>
<td>Pointer to UInt8 to hold the string index</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<h3><a name="USBGetProductStringIndex"></a>USBGetProductStringIndex</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Return the product string index in the device descriptor.
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBGetProductStringIndex)(void *self, UInt8 *psi);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>psi</tt></td>
<td>Pointer to UInt8 to hold the string index</td>
</tr>
</table>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService. <hr>
<p></p>
<h3><a name="USBGetSerialNumberStringIndex"></a>USBGetSerialNumberStringIndex</h3>
<p><b>Note: This function is only available with IOUSBDeviceInterface182 and above.</b></p>
<p><b>Abstract:</b> Return the serial number string index in the device descriptor.</p>
<pre>
<blockquote>
<tt> <b>IOReturn</b>(*USBGetSerialNumberStringIndex)(void *self, UInt8 *snsi);</tt></blockquote>
</pre>
<p>The device does not have to be open.</p>
<h4>Parameters</h4>
<blockquote>
<p>
<table border="1" width="90%">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tr>
<td align="center"><tt>self</tt></td>
<td>Pointer to the IOUSBDeviceInterface</td>
</tr>
<tr>
<td align="center"><tt>snsi</tt></td>
<td>Pointer to UInt8 to hold the string index</td>
</tr>
</table>
<p></p>
</blockquote>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNoDevice</font> if there is no connection to an IOService.
<p>
<hr>
<p></p>
<h3>
<p>© 2001-2003 Apple Computer, Inc. — (Last Updated May 7, 2003)</h3>
</body>
</html>