Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access I/O Kit Framework Reference

IOStreamLib.h

Includes:

Overview

IOCFPlugin library for using IOStream objects.

Discussion

The IOStream plugin provides a convenient set of functions for accessing and manipulating IOStream objects from user programs.

Groups

Buffer information

Group members:

GetBufferInfo: Gets information about a buffer in an IOStream.

Run loop operations

Group members:

RemoveFromRunLoop: Remove the CFRunLoopSource for the notification port from a run loop.

Buffer operations on streams

Group members:

EnqueueInputBuffer: Send a buffer to the kernel side of the IOStream on the input queue.

Notifications

Group members:

SendInputSyncNotification: Notify the kernel side of the stream that input is ready by using a fast trap to call directly into the stream user client driver. This will transfer control to the kernel and continue executing on your same thread, rather than sending the notification to a separate thread.

Input and output

Group members:

SetOutputCallback: Set the callback function to be called when a new buffer is available from the kernel.

Opening and closing streams

Group members:

Close: Closes an IOStream.

Buffer convenience functions

Group members:

SetMode
SetMode()

Functions

AddToRunLoop: Add the CFRunLoopSource for the notification port to a run loop.
Close: Closes an IOStream.
DequeueOutputEntry: Get the next IOStreamBufferQueueEntry available from the output queue.
EnqueueInputBuffer: Send a buffer to the kernel side of the IOStream on the input queue.
EnqueueInputEntry
GetBufferCount: Gets the number of buffers in the stream.
GetBufferInfo: Gets information about a buffer in an IOStream.
GetControlBuffer: Get a pointer to the control area of an IOStreamBuffer.
GetControlBufferLength: Get the length of the control area of an IOStreamBuffer.
GetDataBuffer: Get a pointer to the data area of an IOStreamBuffer.
GetDataBufferLength: Get the length of the data area of an IOStreamBuffer.
GetInputPort: Get the notification port for buffers moving in from user to kernel space.
GetInputQueue: Get the shared memory queue for buffers moving in from user to kernel space.
GetMode
GetMode()
GetOutputPort: Get the notification port for buffers moving out from kernel to user space.
GetOutputQueue: Get the shared memory queue for buffers moving out from kernel to user space.
GetRunLoopSource: Gets a CFRunLoopSource for the CFMachPort used for notifications from the kernel that data is ready.
Open: Open an IOStream from user space.
RemoveFromRunLoop: Remove the CFRunLoopSource for the notification port from a run loop.
SendInputNotification: Send a notification to the kernel side of the IOStream that data is available in the input queue.
SendInputSyncNotification: Notify the kernel side of the stream that input is ready by using a fast trap to call directly into the stream user client driver. This will transfer control to the kernel and continue executing on your same thread, rather than sending the notification to a separate thread.
SetMode
SetMode()
SetOutputCallback: Set the callback function to be called when a new buffer is available from the kernel.
StartStream
StartStream()
StopStream
StopStream()
SuspendStream
SuspendStream()

AddToRunLoop

Add the CFRunLoopSource for the notification port to a run loop.

IOReturn ( *AddToRunLoop)(
    IOStreamRef stream, 
    CFRunLoopRef runLoop );

Parameters

stream: The IOStreamRef of the stream to operate on.
runLoop: The run loop to which to add the notification source.

Return Value

Returns kIOReturnSuccess if the source was successfully added to the run loop.

Close

Closes an IOStream.

IOReturn ( *Close)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to close.

Return Value

Returns kIOReturnSuccess if the stream was successfully closed and the buffers unmapped.

Discussion

Calling Close umaps all shared memory for the stream and frees all user resources used by the stream.

DequeueOutputEntry

Get the next IOStreamBufferQueueEntry available from the output queue.

IOReturn ( *DequeueOutputEntry)(
    IOStreamRef stream,
    IOStreamBufferQueueEntry *entry );

Parameters

stream: The IOStreamRef of the stream to operate on.
entry: A pointer to an IOStreamBufferQueueEntry structure. The next available entry from the output queue will be copied into it.

Return Value

The IOStreamBufferID of the next available buffer, or kInvalidIOStreamBufferID if no buffer is in the queue.

EnqueueInputBuffer

