ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

---

IOStream

Overview

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

Discussion

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."

---

Groups

Managing notifications

Group members:

inputCallback

Input callback function to be implemented by a subclass;

inputSyncCallback

Input callback function to be implemented by a subclass.

 

Managing user clients

Group members:

newUserClient

See the documentation for the IOService method newUserClient.

 

Managing notification ports

Group members:

getInputPort

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

getOutputPort

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

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.

setInputPort

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

setOutputPort

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

 

Creating IOStream objects

Group members:

free

initWithBuffers

withBuffers

 

Stream control

Group members:

getStreamMode

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

setStreamMode

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

startStream

Start sending data on a stream.

stopStream

Stop sending data on a stream.

suspendStream

Temporarily suspend data flow on the stream.

 

Queueing and dequeueing buffers

Group members:

dequeueInputEntry

enqueueOutputBuffer

A convenience method for enqueueing a buffer.

enqueueOutputEntry

 

Managing buffers in an IOStream

Group members:

addBuffer

Add a buffer to an IOStream.

addBuffers

getBufferCount

getBuffers

Get an array containing all the buffers in the stream.

getBufferWithID

removeAllBuffers()

removeAllBuffers()

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.

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.

 

Opening and closing streams

Group members:

handleClose

The handleClose method destroys the shared input and output queues.

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.

 

Managing shared queues

Group members:

createQueues

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

destroyQueues

Releases the shared input and output queues.

getInputQueue

getInputQueueMemoryDescriptor

getOutputQueue

getOutputQueueMemoryDescriptor

---

Functions

addBuffer

Add a buffer to an IOStream.

addBuffers

createQueues

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

dequeueInputEntry

destroyQueues

Releases the shared input and output queues.

enqueueOutputBuffer

A convenience method for enqueueing a buffer.

enqueueOutputEntry

free

getBufferCount

getBuffers

Get an array containing all the buffers in the stream.

getBufferWithID

getInputPort

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

getInputQueue

getInputQueueMemoryDescriptor

getOutputPort

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

getOutputQueue

getOutputQueueMemoryDescriptor

getStreamMode

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

handleClose

The handleClose method destroys the shared input and output queues.

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.

initWithBuffers

inputCallback

Input callback function to be implemented by a subclass;

inputSyncCallback

Input callback function to be implemented by a subclass.

newUserClient

See the documentation for the IOService method newUserClient.

removeAllBuffers()

removeAllBuffers()

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.

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.

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.

setInputPort

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

setOutputPort

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

setStreamMode

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

startStream

Start sending data on a stream.

stopStream

Stop sending data on a stream.

suspendStream

Temporarily suspend data flow on the stream.

withBuffers

---

addBuffer

---

Add a buffer to an IOStream.

public

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

---

public

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().

public

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

Parameters

queueLength

options

Return Value

Returns kIOReturnSuccess if the queues were successfully created.

---

dequeueInputEntry

---

public

virtual IOReturn dequeueInputEntry(
    IOStreamBufferQueueEntry *entry ); 

Parameters

entry

---

destroyQueues

---

Releases the shared input and output queues.

public

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.

public

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

Parameters

buffer

dataOffset

dataLength

controlOffset

controlLength

---

enqueueOutputEntry

---

public

virtual IOReturn enqueueOutputEntry(
    IOStreamBufferQueueEntry *entry ); 

Parameters

entry

---

free

---

public

virtual void free(
    void); 

---

getBufferCount

---

public

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.

public

virtual OSArray *getBuffers(
    void ); 

Discussion

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

---

getBufferWithID

---

public

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.

public

virtual mach_port_t getInputPort(
    void); 

---

getInputQueue

---

public

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

---

public

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.

public

virtual mach_port_t getOutputPort(
    void); 

---

getOutputQueue

---

public

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

---

public

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.

public

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.

public

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.

public

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

Parameters

options

arg

---

initWithBuffers

---

public

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;

public

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.

public

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.

public

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

---

removeAllBuffers()

---

public

virtual IOReturn removeAllBuffers(
    void ); 

---

removeAllBuffers()

---

public

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.

public

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.

public

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.

public

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.

public

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.

public

virtual IOReturn setOutputPort(
    mach_port_t port); 

Parameters

port

---

setStreamMode

---

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

public

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.

public

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.

public

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.

public

virtual IOReturn suspendStream(
    void); 

Return Value

Returns kIOReturnSuccess if the stream was successfully suspended.

Discussion

This must be implemented by a subclass.

---

withBuffers

---

public

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.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19