InterfaceInterface.html [plain text]
<html><head><title>Functions</title></head><body bgcolor="#ffffff">
<font face="Geneva,Arial,Helvtica">
<h1>IOUSBInterfaceInterface Functions</h1>
</font>
<p>The function pointers described here are accessed using any of the IOUSBInterfaceInterface structures. This includes the original IOUSBInterfaceInterface structure which shipped with the original Mac OS X (10.0), as well as IOUSBInterfaceInterface<i>XXX</i> structures 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="AbortPipe"></a>AbortPipe</h3>
<b>Abstract:</b> Aborts any outstanding transactions on the pipe with status kIOReturnAborted. If there are outstanding asynchronous transaction on the pipe, the callbacks will happen. Note that this command will also clear both the halted bit and the data toggle bit on the endpoint in the controller. The data toggle may need to be resynchronized. See <a href="#ClearPipeStall">ClearPipeStall</a> or <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.
<blockquote>
<pre><tt> <b>IOReturn</b>(*AbortPipe)(void *self, UInt8 pipeRef);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ClearPipeStall"></a>ClearPipeStall</h3>
<b>Abstract:</b> This function clears the halted bit and the data toggle bit on the pipe's endpoint in the controller. It will also return any outstanding transactions on the pipe with status kIOUSBTransactionReturned. If there are outstanding asynchronous transaction on the pipe, the callbacks will happen. The data toggle may need to be resynchronized. The driver may handle this by sending a ClearFeature(ENDPOINT_HALT) to the default control pipe, specifying the device's endpoint for this pipe. See also <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ClearPipeStall)(void *self, UInt8 pipeRef);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ClearPipeStallBothEnds"></a>ClearPipeStallBothEnds</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface190 and
above.</b></p>
<b></b><b></b><b></b><b>Abstract:</b> This function is equivalent to ClearPipeStall
except that it will also attempt to clear the halt and toggle bits on the device's
endpoint for the pipe by sending a ClearFeature(ENDPOINT_HALT) to the default
control pipe in the device, specifying the endpoint for the pipe represented by
pipeRef. For most devices, this will resynchronize the data toggle between the
two endpoints to ensure that there is no loss of data.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ClearPipeStallBothEnds)(void *self, UInt8 pipeRef);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ControlRequest"></a>ControlRequest</h3>
<b>Abstract:</b> Sends a USB request on a control pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ControlRequest)(void *self, UInt8 pipeRef, IOUSBDevRequest *req);</tt></pre>
</blockquote>
<p>If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.
</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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index of the control pipe to use. Use zero for the default control pipe
on the device.</td>
<tr>
<td align = "center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequest containing the request.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ControlRequestAsync"></a>ControlRequestAsync</h3>
<b>Abstract:</b> Sends an asynchronous USB request on a control pipe. Use pipeRef=0
for the default device control pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ControlRequestAsync)(void *self, UInt8 pipeRef, IOUSBDevRequest *req, IOAsyncCallback1 callback, void *refCon);</tt></pre>
</blockquote>
<p>If the request is a standard request which will change the state of the device,
the device must be open, which means you should be using the IOUSBDeviceInterface
for this command. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index of the control pipe to use. Use zero for the default control pipe
on the device.</td>
<tr>
<td align = "center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequest containing the request.</td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<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 interface 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="ControlRequestAsyncTO"></a>ControlRequestAsyncTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b>Abstract:</b> Sends an asynchronous USB request on a control pipe. The IOUSBDevRequestTO
structure allows the client to specify timeout values for this request. Use pipeRef=0
for the default device control pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ControlRequestAsyncTO)(void *self, UInt8 pipeRef, IOUSBDevRequestTO *req, IOAsyncCallback1 callback, void *refCon);</tt></pre>
</blockquote>
<p>If the request is a standard request which will change the state of the device,
the device must be open, which means you should be using the IOUSBDeviceInterface
for this command. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index of the control pipe to use. Use zero for the default control pipe
on the device.</td>
<tr>
<td align = "center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequestTO containing the request.</td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<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 interface 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="ControlRequestTO"></a>ControlRequestTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b>Abstract:</b> Sends a USB request on a control pipe. The IOUSBDevRequestTO
structure allows the client to specify timeout values for this request.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ControlRequestTO)(void *self, UInt8 pipeRef, IOUSBDevRequestTO *req);</tt></pre>
</blockquote>
<p>If the request is a standard request which will change the state of the device,
the device must be open, which means you should be using the IOUSBDeviceInterface
for this command. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index of the control pipe to use. Use zero for the default control pipe
on the device.</td>
<tr>
<td align = "center"><tt>req</tt></td>
<td>Pointer to an IOUSBDevRequestTO containing the request.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="CreateInterfaceAsyncEventSource"></a>CreateInterfaceAsyncEventSource</h3>
<b>Abstract:</b> Create a run loop source for delivery of all asynchronous notifications on this device.
<blockquote>
<pre><tt> <b>IOReturn</b>(*CreateInterfaceAsyncEventSource)(void *self, CFRunLoopSourceRef *source);</tt></pre>
</blockquote>
<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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>source</tt></td><td>Pointer to a CFRunLoopSourceRef to return the newly created run loop event source.</td>
</table>
</blockquote>
<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="CreateInterfaceAsyncPort"></a>CreateInterfaceAsyncPort</h3>
<b>Abstract:</b> Create and register a mach_port_t for asynchronous communications.
<blockquote><pre><tt> <b>IOReturn</b>(*CreateInterfaceAsyncPort)(void *self, mach_port_t *port);
</tt><br>
</pre></blockquote>
<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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>port</tt></td><td>Pointer to a mach_port_t to return the newly created port.</td>
</table>
</blockquote>
<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="GetAlternateSetting"></a>GetAlternateSetting</h3>
<b>Abstract:</b> Return the alternate setting currently selected in this interface.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetAlternateSetting)(void *self, UInt8 *intfAltSetting);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>intfAltSetting</tt></td>
<td>Pointer to UInt8 to hold the alternate setting value.</td>
</table>
</blockquote>
<b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetBandwidthAvailable"></a>GetBandwidthAvailable</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface190 and above.</b></p>
<p><b>Abstract:</b> Returns the amount of bandwidth available (in bytes per 1ms frame) on the bus for allocation to Isochronous pipes. This is useful for determining the correct AltInterface setting as well as for using <a href="#SetPipePolicy">SetPipePolicy</a>.</p>
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetBandwidthAvailable)(void *self, UInt32 *bandwidth);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>bandwidth</tt></td>
<td>Pointer to UInt32 to hold the amount of bandwidth available (in bytes
per 1ms frame).</td>
</table>
</blockquote>
<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="GetBusFrameNumber"></a>GetBusFrameNumber</h3>
<b>Abstract:</b> Gets the current frame number of the bus to which the interface and its device is attached.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetBusFrameNumber)(void *self, UInt64 *frame, AbsoluteTime *atTime);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</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 an AbsoluteTime, which should be within 1ms of the time when the bus frame number was attained.</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="GetBusMicroFrameNumber"></a>GetBusMicroFrameNumber</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface197 and above.</b></p>
<b>Abstract:</b> Gets the current micro frame number of the bus to which the interface and its device is attached.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetBusMicroFrameNumber)(void *self, UInt64 *microFrame, AbsoluteTime *atTime);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
</tr>
<tr>
<td align="center"><tt>microFrame</tt></td>
<td>Pointer to UInt64 to hold the microrame 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 attained.</td>
</tr>
</table>
<p><b>Result:</b> Returns <font face="Courier New,Courier,mono">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="GetConfigurationValue"></a>GetConfigurationValue</h3>
<b>Abstract:</b> Return the current configuration value set in the device. The interface will be part of that configuration.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetConfigurationValue)(void *self, UInt8 *configVal);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>configVal</tt></td><td>Pointer to UInt8 to hold the configuration value.</td>
</table>
</blockquote>
<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="GetDevice"></a>GetDevice</h3>
<b>Abstract:</b> Return the device of which this interface is part.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetDevice)(void *self, io_service_t *device);</tt></pre>
</blockquote>
<p>The interface does not have to be open. The returned device can be used to create a CFPlugin to talk to the 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>device</tt></td><td>Pointer to io_service_t to hold the result.</td>
</table>
</blockquote>
<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>
<b>Abstract:</b> Return the USB Product ID (<font face="Courier New,Courier,Monaco">idProduct</font>) of the device of which this interface is a part.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetDeviceProduct)(void *self, UInt16 *devProduct);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>devProduct</tt></td><td>Pointer to UInt16 to hold the ProductID</td>
</table>
</blockquote>
<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="GetDeviceReleaseNumber"></a>GetDeviceReleaseNumber</h3>
<b>Abstract:</b> Return the Device Release Number (<font face="Courier New,Courier,Monaco">bcdDevice</font>) of the device of which this interface is a part.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetDeviceReleaseNumber)(void *self, UInt16 *devRelNum);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>devRelNum</tt></td><td>Pointer to UInt16 to hold the Release Number</td>
</table>
</blockquote>
<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>
<b>Abstract:</b> Return the USB Vendor ID (<font face="Courier New,Courier,Monaco">idVendor</font>) of the device of which this interface is a part.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetDeviceVendor)(void *self, UInt16 *devVendor);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>devVendor</tt></td>
<td>Pointer to UInt16 to hold the vendorID</td>
</table>
</blockquote>
<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="GetEndpointProperties"></a>GetEndpointProperties</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface190 and above.</b></p>
<p><b>Abstract:</b> Returns the transfer type, max packet size, and interval of a
specified endpoint, whether or not the endpoint has a pipe currently established.This
may be useful for determining which alternate interface to select when trying
to balance bandwidth allocations among isochronous pipes. </p>
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetEndpointProperties)(void *self, UInt8 alternateSetting, UInt8 endpointNumber, UInt8 direction, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>alternateSetting</tt></td>
<td>Specifies the alternate setting within the current interface.</td>
<tr>
<td align = "center"><tt>enpointNumber</tt></td>
<td>Specifies the desired endpoint number.</td>
<tr>
<td align = "center"><tt>direction</tt></td>
<td>Specifies the desired direction.</td>
<tr>
<td align = "center"><tt>transferType</tt></td>
<td>Pointer to UInt8 to hold the endpoint's transfer type (kUSBControl,
kUSBIsoc, etc)</td>
<tr>
<td align = "center"><tt>maxPacketSize</tt></td>
<td>Pointer to UInt16 to hold the maxPacketSize of the endpoint</td>
<tr>
<td align = "center"><tt>interval</tt></td>
<td>Pointer to UInt8 to hold the polling interval for interrupt endpoints</td>
</table>
</blockquote>
<b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Courier New,Courier,Monaco">kIOReturnNotAttached</font> if there is no connection to an IOService.
<hr>
<h3><a name="GetFrameListTime"></a>GetFrameListTime</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface197 and above.</b></p>
<b>Abstract:</b> Returns the number of microseconds in each USB Frame.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetFrameListTime)(void *self, UInt32 *microsecondsInFrame);</tt></pre>
</blockquote>
<p>This function can be used to determine whether the device is functioning in full speed or a high speed. In the case of a full speed device, the returned value will be <i>kUSBFullSpeedMicrosecondsInFrame</i>. In the case of a high speed device, the return value will be <i>kUSBHighSpeedMicrosecondsInFrame</i>. (This API should really be called GetUSBFrameTime). </p>
<p>The interface 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 IOUSBInterfaceInterface</td>
</tr>
<tr>
<td align="center"><tt>microsecondsInFrame</tt></td>
<td>Pointer to UInt32 to hold the number of microseconds in each USB frame.</td>
</tr>
</table>
<p><b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Times New Roman,Georgia,Times">kIOReturnNoDevice</font> if there is no connection to an IOService.</p>
<hr>
<h3><a name="GetInterfaceAsyncEventSource"></a>GetInterfaceAsyncEventSource</h3>
<b>Abstract:</b> Return the CFRunLoopSourceRef for this IOService instance.
<blockquote>
<pre><tt> <b>CFRunLoopSourceRef</b>(*GetInterfaceAsyncEventSource)(void *self);</tt></pre>
</blockquote>
<p></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 IOUSBInterfaceInterface</td>
</table>
</blockquote>
<b>Result:</b> Returns the run loop source if one has been created, 0 otherwise.
<hr>
<h3><a name="GetInterfaceAsyncPort"></a>GetInterfaceAsyncPort</h3>
<b>Abstract:</b> Return the mach_port_t port for this IOService instance.
<blockquote>
<pre><tt> <b>mach_port_t</b>(*GetInterfaceAsyncPort)(void *self);</tt></pre>
</blockquote>
<p></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 IOUSBInterfaceInterface</td>
</table>
</blockquote>
<b>Result:</b> Returns the port if one exists, 0 otherwise.
<hr>
<h3><a name="GetInterfaceClass"></a>GetInterfaceClass</h3>
<b>Abstract:</b> Return the USB Class of the interface (<font face="Courier New,Courier,Monaco">bInterfaceClass</font>) .
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetInterfaceClass)(void *self, UInt8 *intfClass);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>intfClass</tt></td><td>Pointer to UInt8 to hold the interface Class</td>
</table>
</blockquote>
<b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnSuccess</font> if successful, <font face="Times New Roman,Georgia,Times">kIOReturnNoDevice</font> if there is no connection to an IOService.
<hr>
<h3><a name="GetInterfaceNumber"></a>GetInterfaceNumber</h3>
<b>Abstract:</b> Return the interface number (zero based index) of this interface within the current configuration of the device.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetInterfaceNumber)(void *self, UInt8 *intfNumber);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>intfNumber</tt></td>
<td>Pointer to UInt8 to hold the interface number</td>
</table>
</blockquote>
<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="GetInterfaceProtocol"></a>GetInterfaceProtocol</h3>
<b>Abstract:</b> Return the USB Protocol of the interface (<font face="Courier New,Courier,Monaco">bInterfaceProtocol</font>).
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetInterfaceProtocol)(void *self, UInt8 *intfProtocol);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td><tr>
<tr><td align = "center"><tt>intfProtocol</tt></td><td>Pointer to UInt8 to hold the interface Protocol</td><tr>
</table>
</blockquote>
<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="GetInterfaceSubClass"></a>GetInterfaceSubClass</h3>
<b>Abstract:</b> Return the USB Subclass of the interface (<font face="Courier New,Courier,Monaco">bInterfaceSubClass</font>).
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetInterfaceSubClass)(void *self, UInt8 *intfSubClass);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>intfSubClass</tt></td><td>Pointer to UInt8 to hold the interface Subclass</td>
</table>
</blockquote>
<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 IOUSBInterfaceInterface197 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 interface 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 IOUSBInterfaceInterface</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">usbFamilyVersion</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>
<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.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetLocationID)(void *self, UInt32 *locationID);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>locationID</tt></td><td>Pointer to UInt32 to hold the location ID.</td>
</table>
</blockquote>
<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="GetNumEndpoints"></a>GetNumEndpoints</h3>
<b>Abstract:</b> Return the number of endpoints in this interface.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetNumEndpoints)(void *self, UInt8 *intfNumEndpoints);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr><td align = "center"><tt>intfNumEndpoints</tt></td><td>Pointer to UInt8 to hold the number of endpoints.</td>
</table>
</blockquote>
<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="GetPipeProperties"></a>GetPipeProperties</h3>
<b>Abstract:</b> Gets the properties for a pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetPipeProperties)(void *self, UInt8 pipeRef, UInt8 *direction, UInt8 *number, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval);</tt></pre>
</blockquote>
<p>Once an Interface is opened, all of the pipes in that Interface get created
by the kernel. The number of pipes can be retrieved by GetNumEndpoints. The
client can then get the properties of any pipe using an index of 1 to GetNumEndpoints.
Pipe 0 is the default control pipe in the 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>direction</tt></td>
<td>Pointer to an UInt8 to get the direction of the pipe.</td>
<tr>
<td align = "center"><tt>number</tt></td>
<td>Pointer to an UInt8 to get the pipe number.</td>
<tr>
<td align = "center"><tt>transferType</tt></td>
<td>Pointer to an UInt8 to get the transfer type of the pipe.</td>
<tr>
<td align = "center"><tt>maxPacketSize</tt></td>
<td>Pointer to an UInt16 to get the maxPacketSize of the pipe.</td>
<tr>
<td align = "center"><tt>interval</tt></td>
<td>Pointer to an UInt8 to get the interval for polling the pipe for data
(in milliseconds).</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="GetPipeStatus"></a>GetPipeStatus</h3>
<b>Abstract:</b> Gets the current status of a pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*GetPipeStatus)(void *self, UInt8 pipeRef);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</table>
</blockquote>
<b>Result:</b> Returns <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 interface is not open for exclusive access. Otherwise, the status of the pipe is returned. Returns <font face="Courier New,Courier,Monaco">kIOUSBPipeStalled</font> if the pipe is stalled. See <a href="#ClearPipeStall">ClearPipeStall</a> or <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.
<hr>
<h3><b><a name="LowLatencyCreateBuffer" id="LowLatencyCreateBuffer"></a>LowLatencyCreateBuffer</b></h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface192 and
above.</b></p>
<b>Abstract:</b> This function will allocate a buffer of type <code>bufferType</code>.
This buffer can then be used with the <code>LowLatencyIsochReadPipeAsync()</code>
or <code>LowLatencyIsochWritePipeAsync()</code> calls.
<blockquote>
<pre><tt> IOReturn (*<strong>LowLatencyCreateBuffer</strong>) (void * self, void **buffer, IOByteCount size,
UInt32 bufferType);</tt></pre>
</blockquote>
<p>The <code>LowLatencyIsochReadPipeAsync()</code> or <code>LowLatencyIsochWritePipeAsync()</code>
calls require the clients to pre-allocate the data buffer and the frame list
buffer parameters. This call is used to allocate those buffers. After the client
is done using the buffers, they need to be released through the <code>LowLatencyDestroyBuffer()</code>
call.</p>
<p>If the buffer is to be used for reading data, the type passed in should be
<code>kUSBLowLatencyReadBuffer.</code> If the buffer is to be used for writing
data, the type should be <code>kUSBLowLatencyWriteBuffer</code>. For frame list
data, the type should be <code>kUSBLowLatencyFrameListBuffer</code>.</p>
<p>The client can create multiple data and frame list buffers, or it can allocate
a large buffer and then use only a portion of the buffer in calls to <code>LowLatencyReadIsochPipeAsync()</code>
or <code>LowLatencyWriteIsochPipeAsync().</code> </p>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>buffer</tt></td>
<td>Pointer to a pointer that will receive the pointer to the buffer created
by this call. </td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>The size of the buffer to be created in bytes.</td>
<tr>
<td align = "center"><tt>bufferType</tt></td>
<td>Type of buffer: one of <code>kUSBLowLatencyWriteBuffer</code>, <code>kUSBLowLatencyReadBuffer</code>,
or <code>kUSBLowLatencyFrameListBuffer</code>. See USB.h.</td>
</table>
</blockquote>
<b>Result:</b> Returns <code>kIOReturnSuccess</code> if successful, <code>kIOReturnNoDevice</code>
if there is no connection to an <code>IOService</code>, or <code>kIOReturnNotOpen</code>
if the interface is not open for exclusive access. If the buffer can't be allocated,
it will return <code>kIOReturnNoMemory</code>.
<hr>
<h3><b><a name="LowLatencyDestroyBuffer" id="LowLatencyDestroyBuffer"></a>LowLatencyDestroyBuffer</b></h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface192 and
above.</b></p>
<b></b><b>Abstract:</b> Releases a buffer that was previously allocated using
LowLatencyCreateBuffer().
<blockquote>
<pre><tt> IOReturn (*<strong>LowLatencyDestroyBuffer</strong>) (void * self, void * buffer );</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>buffer</tt></td>
<td>Pointer to the buffer previously allocated using LowLatencyCreateBuffer().</td>
</table>
</blockquote>
<b>Result:</b> Returns <code>kIOReturnSuccess</code> if successful, <code>kIOReturnNoDevice</code>
if there is no connection to an <code>IOService</code>, or <code>kIOReturnNotOpen</code>
if the interface is not open for exclusive access. If the buffer was not previously
allocated using <code>LowLatencyCreateBuffer</code>() it will return <code>kIOReturnBadArgument</code>.
<hr>
<h3><b><a name="LowLatencyReadIsochPipeAsync" id="LowLatencyReadIsochPipeAsync"></a>LowLatencyReadIsochPipeAsync</b></h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface192 and
above.</b></p>
<b></b><b></b><b>Abstract:</b> Does an asynchronous read on a ISOCHRONOUS pipe
and updates the frame list at primary interrupt time.
<blockquote>
<pre><tt> IOReturn (*<strong>LowLatencyReadIsochPipeAsync</strong>)(void *self, UInt8 pipeRef, void *buf,
UInt64 frameStart, UInt32 numFrames, UInt32 updateFrequency,
IOUSBLowLatencyIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon)</tt></pre>
</blockquote>
<p>The <code>LowLatencyReadIsochPipeAsync()</code> and <code>LowLatencyWriteIsochPipeAsync()</code>
calls are analogous to <code>ReadIsochPipeAsync()</code> and <code>WriteIsochPipeAsync().</code>
They differ in that the frame list data is updated at <em>primary interrupt
time</em>. This means that the client can inspect the <code>frStatus</code>
and <code>frActCount</code> fields as soon as the transaction has been completed,
without having to wait for the callback to happen (depending on the value of
<code>updateFrequency</code>). The callback will still happen when the all the
frames have been received. </p>
<p>The client can specify how often the USB stack should update the frame list
data by specifying the <code>updateFrequency</code>: this value can range from
0 - 8. If the value is between 1 and 8, the frame list will be updated every
<code>updateFrequency</code> milliseconds. If the value is 0, the frame list
will only be updated once all the frames in the transfer have been received.
For example, consider a transfer with <code>numFrames</code> equal to 64. If
the update frequency is 4, the frame list data will be updated every 4 milliseconds.
If the update frequency is 0, the frame list will only be updated at the end
of the transfer, after the 64 frames have been sent or received. The difference
between using an update frequency of 0 and using the non-low latency isoch calls
is that in the former case, the frame list will be updated at primary interrupt
time, while in the latter, it will be updated at secondary interrupt time. Regardless
of the value of <code>updateFrequency</code>, the frame list will <em>always</em>
be updated on the last frame of a transfer.</p>
<p>The rationale for adding this call is that because completion routines run
on the USB Workloop, they can be scheduled to run a number of milliseconds after
the USB transfer has finished. This latency is variable and depends on what
other higher priority threads are running on the system. This latency presents
a problem for applications, such as audio processing, that depend on receiving
data, processing it, and sending it back out, and need to do this as fast as
possible. Since applications that use isochronous data know when the data should
be available, they can look at the frame list at the expected time and note
the <code>frActCount</code> and <code>frStatus</code> (and <code>frTimeStamp</code>
if needed) and determine how many valid bytes are in their data buffer and whether
there was an error. They can then access their data buffer and process the actual
data.</p>
<p>In order to update the frame list at primary interrupt time and to allow the
client to see that update, the frame list buffer needs to be shared between
the kernel and the user space. The same thing applies to the data buffer. This
is a difference between the low latency isoch calls and the regular isoch calls.
The <code>LowLatencyCreateBuffer()</code> call is used to pre-allocate the buffers.
The client <em>must</em> use that call to allocate the data and the frame list
buffers. The client can pass a portion of the buffer that was previoulsy allocated.
The USB stack will range check the data and frame list buffers to make sure
they are within the ranges of the buffers previously allocated. This allows
the client, if it so desires, to allocate a large data buffer and pass portions
of it to the read or write calls. The same applies to the frame list buffers.
Of course, the client can also pre-allocate several data buffers and several
frame list buffers and use those for each transfer. Once the transfer completes,
the buffers can be reused in subsequent calls. When all transfers are finished,
the client needs to call <code>LowLatencyDestroyBuffer()</code> for each buffer
that was created with <code>LowLatencyCreateBuffer().</code> </p>
<p>The interface must be open for the pipe to exist. The <font face="Courier New, Courier, mono"><code>buf</code></font>
pointer and the <font face="Courier New, Courier, mono"><code>frameList</code></font>
pointer need to be pre-allocated using <code>LowLatencyCreateBuffer()</code>.
After using them, they should be freed using <code>LowLatencyDestroyBuffer().</code></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 <code>IOUSBInterfaceInterface</code></td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-<code>GetNumEndpoints</code>).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data, previously allocated with <code>LowLatencyCreateBuffer()</code>
using a <code>kUSBLowLatencyReadBuffer</code> type.</td>
<tr>
<td align = "center"><tt>frameStart</tt></td>
<td>the bus frame number on which to start the read. obtained from <code>GetBusFrameNumber</code></td>
<tr>
<td align = "center"><tt>numFrames</tt></td>
<td>the number of frames for which to transfer data</td>
<tr>
<td align = "center">updateFrequency</td>
<td>specifies how often, in milliseconds, should the frame list data be
updated. Valid range is 0 - 8. If 0, it means that the framelist should
be updated at the end of the transfer.</td>
<tr>
<td align = "center"><tt>frameList</tt></td>
<td>A pointer to an array of <code>IOUSBLowLatencyIsocFrame</code> structures
describing the frames</td>
<tr>
<td align = "center"><tt>callback</tt></td>
<td>An <code>IOAsyncCallback1</code> method. A message addressed to this
callback is posted to the Async port upon completion.</td>
<tr>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<b>Result:</b> Returns <code>kIOReturnSuccess</code> if successful, <code>kIOReturnNoDevice</code>
if there is no connection to an <code>IOService</code>, or <code>kIOReturnNotOpen</code>
if the interface is not open for exclusive access. Will return <code>kIOUSBLowLatencyBufferNotPreviouslyAllocated</code>
or <code>kIOUSBLowLatencyFrameListNotPreviouslyAllocated</code> if the buffer
or the frameList were not previously allocated using <code>LowLatencyCreateBuffer().</code>
<hr>
<h3><b><a name="LowLatencyWriteIsochPipeAsync" id="LowLatencyWriteIsochPipeAsync"></a>LowLatencyWriteIsochPipeAsync</b></h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface192 and
above.</b></p>
<b></b><b></b><b>Abstract:</b> Does an asynchronous write on an ISOCHRONOUS pipe
and updates the frame list at primary interrupt time.
<blockquote>
<pre><tt> IOReturn (*<strong>LowLatencyWriteIsochPipeAsync</strong>)(void *self, UInt8 pipeRef, void *buf,
UInt64 frameStart, UInt32 numFrames, UInt32 updateFrequency,
IOUSBLowLatencyIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The <code>LowLatencyReadIsochPipeAsync()</code> and <code>LowLatencyWriteIsochPipeAsync()</code>
calls are analogous to <code>ReadIsochPipeAsync()</code> and <code>WriteIsochPipeAsync().</code>
They differ in that the frame list data is updated at <em>primary interrupt
time</em>. This means that the client can inspect the <code>frStatus</code>
and <code>frActCount</code> fields as soon as the transaction has been completed,
without having to wait for the callback to happen (depending on the value of
<code>updateFrequency</code>). The callback will still happen when the all the
frames have been received. </p>
<p>The client can specify how often the USB stack should update the frame list
data by specifying the <code>updateFrequency</code>: this value can range from
0 - 8. If the value is between 1 and 8, the frame list will be updated every
<code>updateFrequency</code> milliseconds. If the value is 0, the frame list
will only be updated once all the frames in the transfer have been received.
For example, consider a transfer with <code>numFrames</code> equal to 64. If
the update frequency is 4, the frame list data will be updated every 4 milliseconds.
If the update frequency is 0, the frame list will only be updated at the end
of the transfer, after the 64 frames have been sent or received. The difference
between using an update frequency of 0 and using the non-low latency isoch calls
is that in the former case, the frame list will be updated at primary interrupt
time, while in the latter, it will be updated at secondary interrupt time. Regardless
of the value of <code>updateFrequency</code>, the frame list will <em>always</em>
be updated on the last frame of a transfer.</p>
<p>The rationale for adding this call is that because completion routines run
on the USB Workloop, they can be scheduled to run a number of milliseconds after
the USB transfer has finished. This latency is variable and depends on what
other higher priority threads are running on the system. This latency presents
a problem for applications, such as audio processing, that depend on receiving
data, processing it, and sending it back out, and need to do this as fast as
possible. Since applications that use isochronous data know when the data should
be available, they can look at the frame list at the expected time and note
the <code>frActCount</code> and <code>frStatus</code> (and <code>frTimeStamp</code>
if needed) and determine how many valid bytes are in their data buffer and whether
there was an error. They can then access their data buffer and process the actual
data.</p>
<p>In order to update the frame list at primary interrupt time and to allow the
client to see that update, the frame list buffer needs to be shared between
the kernel and the user space. The same thing applies to the data buffer. This
is a difference between the low latency isoch calls and the regular isoch calls.
The <code>LowLatencyCreateBuffer()</code> call is used to pre-allocate the buffers.
The <em>client</em> must use that call to allocate the data and the frame list
buffers. The client can pass a portion of the buffer that was previoulsy allocated.
The USB stack will range check the data and frame list buffers to make sure
they are within the ranges of the buffers previously allocated. This allows
the client, if it so desires, to allocate a large data buffer and pass portions
of it to the read or write calls. The same applies to the frame list buffers.
Of course, the client can also pre-allocate several data buffers and several
frame list buffers and use those for each transfer. Once the transfer completes,
the buffers can be reused in subsequent calls. When all transfers are finished,
the client needs to call <code>LowLatencyDestroyBuffer()</code> for each buffer
that was created with <code>LowLatencyCreateBuffer().</code> </p>
<p>The interface must be open for the pipe to exist. The <font face="Courier New, Courier, mono"><code>buf</code></font>
pointer and the <font face="Courier New, Courier, mono"><code>frameList</code></font>
pointer need to be pre-allocated using <code>LowLatencyCreateBuffer()</code>.
After using them, they should be freed using <code>LowLatencyDestroyBuffer().</code></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 <code>IOUSBInterfaceInterface</code></td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-<code>GetNumEndpoints</code>).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data, previously allocated with <code>LowLatencyCreateBuffer()</code>
using a <code>kUSBLowLatencyWriteBuffer</code> type.</td>
<tr>
<td align = "center"><tt>frameStart</tt></td>
<td>The bus frame number on which to start the write. obtained from <code>GetBusFrameNumber</code></td>
<tr>
<td align = "center"><tt>numFrames</tt></td>
<td>The number of frames for which to transfer data</td>
<tr>
<td align = "center">updateFrequency</td>
<td>Specifies how often, in milliseconds, should the frame list data be
updated. Valid range is 0 - 8. If 0, it means that the framelist should
be updated at the end of the transfer.</td>
<tr>
<td align = "center"><tt>frameList</tt></td>
<td>A pointer to an array of <code>IOUSBLowLatencyIsocFrame</code> structures
describing the frames</td>
<tr>
<td align = "center"><tt>callback</tt></td>
<td>An <code>IOAsyncCallback1</code> method. A message addressed to this
callback is posted to the Async port upon completion.</td>
<tr>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<b>Result:</b> Returns <code>kIOReturnSuccess</code> if successful, <code>kIOReturnNoDevice</code>
if there is no connection to an <code>IOService</code>, or <code>kIOReturnNotOpen</code>
if the interface is not open for exclusive access. Will return <code>kIOUSBLowLatencyBufferNotPreviouslyAllocated</code>
or <code>kIOUSBLowLatencyFrameListNotPreviouslyAllocated</code> if the buffer
or the frameList were not previously allocated using <code>LowLatencyCreateBuffer().</code>
<hr>
<h3><a name="ReadIsochPipeAsync"></a>ReadIsochPipeAsync</h3>
<b>Abstract:</b> Does a read on an <b>ISOCHRONOUS</b> pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ReadIsochPipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>frameStart</tt></td>
<td>the bus frame number on which to start the read. obtained from GetBusFrameNumber</td>
<tr>
<td align = "center"><tt>numFrames</tt></td>
<td>the number of frames for which to transfer data</td>
<tr>
<td align = "center"><tt>frameList</tt></td>
<td>A pointer to an array of IOUSBIsocFrame structures describing the frames</td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ReadPipe"></a>ReadPipe</h3>
<b>Abstract:</b> Reads data on a <b>BULK IN</b> or an <b>INTERRUPT</b> pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ReadPipe)(void *self, UInt8 pipeRef, void *buf, UInt32 *size);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>on entry: a pointer to the size of the buffer pointed to by buf<br>
on exit: a pointer to the number of bytes actually read from the device</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ReadPipeAsync"></a>ReadPipeAsync</h3>
<b>Abstract:</b> Does an asynchronous read on a <b>BULK IN</b> or an <b>INTERRUPT</b> pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ReadPipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt32 size, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>the size of the buffer pointed to by buf</td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="ReadPipeAsyncTO"></a>ReadPipeAsyncTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b></b><b>Abstract:</b> Does an asynchronous read on a <b>BULK IN </b>pipe, with specified timeout values.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ReadPipeAsyncTO)(void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </p>
<p>If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See <a href="#ClearPipeStall">ClearPipeStall</a> or <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.</p>
<p>Timeouts do not apply to interrupt pipes, so you should use the <a href="#ReadPipeAsync">ReadPipeAsync</a> API to perform an asynchronous read from an interrupt pipe.</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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>the size of the buffer pointed to by buf</td>
<tr>
<td align = "center"><tt>noDataTimeout</tt></td>
<td>Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.</td>
<tr>
<td align = "center"><tt>completionTimeout</tt></td>
<td>Specified a time value in milliseconds. Once the request is queued on
the bus, if the entire request is not completed in this amount of time,
the request will be aborted and returned. </td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<b>Result:</b> Returns <font face="Courier New,Courier,mono">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 interface is not open for exclusive access. Returns <font face="Courier New,Courier,Monaco">kIOReturnBadArgument</font> if timeout values are specified for an interrupt pipe.
<hr>
<h3><a name="ReadPipeTO"></a>ReadPipeTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b>Abstract:</b> Does a read on a <b>BULK IN</b> pipe, specifying timeout values
<blockquote>
<pre><tt> <b>IOReturn</b>(*ReadPipeTO)(void *self, UInt8 pipeRef, void *buf, UInt32 *size, UInt32 noDataTimeout, UInt32 completionTimeout);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </p>
<p>If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See <a href="#ClearPipeStall">ClearPipeStall</a> or <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.</p>
<p>Timeouts do not apply to interrupt pipes, so you should use the <a href="#ReadPipe">ReadPipe</a> API to perform a read from an interrupt pipe.</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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>Pointer to the size of the buffer pointed to by buf</td>
<tr>
<td align = "center"><tt>noDataTimeout</tt></td>
<td>Specifies a time value in milliseconds. Once the request is queued on
the bus, if no data is transferred in this amount of time, the request
will be aborted and returned. </td>
<tr>
<td align = "center"><tt>completionTimeout</tt></td>
<td>Specified a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access. Returns <font face="Courier New,Courier,Monaco">kIOReturnBadArgument</font> if timeout values are specified for an interrupt pipe. If a transaction error or a timeout is returned, the number of bytes read will <B>not</B> be updated.
<hr>
<h3><a name="ResetPipe"></a>ResetPipe</h3>
<b>Abstract:</b> Equivalent to <a href="#ClearPipeStall">ClearPipeStall</a>.
<blockquote>
<pre><tt> <b>IOReturn</b>(*ResetPipe)(void *self, UInt8 pipeRef);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="SetAlternateInterface"></a>SetAlternateInterface</h3>
<b>Abstract:</b> Change the AltInterface setting.
<blockquote>
<pre><tt> <b>IOReturn</b>(*SetAlternateInterface)(void *self, UInt8 alternateSetting);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>alternateSetting</tt></td>
<td>The new alternate setting for the interface.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="SetPipePolicy"></a>SetPipePolicy</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface190 and above.</b></p>
<p><b>Abstract:</b> Change the size of the reserved bandwidth for an isochronous pipe. The pipe may be made smaller or larger (up to the maxPacketSize specified in the endpoint descriptor). When an interface is first opened, all pipes are created with their descriptor-supplied maxPacketSize. For isochronous pipes, if there is not enough bandwidth on the bus to allocate to the pipe, the pipe is created with a reserved bandwidth of zero. Any attempts to transfer data on a pipe with zero bandwidth will result in a <font face="Courier New,Courier,Monaco">kIOReturnNoBandwidth</font> error. The pipe must first be given some bandwidth using this call.</p>
<blockquote>
<pre><tt> <b>IOReturn</b>(*SetPipePolicy)(void *self, UInt8 pipeRef, UInt16 maxPacketSize, UInt8 maxInterval);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints)</td>
<tr>
<td align = "center"><tt>maxPacketSize</tt></td>
<td>The desired size for the Isochronous pipe. Valid values are 0 through
the maxPacketSize defined in the endpoint descriptor.</td>
<tr>
<td align = "center"><tt>maxInterval</tt></td>
<td>Currently ignored.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access. May also return <font face="Courier New,Courier,Monaco">kIOReturnNoBandwidth</font> if there is not enough bandwidth available on the bus, or <font face="Courier New,Courier,Monaco">kIOReturnBadArgument</font> if the desired maxPacketSize is outside of the allowed range.
<hr>
<h3><a name="USBInterfaceClose"></a>USBInterfaceClose</h3>
<b>Abstract:</b> Close the task's connection to the IOUSBInterface.
<blockquote>
<pre><tt> <b>IOReturn</b>(*USBInterfaceClose)(void *self);</tt></pre>
</blockquote>
<p>Release the clients exclusive access to the IOUSBInterface.
</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 IOUSBInterfaceInterface</td>
</table>
</blockquote>
<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="USBInterfaceGetStringIndex"></a>USBInterfaceGetStringIndex</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b></b><b>Abstract:</b> Return the string index in the interface descriptor.
<blockquote>
<pre><tt> <b>IOReturn</b>(*USBInterfaceGetStringIndex)(void *self, UInt8 *si);</tt></pre>
</blockquote>
<p>The interface 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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>si</tt></td>
<td>Pointer to UInt8 to hold the string index</td>
</table>
</blockquote>
<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="USBInterfaceOpen"></a>USBInterfaceOpen</h3>
<b>Abstract:</b> Open up the IOUSBInterface for exclusive access.
<blockquote>
<pre><tt> <b>IOReturn</b>(*USBInterfaceOpen)(void *self);</tt></pre>
</blockquote>
<p>Before the client can transfer data to and from the interface, it must have
succeeded in opening the interface. This establishes an exclusive link between
the clients task and the actual interface device. Opening the interface causes
pipes to be created on each endpoint contained in the interface. If the interface
contains isochronous endpoints, an attempt is made to allocate bandwidth on
the bus for each of those pipes. If there is not enough bandwidth available,
an isochronous pipe may be created with a bandwidth of zero. The software must
then call SetPipePolicy to change the size of that pipe before it can be used
for I/O.</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 IOUSBInterfaceInterface</td>
</table>
</blockquote>
<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="USBInterfaceOpenSeize"></a>USBInterfaceOpenSeize</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface183 and
above.</b></p>
<b></b><b>Abstract:</b> Open up the IOUSBInterface for exclusive access. If another
client has the device opened, an attempt is made to get that client to close it
before returning.
<blockquote>
<pre><tt> <b>IOReturn</b>(*USBInterfaceOpenSeize)(void *self);</tt></pre>
</blockquote>
<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 IOUSBInterfaceInterface</td>
</table>
</blockquote>
<b>Result:</b> Returns <font face="Courier New,Courier,Monaco">kIOReturnExclusiveAccess</font> if some other task has the interface 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>
<h3><a name="WriteIsochPipeAsync"></a>WriteIsochPipeAsync</h3>
<b>Abstract:</b> Does an asynchronous write on an <b>ISOCHRONOUS</b> pipe
<blockquote>
<pre><tt> <b>IOReturn</b>(*WriteIsochPipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>frameStart</tt></td>
<td>the bus frame number on which to start the read. obtained from GetBusFrameNumber</td>
<tr>
<td align = "center"><tt>numFrames</tt></td>
<td>the number of frames for which to transfer data</td>
<tr>
<td align = "center"><tt>frameList</tt></td>
<td>A pointer to an array of IOUSBIsocFrame structures describing the frames</td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="WritePipe"></a>WritePipe</h3>
<b>Abstract:</b> Writes data on a <b>BULK OUT</b> or <b>INTERRUPT OUT</b> pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*WritePipe)(void *self, UInt8 pipeRef, void *buf, UInt32 size);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>the size of the data buffer</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="WritePipeAsync"></a>WritePipeAsync</h3>
<b>Abstract:</b> Does an asynchronous write on a <b>BULK OUT</b> or <b>INTERRUPT OUT</b> pipe.
<blockquote>
<pre><tt> <b>IOReturn</b>(*WritePipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt32 size, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist. </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 IOUSBInterfaceInterface</td>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<td align = "center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
<tr>
<td align = "center"><tt>size</tt></td>
<td>the size of the buffer pointed to by buf</td>
<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>
<td align = "center"><tt>refCon</tt></td>
<td>Arbitrary pointer which is passed as a parameter to the callback routine.</td>
</table>
</blockquote>
<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 interface is not open for exclusive access.
<hr>
<h3><a name="WritePipeAsyncTO"></a>WritePipeAsyncTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and above.</b></p>
<b>Abstract:</b> Does an asynchronous write on a <b>BULK OUT</b> pipe, with specified timeout values.
<blockquote>
<pre><tt> <b>IOReturn</b>(*WritePipeAsyncTO)(void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist.</p>
<p>If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See <a href="#ClearPipeStall">ClearPipeStall</a> or <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.</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 IOUSBInterfaceInterface</td>
</tr>
<tr>
<td align="center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</tr>
<tr>
<td align="center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
</tr>
<tr>
<td align="center"><tt>size</tt></td>
<td>the size of the buffer pointed to by buf</td>
</tr>
<tr>
<td align="center"><tt>noDataTimeout</tt></td>
<td>Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.</td>
</tr>
<tr>
<td align="center"><tt>completionTimeout</tt></td>
<td>Specified a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.</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>
<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 interface is not open for exclusive access.</p>
<hr>
<h3><a name="WritePipeTO"></a>WritePipeTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and above.</b></p>
<b>Abstract:</b> Does an asynchronous write on a BULK OUT pipe, with specified timeout values.
<blockquote>
<pre><tt> <b>IOReturn</b>(*WritePipeTO)(void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout);</tt></pre>
</blockquote>
<p>The interface must be open for the pipe to exist.</p>
<p>If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See <a href="#ClearPipeStall">ClearPipeStall</a> or <a href="#ClearPipeStallBothEnds">ClearPipeStallBothEnds</a>.</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 IOUSBInterfaceInterface</td>
</tr>
<tr>
<td align="center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
</tr>
<tr>
<td align="center"><tt>buf</tt></td>
<td>Buffer to hold the data</td>
</tr>
<tr>
<td align="center"><tt>size</tt></td>
<td>the size of the buffer pointed to by buf</td>
</tr>
<tr>
<td align="center"><tt>noDataTimeout</tt></td>
<td>Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.</td>
</tr>
<tr>
<td align="center"><tt>completionTimeout</tt></td>
<td>Specified a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.</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, or <font face="Courier New,Courier,Monaco">kIOReturnNotOpen</font> if the interface is not open for exclusive access.</p>
<hr>
<b></b><b></b><b></b><b></b>
<p>© 2001-2003 Apple Computer, Inc. — (Last Updated 2003/05/07)</p>
</body></html>