Send a buffer to the kernel side of the IOStream on the input queue.

IOReturn ( *EnqueueInputBuffer)(
    IOStreamRef stream,
    IOStreamBufferID bufferID, 
    IOByteCount dataOffset,
    IOByteCount dataLength, 
    IOByteCount controlOffset,
    IOByteCount controlLength );

Parameters

stream: The IOStreamRef of the stream to operate on.
bufferID: The IOStreamBufferID of the buffer to place on the queue.
dataLength: The length of the valid data in the buffer.

Return Value

Returns kIOReturnSuccess if the buffer was successfully placed on the input queue.

EnqueueInputEntry

IOReturn ( *EnqueueInputEntry)(
    IOStreamRef stream,
    IOStreamBufferQueueEntry *entry);

GetBufferCount

Gets the number of buffers in the stream.

IOItemCount ( *GetBufferCount)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to operate on.

Return Value

Returns then number of buffers in the stream.

GetBufferInfo

Gets information about a buffer in an IOStream.

IOReturn ( *GetBufferInfo)(
    IOStreamRef stream, 
    IOStreamBufferID bufferID, 
    void **dataBufferAddressOut,
    IOByteCount *dataBufferSizeOut, 
    void **controlBufferAddressOut,
    IOByteCount *controlBufferSizeOut );

Parameters

stream: The IOStreamRef of the stream to operate on.
bufferID
dataBufferAddressOut
dataBufferSizeOut
controlBufferAddressOut
controlBufferSizeOut

Return Value

Returns kIOReturnSuccess if the buffer ID was valid.

GetControlBuffer

Get a pointer to the control area of an IOStreamBuffer.

void *( *GetControlBuffer)(
    IOStreamRef stream,
    IOStreamBufferID bufferID );

Parameters

stream: The IOStreamRef of the stream owning the buffer.
buffer: The IOStreamBufferID of the buffer to operate on.

Return Value

A pointer to the control buffer area of the IOStreamBuffer, or NULL if it does not have a control buffer.

GetControlBufferLength

Get the length of the control area of an IOStreamBuffer.

IOByteCount ( *GetControlBufferLength)(
    IOStreamRef stream,
    IOStreamBufferID bufferID );

Parameters

stream: The IOStreamRef of the stream owning the buffer.
bufferID: The IOStreamBufferID of the buffer to operate on.

Return Value

The length in bytes of the control buffer, or 0 if there is no control buffer.

GetDataBuffer

Get a pointer to the data area of an IOStreamBuffer.

void *( *GetDataBuffer)(
    IOStreamRef stream,
    IOStreamBufferID bufferID );

Parameters

stream: The IOStreamRef of the stream owning the buffer.
bufferID: The IOStreamBufferID of the buffer to operate on.

Return Value

A pointer to the data buffer area of the IOStreamBuffer, or NULL if it does not have a data buffer.

GetDataBufferLength

Get the length of the data area of an IOStreamBuffer.

IOByteCount ( *GetDataBufferLength)(
    IOStreamRef stream,
    IOStreamBufferID bufferID );

Parameters

stream: The IOStreamRef of the stream owning the buffer.
bufferID: The IOStreamBufferID of the buffer to operate on.

Return Value

The length in bytes of the data buffer, or 0 if there is no data buffer.

GetInputPort

Get the notification port for buffers moving in from user to kernel space.

CFMachPortRef ( *GetInputPort)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to operate on.

Return Value

A CFMachPortRef for the input notification port.

GetInputQueue

Get the shared memory queue for buffers moving in from user to kernel space.

IOStreamBufferQueue *( *GetInputQueue)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to operate on.

Return Value

A pointer to the shared memory IOStreamBufferQueue structure for the input queue.

Discussion

If you use the notification functions, you should never need to access the queues directly.

GetMode

IOStreamMode ( *GetMode)(
    IOStreamRef stream );

GetMode()

IOStreamMode ( *GetMode)(
    IOStreamRef stream );

GetOutputPort

Get the notification port for buffers moving out from kernel to user space.

CFMachPortRef ( *GetOutputPort)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to operate on.

Return Value

A CFMachPortRef of the output notification port.

GetOutputQueue

Get the shared memory queue for buffers moving out from kernel to user space.

