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, as well as versions of the structure which
became available in later versions of Mac OS X. Functions which were <i><b>not</b></i>
available in the original API will be documented as such.</p>
<hr>
<h3><a name="AbortPipe">AbortPipe</a></h3>
<b>Abstract:</b> Aborts any outstanding transactions on the pipe with status kIOReturnAborted.
If there are outstanding asyncronous 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 ClearPipeStall or ClearPipeStallBothEnds.
<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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<tr>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="ClearPipeStall">ClearPipeStall</a></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 asyncronous
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 ClearPipeStallBothEnds.
<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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<tr>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="ClearPipeStallBothEnds">ClearPipeStall</a>BothEnds</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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<tr>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="ControlRequest">ControlRequest</a></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>
<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>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
<hr>
<h3><a name="ControlRequestAsync">ControlRequestAsync</a></h3>
<b>Abstract:</b> Sends an asyncronous 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>
<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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, kIOReturnNotOpen if the interface is not open
for exclusive access, or kIOUSBNoAsyncPortErr if no Async port has been created
for this interface.
<hr>
<h3><a name="ControlRequestAsyncTO">ControlRequestAsyncTO</a></h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b>Abstract:</b> Sends an asyncronous 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>
<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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, kIOReturnNotOpen if the interface is not open
for exclusive access, or kIOUSBNoAsyncPortErr if no Async port has been created
for this interface.
<hr>
<h3><a name="ControlRequestTO">ControlRequest</a>TO</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>
<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>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="CreateInterfaceAsyncEventSource">CreateInterfaceAsyncEventSource</a></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 deliveres 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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful or a kern_return_t if failed.
<hr>
<h3><a name="CreateInterfaceAsyncPort">CreateInterfaceAsyncPort</a></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 deliveres 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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful or a kern_return_t if failed.
<hr>
<h3><a name="GetAlternateSetting">GetAlternateSetting</a></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>
<tr>
<td align = "center"><tt>intfAltSetting</tt></td>
<td>Pointer to UInt8 to hold the alternate setting value.</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService.
<hr>
<h3><a name="GetBandwidthAvailable">GetBandwidthAvailable</a></h3>
<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 SetPipePolicy.
<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>
<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>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService.
<hr>
<h3><a name="GetBusFrameNumber">GetBusFrameNumber</a></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>
<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>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>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetConfigurationValue">GetConfigurationValue</a></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>
<tr><td align = "center"><tt>configVal</tt></td><td>Pointer to UInt8 to hold the configuration value.</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetDevice">GetDevice</a></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>
<tr><td align = "center"><tt>device</tt></td><td>Pointer to io_service_t to hold the result.</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetDeviceProduct">GetDeviceProduct</a></h3>
<b>Abstract:</b> Return the ProductID 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>
<tr><td align = "center"><tt>devProduct</tt></td><td>Pointer to UInt16 to hold the ProductID</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetDeviceReleaseNumber">GetDeviceReleaseNumber</a></h3>
<b>Abstract:</b> Return the Release Number 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>
<tr><td align = "center"><tt>devRelNum</tt></td><td>Pointer to UInt16 to hold the Release Number</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetDeviceVendor">GetDeviceVendor</a></h3>
<b>Abstract:</b> Return the VendorID 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>
<tr>
<td align = "center"><tt>devVendor</tt></td>
<td>Pointer to UInt16 to hold the vendorID</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService.
<hr>
<h3><a name="GetEndpointProperties">GetEndpointProperties</a></h3>
<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.
<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>
<tr>
<td align = "center"><tt>alternateSetting</tt></td>
<td>Specifies the alternate setting within the current interface.</td>
<tr>
<tr>
<td align = "center"><tt>enpointNumber</tt></td>
<td>Specifies the desired endpoint number.</td>
<tr>
<tr>
<td align = "center"><tt>direction</tt></td>
<td>Specifies the desired direction.</td>
<tr>
<tr>
<td align = "center"><tt>transferType</tt></td>
<td>Pointer to UInt8 to hold the endpoint's transfer type (kUSBControl,
kUSBIsoc, etc)</td>
<tr>
<tr>
<td align = "center"><tt>maxPacketSize</tt></td>
<td>Pointer to UInt16 to hold the maxPacketSize of the endpoint</td>
<tr>
<tr>
<td align = "center"><tt>interval</tt></td>
<td>Pointer to UInt8 to hold the polling interval for interrupt endpoints</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService.
<hr>
<h3><a name="GetInterfaceAsyncEventSource">GetInterfaceAsyncEventSource</a></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><tr>
</table>
</blockquote>
<b>Result:</b> Returns the run loop source if one has been created, 0 otherwise.
<hr>
<h3><a name="GetInterfaceAsyncPort">GetInterfaceAsyncPort</a></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><tr>
</table>
</blockquote>
<b>Result:</b> Returns the port if one exists, 0 otherwise.
<hr>
<h3><a name="GetInterfaceClass">GetInterfaceClass</a></h3>
<b>Abstract:</b> Return the USB Class of the interface.
<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>
<tr><td align = "center"><tt>intfClass</tt></td><td>Pointer to UInt8 to hold the interface Class</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetInterfaceNumber">GetInterfaceNumber</a></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>
<tr>
<td align = "center"><tt>intfNumber</tt></td>
<td>Pointer to UInt8 to hold the interface number</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetInterfaceProtocol">GetInterfaceProtocol</a></h3>
<b>Abstract:</b> Return the USB Protocol of the interface.
<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 kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetInterfaceSubClass">GetInterfaceSubClass</a></h3>
<b>Abstract:</b> Return the USB Subclass of the interface.
<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>
<tr><td align = "center"><tt>intfSubClass</tt></td><td>Pointer to UInt8 to hold the interface Subclass</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetLocationID">GetLocationID</a></h3>
<b>Abstract:</b> Return the location ID. This is a 32 bit number which is unique
among all USB devices in the system, andwhich 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>
<tr><td align = "center"><tt>locationID</tt></td><td>Pointer to UInt32 to hold the location ID.</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetNumEndpoints">GetNumEndpoints</a></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>
<tr><td align = "center"><tt>intfNumEndpoints</tt></td><td>Pointer to UInt8 to hold the number of endpoints.</td><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
<hr>
<h3><a name="GetPipeProperties">GetPipeProperties</a></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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<tr>
<td align = "center"><tt>direction</tt></td>
<td>Pointer to an UInt8 to get the direction of the pipe.</td>
<tr>
<tr>
<td align = "center"><tt>number</tt></td>
<td>Pointer to an UInt8 to get the pipe number.</td>
<tr>
<tr>
<td align = "center"><tt>transferType</tt></td>
<td>Pointer to an UInt8 to get the transfer type of the pipe.</td>
<tr>
<tr>
<td align = "center"><tt>maxPacketSize</tt></td>
<td>Pointer to an UInt16 to get the maxPacketSize of the pipe.</td>
<tr>
<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>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="GetPipeStatus">GetPipeStatus</a></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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<tr>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnNoDevice if there is no connection to an IOService,
or kIOReturnNotOpen if the interface is not open for exclusive access. Otherwise,
the status of the pipe is returned. Returns kIOUSBPipeStalled if the pipe is stalled.
See ClearPipeStall or ClearPipsStallBothEnds.
<hr>
<h3><a name="ReadIsochPipeAsync">ReadIsochPipe</a>Async</h3>
<b>Abstract:</b> Does a read on an ISOCHRONOUS 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>
<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 strcutures descibing 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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="ReadPipe">ReadPipe</a></h3>
<b>Abstract:</b> Reads data on a BULK IN or an INTERRUPT 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>
<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>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="ReadPipeAsync">ReadPipe</a>Async</h3>
<b>Abstract:</b> Does an asyncronous read on a BULK IN or an INTERRUPT 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>
<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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="ReadPipeAsyncTO">ReadPipe</a>AsyncTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b></b><b>Abstract:</b> Does an asyncronous read on a BULK IN or an INTERRUPT
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 ClearPipeStall or ClearPipeStallBothEnds.</p>
<h4></h4>
<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>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. <b>This parameter must be set to 0 for
interrupt pipes.</b></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. <b>This parameter must be set to 0 for
interrupt pipes.</b></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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access. Returns kIOReturnBadArgument is timeout values are specified
for an interrupt pipe.
<hr>
<h3><a name="ReadPipeTO">ReadPipeTO</a></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 BULK IN or an INTERRUPT 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 ClearPipeStall or ClearPipeStallBothEnds.</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>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. <b>This parameter must be set to 0 for interrupt
pipes.</b></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. <b>This parameter must be set to 0 for
interrupt pipes.</b></td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access. Returns kIOReturnBadArgument is timeout values are specified
for an interrupt pipe.
<hr>
<h3><a name="ResetPipe">ResetPipe</a></h3>
<b>Abstract:</b> Equivalent to ClearPipeStall.
<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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints).</td>
<tr>
<tr>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="SetAlternateInterface">SetAlternateInterface</a></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>
<tr>
<td align = "center"><tt>alternateSetting</tt></td>
<td>The new alternate setting for the interface.</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="SetPipePolicy">SetPipePolicy</a></h3>
<b>Abstract:</b> Change the size od the reserved bandwidth for an isochronous
pipe. The pipe may be made smaller or larger, 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 maxPacketSize of zero. Any attempts to transfer data on a pipe with zero
bandwidth will result in a kIOReturnNoBandwidth error. The pipe must first be
given some bandwidth using this call.
<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>
<tr>
<td align = "center"><tt>pipeRef</tt></td>
<td>Index for the desired pipe (1-GetNumEndpoints)</td>
<tr>
<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>
<tr>
<td align = "center"><tt>maxInterval</tt></td>
<td>Currently ignored.</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access. May also return kIOReturnNoBandwidth if there is not
enough bandwidth available on the bus, or kIOReturnBadArgument if the desired
maxPacketSize is outside of the allowed range.
<hr>
<h3></h3>
<h3><a name="USBInterfaceClose">USBInterfaceClose</a></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><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, some other mach error if the connection is no longer valid.
<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>
<tr>
<td align = "center"><tt>si</tt></td>
<td>Pointer to UInt8 to hold the string index</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService.
<hr>
<h3><a name="USBInterfaceOpen">USBInterfaceOpen</a></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 muct
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><tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnExclusiveAccess if some other task has the device opened already, kIOReturnError if the connection with the kernel can not be established or kIOReturnSuccess if successful.
<hr>
<h3><a name="USBInterfaceOpenSeize">USBInterfaceOpen</a>Seize</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 IOUSBInterfaceceInterface</td>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnExclusiveAccess if some other task has the interface
opened already and refuses to close it, kIOReturnError if the connection with
the kernel can not be established or kIOReturnSuccess if successful.
<hr>
<h3><a name="WriteIsochPipeAsync">WriteIsochPipe</a>Async</h3>
<b>Abstract:</b> Does an asyncronous write on an ISOCHRONOUS 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>
<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 strcutures descibing 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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="WritePipe">WritePipe</a></h3>
<b>Abstract:</b> Writes data on a BULK OUT 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>
<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>
<tr>
<tr>
<tr>
<tr>
</table>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="WritePipeAsync">WritePipe</a>Async</h3>
<b>Abstract:</b> Does an asyncronous write on a BULK OUT 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>
<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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="WritePipeAsyncTO">WritePipe</a>AsyncTO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b></b><b>Abstract:</b> Does an asyncronous write on a BULK OUT 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 ClearPipeStall or ClearPipeStallBothEnds.</p>
<h4></h4>
<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>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>
<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>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<h3><a name="WritePipeTO">WritePipe</a>TO</h3>
<p><b>Note: This function is only available with IOUSBInterfaceInterface182 and
above.</b></p>
<b></b><b>Abstract:</b> Does a write on a BULK OUT pipe, specifying 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 ClearPipeStall or ClearPipeStallBothEnds.</p>
<h4></h4>
<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>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>
<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>
</blockquote>
<b>Result:</b> Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there
is no connection to an IOService, or kIOReturnNotOpen if the interface is not
open for exclusive access.
<hr>
<p>© 2001-2002 Apple Computer, Inc. — (Last Updated 5/31/2002)</p>
</body></html>