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 not available in the original API will be documented as such.
IOReturn(*AbortPipe)(void *self, UInt8 pipeRef);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints).
IOReturn(*ClearPipeStall)(void *self, UInt8 pipeRef);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints).
Note: This function is only available with IOUSBInterfaceInterface190 and above.
Abstract: 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.IOReturn(*ClearPipeStallBothEnds)(void *self, UInt8 pipeRef);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints).
IOReturn(*ControlRequest)(void *self, UInt8 pipeRef, IOUSBDevRequest *req);
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.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index of the control pipe to use. Use zero for the default control pipe on the device. req Pointer to an IOUSBDevRequest containing the request.
IOReturn(*ControlRequestAsync)(void *self, UInt8 pipeRef, IOUSBDevRequest *req, IOAsyncCallback1 callback, void *refCon);
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.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index of the control pipe to use. Use zero for the default control pipe on the device. req Pointer to an IOUSBDevRequest containing the request. callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: 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.IOReturn(*ControlRequestAsyncTO)(void *self, UInt8 pipeRef, IOUSBDevRequestTO *req, IOAsyncCallback1 callback, void *refCon);
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.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index of the control pipe to use. Use zero for the default control pipe on the device. req Pointer to an IOUSBDevRequestTO containing the request. callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: Sends a USB request on a control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request.IOReturn(*ControlRequestTO)(void *self, UInt8 pipeRef, IOUSBDevRequestTO *req);
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.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index of the control pipe to use. Use zero for the default control pipe on the device. req Pointer to an IOUSBDevRequestTO containing the request.
IOReturn(*CreateInterfaceAsyncEventSource)(void *self, CFRunLoopSourceRef *source);
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.
Result: Returns kIOReturnSuccess if successful or a kern_return_t if failed.
Name Description self Pointer to the IOUSBInterfaceInterface source Pointer to a CFRunLoopSourceRef to return the newly created run loop event source.
IOReturn(*CreateInterfaceAsyncPort)(void *self, mach_port_t *port);
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.
Result: Returns kIOReturnSuccess if successful or a kern_return_t if failed.
Name Description self Pointer to the IOUSBInterfaceInterface port Pointer to a mach_port_t to return the newly created port.
IOReturn(*GetAlternateSetting)(void *self, UInt8 *intfAltSetting);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface intfAltSetting Pointer to UInt8 to hold the alternate setting value.
IOReturn(*GetBandwidthAvailable)(void *self, UInt32 *bandwidth);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface bandwidth Pointer to UInt32 to hold the amount of bandwidth available (in bytes per 1ms frame).
IOReturn(*GetBusFrameNumber)(void *self, UInt64 *frame, AbsoluteTime *atTime);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface frame Pointer to UInt64 to hold the frame number. atTime Pointer to an AbsoluteTime, which should be within 1ms of the time when the bus frame number was attained.
IOReturn(*GetConfigurationValue)(void *self, UInt8 *configVal);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface configVal Pointer to UInt8 to hold the configuration value.
IOReturn(*GetDevice)(void *self, io_service_t *device);
The interface does not have to be open. The returned device can be used to create a CFPlugin to talk to the device.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface device Pointer to io_service_t to hold the result.
IOReturn(*GetDeviceProduct)(void *self, UInt16 *devProduct);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface devProduct Pointer to UInt16 to hold the ProductID
IOReturn(*GetDeviceReleaseNumber)(void *self, UInt16 *devRelNum);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface devRelNum Pointer to UInt16 to hold the Release Number
IOReturn(*GetDeviceVendor)(void *self, UInt16 *devVendor);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface devVendor Pointer to UInt16 to hold the vendorID
IOReturn(*GetEndpointProperties)(void *self, UInt8 alternateSetting, UInt8 endpointNumber, UInt8 direction, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface alternateSetting Specifies the alternate setting within the current interface. enpointNumber Specifies the desired endpoint number. direction Specifies the desired direction. transferType Pointer to UInt8 to hold the endpoint's transfer type (kUSBControl, kUSBIsoc, etc) maxPacketSize Pointer to UInt16 to hold the maxPacketSize of the endpoint interval Pointer to UInt8 to hold the polling interval for interrupt endpoints
CFRunLoopSourceRef(*GetInterfaceAsyncEventSource)(void *self);
Result: Returns the run loop source if one has been created, 0 otherwise.
Name Description self Pointer to the IOUSBInterfaceInterface
mach_port_t(*GetInterfaceAsyncPort)(void *self);
Result: Returns the port if one exists, 0 otherwise.
Name Description self Pointer to the IOUSBInterfaceInterface
IOReturn(*GetInterfaceClass)(void *self, UInt8 *intfClass);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface intfClass Pointer to UInt8 to hold the interface Class
IOReturn(*GetInterfaceNumber)(void *self, UInt8 *intfNumber);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface intfNumber Pointer to UInt8 to hold the interface number
IOReturn(*GetInterfaceProtocol)(void *self, UInt8 *intfProtocol);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface intfProtocol Pointer to UInt8 to hold the interface Protocol
IOReturn(*GetInterfaceSubClass)(void *self, UInt8 *intfSubClass);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface intfSubClass Pointer to UInt8 to hold the interface Subclass
IOReturn(*GetLocationID)(void *self, UInt32 *locationID);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface locationID Pointer to UInt32 to hold the location ID.
IOReturn(*GetNumEndpoints)(void *self, UInt8 *intfNumEndpoints);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface intfNumEndpoints Pointer to UInt8 to hold the number of endpoints.
IOReturn(*GetPipeProperties)(void *self, UInt8 pipeRef, UInt8 *direction, UInt8 *number, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval);
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.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). direction Pointer to an UInt8 to get the direction of the pipe. number Pointer to an UInt8 to get the pipe number. transferType Pointer to an UInt8 to get the transfer type of the pipe. maxPacketSize Pointer to an UInt16 to get the maxPacketSize of the pipe. interval Pointer to an UInt8 to get the interval for polling the pipe for data (in milliseconds).
IOReturn(*GetPipeStatus)(void *self, UInt8 pipeRef);
The interface must be open for the pipe to exist.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints).
Note: This function is only available with IOUSBInterfaceInterface192 and above.
Abstract: This function will allocate a buffer of typebufferType.
This buffer can then be used with the LowLatencyIsochReadPipeAsync()
or LowLatencyIsochWritePipeAsync() calls.
IOReturn (*LowLatencyCreateBuffer) (void * self, void **buffer, IOByteCount size,
UInt32 bufferType);
The LowLatencyIsochReadPipeAsync() or LowLatencyIsochWritePipeAsync()
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 LowLatencyDestroyBuffer()
call.
If the buffer is to be used for reading data, the type passed in should be
kUSBLowLatencyReadBuffer. If the buffer is to be used for writing
data, the type should be kUSBLowLatencyWriteBuffer. For frame list
data, the type should be kUSBLowLatencyFrameListBuffer.
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 LowLatencyReadIsochPipeAsync()
or LowLatencyWriteIsochPipeAsync().
The interface must be open for the pipe to exist.
Result: Returns
Name Description self Pointer to the IOUSBInterfaceInterface buffer Pointer to a pointer that will receive the pointer to the buffer created by this call. size The size of the buffer to be created in bytes. bufferType Type of buffer: one of kUSBLowLatencyWriteBuffer,kUSBLowLatencyReadBuffer, orkUSBLowLatencyFrameListBuffer. See USB.h.
kIOReturnSuccess if successful, kIOReturnNoDevice
if there is no connection to an IOService, or kIOReturnNotOpen
if the interface is not open for exclusive access. If the buffer can't be allocated,
it will return kIOReturnNoMemory.
Note: This function is only available with IOUSBInterfaceInterface192 and above.
Abstract: Releases a buffer that was previously allocated using LowLatencyCreateBuffer().IOReturn (*LowLatencyDestroyBuffer) (void * self, void * buffer );
The interface must be open for the pipe to exist.
Result: Returns
Name Description self Pointer to the IOUSBInterfaceInterface buffer Pointer to the buffer previously allocated using LowLatencyCreateBuffer().
kIOReturnSuccess if successful, kIOReturnNoDevice
if there is no connection to an IOService, or kIOReturnNotOpen
if the interface is not open for exclusive access. If the buffer was not previously
allocated using LowLatencyCreateBuffer() it will return kIOReturnBadArgument.
Note: This function is only available with IOUSBInterfaceInterface192 and above.
Abstract: Does an asynchronous read on a ISOCHRONOUS pipe and updates the frame list at primary interrupt time.
IOReturn (*LowLatencyReadIsochPipeAsync)(void *self, UInt8 pipeRef, void *buf,
UInt64 frameStart, UInt32 numFrames, UInt32 updateFrequency,
IOUSBLowLatencyIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon)
The LowLatencyReadIsochPipeAsync() and LowLatencyWriteIsochPipeAsync()
calls are analogous to ReadIsochPipeAsync() and WriteIsochPipeAsync().
They differ in that the frame list data is updated at primary interrupt
time. This means that the client can inspect the frStatus
and frActCount fields as soon as the transaction has been completed,
without having to wait for the callback to happen (depending on the value of
updateFrequency). The callback will still happen when the all the
frames have been received.
The client can specify how often the USB stack should update the frame list
data by specifying the updateFrequency: this value can range from
0 - 8. If the value is between 1 and 8, the frame list will be updated every
updateFrequency 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 numFrames 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 updateFrequency, the frame list will always
be updated on the last frame of a transfer.
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 frActCount and frStatus (and frTimeStamp
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.
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 LowLatencyCreateBuffer() call is used to pre-allocate the buffers.
The client 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 LowLatencyDestroyBuffer() for each buffer
that was created with LowLatencyCreateBuffer().
The interface must be open for the pipe to exist. The buf
pointer and the frameList
pointer need to be pre-allocated using LowLatencyCreateBuffer().
After using them, they should be freed using LowLatencyDestroyBuffer().
Result: Returns
Name Description self Pointer to the IOUSBInterfaceInterfacepipeRef Index for the desired pipe (1- GetNumEndpoints).buf Buffer to hold the data, previously allocated with LowLatencyCreateBuffer()using akUSBLowLatencyReadBuffertype.frameStart the bus frame number on which to start the read. obtained from GetBusFrameNumbernumFrames the number of frames for which to transfer data updateFrequency 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. frameList A pointer to an array of IOUSBLowLatencyIsocFramestructures describing the framescallback An IOAsyncCallback1method. A message addressed to this callback is posted to the Async port upon completion.refCon Arbitrary pointer which is passed as a parameter to the callback routine.
kIOReturnSuccess if successful, kIOReturnNoDevice
if there is no connection to an IOService, or kIOReturnNotOpen
if the interface is not open for exclusive access. Will return kIOUSBLowLatencyBufferNotPreviouslyAllocated
or kIOUSBLowLatencyFrameListNotPreviouslyAllocated if the buffer
or the frameList were not previously allocated using LowLatencyCreateBuffer().
Note: This function is only available with IOUSBInterfaceInterface192 and above.
Abstract: Does an asynchronous write on an ISOCHRONOUS pipe and updates the frame list at primary interrupt time.
IOReturn (*LowLatencyWriteIsochPipeAsync)(void *self, UInt8 pipeRef, void *buf,
UInt64 frameStart, UInt32 numFrames, UInt32 updateFrequency,
IOUSBLowLatencyIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);
The LowLatencyReadIsochPipeAsync() and LowLatencyWriteIsochPipeAsync()
calls are analogous to ReadIsochPipeAsync() and WriteIsochPipeAsync().
They differ in that the frame list data is updated at primary interrupt
time. This means that the client can inspect the frStatus
and frActCount fields as soon as the transaction has been completed,
without having to wait for the callback to happen (depending on the value of
updateFrequency). The callback will still happen when the all the
frames have been received.
The client can specify how often the USB stack should update the frame list
data by specifying the updateFrequency: this value can range from
0 - 8. If the value is between 1 and 8, the frame list will be updated every
updateFrequency 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 numFrames 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 updateFrequency, the frame list will always
be updated on the last frame of a transfer.
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 frActCount and frStatus (and frTimeStamp
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.
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 LowLatencyCreateBuffer() call is used to pre-allocate the buffers.
The client 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 LowLatencyDestroyBuffer() for each buffer
that was created with LowLatencyCreateBuffer().
The interface must be open for the pipe to exist. The buf
pointer and the frameList
pointer need to be pre-allocated using LowLatencyCreateBuffer().
After using them, they should be freed using LowLatencyDestroyBuffer().
Result: Returns
Name Description self Pointer to the IOUSBInterfaceInterfacepipeRef Index for the desired pipe (1- GetNumEndpoints).buf Buffer to hold the data, previously allocated with LowLatencyCreateBuffer()using akUSBLowLatencyWriteBuffertype.frameStart The bus frame number on which to start the write. obtained from GetBusFrameNumbernumFrames The number of frames for which to transfer data updateFrequency 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. frameList A pointer to an array of IOUSBLowLatencyIsocFramestructures describing the framescallback An IOAsyncCallback1method. A message addressed to this callback is posted to the Async port upon completion.refCon Arbitrary pointer which is passed as a parameter to the callback routine.
kIOReturnSuccess if successful, kIOReturnNoDevice
if there is no connection to an IOService, or kIOReturnNotOpen
if the interface is not open for exclusive access. Will return kIOUSBLowLatencyBufferNotPreviouslyAllocated
or kIOUSBLowLatencyFrameListNotPreviouslyAllocated if the buffer
or the frameList were not previously allocated using LowLatencyCreateBuffer().
IOReturn(*ReadIsochPipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data frameStart the bus frame number on which to start the read. obtained from GetBusFrameNumber numFrames the number of frames for which to transfer data frameList A pointer to an array of IOUSBIsocFrame structures describing the frames callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
IOReturn(*ReadPipe)(void *self, UInt8 pipeRef, void *buf, UInt32 *size);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size on entry: a pointer to the size of the buffer pointed to by buf
on exit: a pointer to the number of bytes actually read from the device
IOReturn(*ReadPipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt32 size, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size the size of the buffer pointed to by buf callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: Does an asynchronous read on a BULK IN or an INTERRUPT pipe, with specified timeout values.IOReturn(*ReadPipeAsyncTO)(void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size the size of the buffer pointed to by buf noDataTimeout 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. This parameter must be set to 0 for interrupt pipes. completionTimeout 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. This parameter must be set to 0 for interrupt pipes. callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: Does a read on a BULK IN or an INTERRUPT pipe, specifying timeout valuesIOReturn(*ReadPipeTO)(void *self, UInt8 pipeRef, void *buf, UInt32 *size, UInt32 noDataTimeout, UInt32 completionTimeout);
The interface must be open for the pipe to exist.
If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size Pointer to the size of the buffer pointed to by buf noDataTimeout 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. This parameter must be set to 0 for interrupt pipes. completionTimeout 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. This parameter must be set to 0 for interrupt pipes.
IOReturn(*ResetPipe)(void *self, UInt8 pipeRef);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints).
IOReturn(*SetAlternateInterface)(void *self, UInt8 alternateSetting);
The interface must be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface alternateSetting The new alternate setting for the interface.
IOReturn(*SetPipePolicy)(void *self, UInt8 pipeRef, UInt16 maxPacketSize, UInt8 maxInterval);
The interface must be open for the pipe to exist.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints) maxPacketSize The desired size for the Isochronous pipe. Valid values are 0 through the maxPacketSize defined in the endpoint descriptor. maxInterval Currently ignored.
IOReturn(*USBInterfaceClose)(void *self);
Release the clients exclusive access to the IOUSBInterface.
Result: Returns kIOReturnSuccess if successful, some other mach error if the connection is no longer valid.
Name Description self Pointer to the IOUSBInterfaceInterface
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: Return the string index in the interface descriptor.IOReturn(*USBInterfaceGetStringIndex)(void *self, UInt8 *si);
The interface does not have to be open.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.
Name Description self Pointer to the IOUSBInterfaceInterface si Pointer to UInt8 to hold the string index
IOReturn(*USBInterfaceOpen)(void *self);
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.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface
Note: This function is only available with IOUSBInterfaceInterface183 and above.
Abstract: 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.IOReturn(*USBInterfaceOpenSeize)(void *self);
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.
Result: 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.
Name Description self Pointer to the IOUSBInterfaceInterface
IOReturn(*WriteIsochPipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data frameStart the bus frame number on which to start the read. obtained from GetBusFrameNumber numFrames the number of frames for which to transfer data frameList A pointer to an array of IOUSBIsocFrame structures describing the frames callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
IOReturn(*WritePipe)(void *self, UInt8 pipeRef, void *buf, UInt32 size);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size the size of the data buffer
IOReturn(*WritePipeAsync)(void *self, UInt8 pipeRef, void *buf, UInt32 size, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size the size of the buffer pointed to by buf callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: Does an asynchronous write on a BULK OUT pipe, with specified timeout values.IOReturn(*WritePipeAsyncTO)(void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data size the size of the buffer pointed to by buf noDataTimeout 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. completionTimeout 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. callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
Note: This function is only available with IOUSBInterfaceInterface182 and above.
Abstract: Does an asynchronous write on a BULK OUT pipe, with specified timeout values.IOReturn(*WritePipeAsyncTO)(void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);
The interface must be open for the pipe to exist.
If a timeout is specified and the request times out the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.
Result: Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.
Name Description self Pointer to the IOUSBInterfaceInterface pipeRef Index for the desired pipe (1-GetNumEndpoints). buf Buffer to hold the data. size the size of the buffer pointed to by buf noDataTimeout 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. completionTimeout 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. callback An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion. refCon Arbitrary pointer which is passed as a parameter to the callback routine.
© 2001-2002 Apple Computer, Inc. — (Last Updated 11/06/2002)