IOStreamBufferQueue *( *GetOutputQueue)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to operate on.

Return Value

A pointer to the shared memory IOStreamBufferQueue structure for the output queue.

Discussion

If you use the notification functions, you should never need to access the queues directly.

GetRunLoopSource

Gets a CFRunLoopSource for the CFMachPort used for notifications from the kernel that data is ready.

CFRunLoopSourceRef ( *GetRunLoopSource)(
    IOStreamRef stream );

Parameters

stream: The IOStreamRef of the stream to operate on.

Return Value

The CFRunLoopSourceRef for the run loop source, or NULL if there was an error creating the source.

Open

Open an IOStream from user space.

IOReturn ( *Open)(
    IOStreamRef stream,
    IOOptionBits options );

Parameters

stream: The reference to the stream returned by QueryInterface.
options: Open options. Currently unused.

Return Value

If the stream could not be opened or the buffers could not be mapped, an error will be returned.

Discussion

The Open function opens the stream and maps the memory for the shared input and output queues into the current task, as well as the memory for all the buffers in the queue. It also creates the notification ports for input and output.

RemoveFromRunLoop

Remove the CFRunLoopSource for the notification port from a run loop.

IOReturn ( *RemoveFromRunLoop)(
    IOStreamRef stream, 
    CFRunLoopRef runLoop );

Parameters

stream: The IOStreamRef of the stream to operate on.
runLoop: The run loop from which to remove the notification source.

Return Value

Returns kIOReturnSuccess if the source was successfully removed from the run loop.

SendInputNotification

Send a notification to the kernel side of the IOStream that data is available in the input queue.

IOReturn ( *SendInputNotification)(
    IOStreamRef stream,
    UInt32 token );

Parameters

stream: The IOStreamRef of the stream to operate on.
token: A value to pass to the stream's notification function. This is unused by IOStream but may be used by subclasses.

Return Value

Returns kIOReturnSuccess if the notification was successfully sent.

SendInputSyncNotification

Notify the kernel side of the stream that input is ready by using a fast trap to call directly into the stream user client driver. This will transfer control to the kernel and continue executing on your same thread, rather than sending the notification to a separate thread.

IOReturn ( *SendInputSyncNotification)(
    IOStreamRef stream,
    UInt32 token );

Parameters

stream: The IOStreamRef of the stream to operate on.
token: A value to pass to the stream's notification function. This is unused by IOStream but may be used by subclasses.

Return Value

Returns kIOReturnSuccess if the notification was successfully sent.

SetMode

IOReturn ( *SetMode)(
    IOStreamRef stream,
    IOStreamMode mode );

SetMode()

IOReturn ( *SetMode)(
    IOStreamRef stream,
    IOStreamMode mode );

SetOutputCallback

Set the callback function to be called when a new buffer is available from the kernel.

IOReturn ( *SetOutputCallback)(
    IOStreamRef stream, 
    IOStreamOutputCallback callback, 
    void *context );

Parameters

stream: The IOStreamRef of the stream to operate on. Pass NULL to remove the callback.

Return Value

Returns kIOReturnSuccess if the callback was successfully set or removed.

StartStream

IOReturn ( *StartStream)(
    IOStreamRef stream );

StartStream()

IOReturn ( *StartStream)(
    IOStreamRef stream );

StopStream

IOReturn ( *StopStream)(
    IOStreamRef stream );

StopStream()

IOReturn ( *StopStream)(
    IOStreamRef stream );

SuspendStream

IOReturn ( *SuspendStream)(
    IOStreamRef stream );

SuspendStream()

IOReturn ( *SuspendStream)(
    IOStreamRef stream );

Typedefs

IOStreamCallback
IOStreamOutputCallback
IOStreamRef

IOStreamCallback

See Also:

IOStreamOutputCallback

typedef void ( *IOStreamOutputCallback) ( 
    IOStreamRef stream, 
    void *context );

Callbacks

IOStreamOutputCallback

See Also:

IOStreamCallback

typedef void ( *IOStreamOutputCallback) ( 
    IOStreamRef stream, 
    void *context );

Callbacks

IOStreamRef

typedef struct IOStreamInterface_v1_t ** IOStreamRef;

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2009-10-15