IOStream

Inherits from
IOService
Availability
Available in OS X v10.5 and later.
Declared in
IOStream.h

Overview

A class representing a stream of data buffers passed from kernel to user space and back again.

The IOStream class defines a mechanism for moving buffers of data from kernel space to user space or vice-versa. The policy for which direction the data flows and the nature of the data is left up the the implementer of the driver which uses IOStream.

Although it is expected that the client of an IOStream will be in user space, this is not required.

References to "output" mean "from the IOStream to the user client", and "input" means "from the user client to the IOStream."

Tasks

Stream Control

Queueing and Dequeueing Buffers

Opening and Closing Streams

Managing User Clients

Managing Shared Queues

Managing Notifications

Managing Notification Ports

Managing Buffers in an IOStream

Creating IOStream Objects

Instance Methods

addBuffer

Add a buffer to an IOStream.

virtual IOReturn addBuffer( IOStreamBuffer *buffer);
Parameters
buffer
Discussion

Adds an IOStreamBuffer to an IOStream. It will be added to the end of the buffer array, so the buffer ID of existing buffers will not change.

addBuffers

virtual IOReturn addBuffers( OSArray *buffers);
Parameters
buffers

createQueues

Creates the shared input and output queues, without regard to whether the stream is open or not. Normally this is called by handleOpen().

virtual IOReturn createQueues( IOItemCount queueLength = 0, IOOptionBits options = 0 );
Parameters
queueLength
options
Return Value

Returns kIOReturnSuccess if the queues were successfully created.

dequeueInputEntry

virtual IOReturn dequeueInputEntry( IOStreamBufferQueueEntry *entry );
Parameters
entry

destroyQueues

Releases the shared input and output queues.

virtual IOReturn destroyQueues( void );
Return Value

Returns kIOReturnSuccess if the queues were successfully destroyed. The queues cannot be destroyed while the stream is open by a client.

enqueueOutputBuffer

A convenience method for enqueueing a buffer.

virtual IOReturn enqueueOutputBuffer( IOStreamBuffer *buffer, IOByteCount dataOffset = 0, IOByteCount dataLength = 0, IOByteCount controlOffset = 0, IOByteCount controlLength = 0);
Parameters
buffer
dataOffset
dataLength
controlOffset
controlLength

enqueueOutputEntry

virtual IOReturn enqueueOutputEntry( IOStreamBufferQueueEntry *entry );
Parameters
entry

free

virtual void free( void);

getBufferCount

virtual IOItemCount getBufferCount( void );
Return Value

Returns kIOReturnSuccess if all the buffers were successfully removed. Buffers cannot be removed while the stream is open, as this will change the buffer IDs of existing buffers.

getBuffers

Get an array containing all the buffers in the stream.

virtual OSArray *getBuffers( void );
Discussion

Returns an OSArray containing all the buffers in the stream in order of their buffer ID.

getBufferWithID

virtual IOStreamBuffer *getBufferWithID( IOStreamBufferID bufferID);
Parameters
bufferID

The ID of the buffer to get.

Return Value

A pointer to an IOStreamBuffer object, or NULL if the buffer ID was invalid for this stream.

getInputPort

Get the Mach port used to receive notifications from user space that a buffer has been added to the input queue.

virtual mach_port_t getInputPort( void);

getInputQueue

virtual IOStreamBufferQueue *getInputQueue( void);
Return Value

A pointer to the input IOStreamBufferQueue structure for the stream, or NULL if the stream is not open and the queue has not been created yet.

getInputQueueMemoryDescriptor

virtual IOMemoryDescriptor *getInputQueueMemoryDescriptor( void);
Return Value

An IOMemoryDescriptor object repesenting the shared memory input queue buffer.

getOutputPort

Get the Mach port used to send notifications to user space that a buffer has been added to the output queue.

virtual mach_port_t getOutputPort( void);

getOutputQueue

virtual IOStreamBufferQueue *getOutputQueue( void);
Return Value

A pointer to the output IOStreamBufferQueue structure for the stream, or NULL if the stream is not open and the queue has not been created yet.

getOutputQueueMemoryDescriptor

virtual IOMemoryDescriptor *getOutputQueueMemoryDescriptor( void);
Return Value

An IOMemoryDescriptor object repesenting the shared memory output queue buffer.

getStreamMode

Returns the mode of the stream, either input or output.

virtual IOStreamMode getStreamMode( void);
Return Value

The mode of the stream, either kIOStreamModeInput (from user space to kernel space) or the default kIOStreamModeOutput (from kernel space to user space).

handleClose

The handleClose method destroys the shared input and output queues.

virtual void handleClose( IOService *forClient, IOOptionBits options );
Parameters
options

handleOpen

The handleOpen() method relies on the default IOService behavior to ensure that only one client has the stream open at a time. The shared input and output queues are created at open time.

virtual bool handleOpen( IOService *forClient, IOOptionBits options, void *arg );
Parameters
options
arg

initWithBuffers

virtual bool initWithBuffers( OSArray *buffers, IOStreamMode mode = kIOStreamModeOutput, IOItemCount queueLength = 0, OSDictionary *properties = 0);
Parameters
mode

The initial mode of the stream, either output, input, or input/output.

queueLength

The nuber of queue entries to reserve in the input and output queue. Zero means to make the queues big enough to accommodate all the buffers at once.

properties

A dictionary of properties which will be set on the stream.

buffers

An array of IOStreamBuffer objects which will be the buffers for this stream.

inputCallback

Input callback function to be implemented by a subclass;

virtual void inputCallback( UInt32 token );
Parameters
token

A 32-bit token value that can be used by convention to communicate from user space to the stream. The semantics of this value are defined by the IOStream subclass.

Discussion

The inputCallback() method is called as a result of a fast trap from user space. It is called on the same thread as the user request, but the subclass should implement this call as a notification sent to a workloop so that the request is asynchronous.

inputSyncCallback

Input callback function to be implemented by a subclass.

virtual void inputSyncCallback( UInt32 token );
Parameters
token

A 32-bit token value that can be used by convention to communicate from user space to the stream. The semantics of this value are defined by the IOStream subclass.

Discussion

The inputSyncCallback() method is called as a result of a fast trap from user space. It is called on the same thread as the user request, so no context switch is necessary.

newUserClient

See the documentation for the IOService method newUserClient.

virtual IOReturn newUserClient( task_t owningTask, void *securityID, UInt32 type, OSDictionary *properties, IOUserClient **handler );

removeAllBuffers()

virtual IOReturn removeAllBuffers( void );

removeAllBuffers()

virtual IOItemCount getBufferCount( void );
Return Value

Returns kIOReturnSuccess if all the buffers were successfully removed. Buffers cannot be removed while the stream is open, as this will change the buffer IDs of existing buffers.

removeBuffer(IOStreamBuffer *)

Removes a buffer from the stream. Buffers cannot be removed while the stream is open, as this will change the buffer IDs of existing buffers.

virtual IOReturn removeBuffer( IOStreamBuffer *buffer);
Parameters
buffer

A pointer to an IOStreamBuffer object in the stream.

Return Value

Returns kIOReturnSuccess if the buffer was removed, or kIOReturnNotFound if the buffer was not in this stream.

removeBuffer(IOStreamBufferID)

Removes a buffer from the stream. Buffers cannot be removed while the stream is open, as this will change the buffer IDs of existing buffers.

virtual IOReturn removeBuffer( IOStreamBufferID bufferID);
Parameters
bufferID

The ID of the buffer to remove.

Return Value

Returns kIOReturnSuccess if the buffer was removed.

sendOutputNotification

Send a notification to the user client that data is available for reading on the output queue. This will result in the user's output handler being called, if they registered one.

virtual IOReturn sendOutputNotification( void);
Return Value

Returns kIOReturnSuccess if the notification was successfully sent.

setInputPort

Set the Mach port used to receive notifications from user space that a buffer has been added to the input queue.

virtual IOReturn setInputPort( mach_port_t port);
Parameters
port

setOutputPort

Set the Mach port used to send notifications to user space that a buffer has been added to the output queue.

virtual IOReturn setOutputPort( mach_port_t port);
Parameters
port

setStreamMode

Sets the mode of the stream, either input or output.

virtual IOReturn setStreamMode( IOStreamMode mode);
Discussion

Subclasses may define whether it is possible to change the mode of a stream.

startStream

Start sending data on a stream.

virtual IOReturn startStream( void);
Return Value

Returns kIOReturnSuccess if the stream was successfully started.

Discussion

This must be implemented by a subclass.

stopStream

Stop sending data on a stream.

virtual IOReturn stopStream( void);
Return Value

Returns kIOReturnSuccess if the stream was successfully stopped.

Discussion

This must be implemented by a subclass.

suspendStream

Temporarily suspend data flow on the stream.

virtual IOReturn suspendStream( void);
Return Value

Returns kIOReturnSuccess if the stream was successfully suspended.

Discussion

This must be implemented by a subclass.

withBuffers

static IOStream *withBuffers( OSArray *buffers, IOStreamMode mode = kIOStreamModeOutput, IOItemCount queueLength = 0, OSDictionary *properties = 0);
Parameters
mode

The initial mode of the stream, either output, input, or input/output.

queueLength

The nuber of queue entries to reserve in the input and output queue. Zero means to make the queues big enough to accommodate all the buffers at once.

properties

A dictionary of properties which will be set on the stream.

buffers

An array of IOStreamBuffer objects which will be the buffers for this stream.