Mac Developer Library

Developer

IOStream Class Reference

Options
Deployment Target:

On This Page
Language:

IOStream

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.5 and later.
  • Returns the mode of the stream, either input or output.

    Declaration

    C++

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

    Import Statement

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

    Declaration

    C++

    virtual IOReturn setStreamMode( IOStreamMode mode);

    Discussion

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

    Import Statement

  • Start sending data on a stream.

    Declaration

    C++

    virtual IOReturn startStream( void);

    Return Value

    Returns kIOReturnSuccess if the stream was successfully started.

    Discussion

    This must be implemented by a subclass.

    Import Statement

  • Stop sending data on a stream.

    Declaration

    C++

    virtual IOReturn stopStream( void);

    Return Value

    Returns kIOReturnSuccess if the stream was successfully stopped.

    Discussion

    This must be implemented by a subclass.

    Import Statement

  • Temporarily suspend data flow on the stream.

    Declaration

    C++

    virtual IOReturn suspendStream( void);

    Return Value

    Returns kIOReturnSuccess if the stream was successfully suspended.

    Discussion

    This must be implemented by a subclass.

    Import Statement

  • Declaration

    C++

    virtual IOReturn dequeueInputEntry( IOStreamBufferQueueEntry *entry );

    Parameters

    entry

    Import Statement

  • A convenience method for enqueueing a buffer.

    Declaration

    C++

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

    Parameters

    buffer
    dataOffset
    dataLength
    controlOffset
    controlLength

    Import Statement

  • Declaration

    C++

    virtual IOReturn enqueueOutputEntry( IOStreamBufferQueueEntry *entry );

    Parameters

    entry

    Import Statement

  • The handleClose method destroys the shared input and output queues.

    Declaration

    C++

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

    Parameters

    options

    Import Statement

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

    Declaration

    C++

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

    Parameters

    options
    arg

    Import Statement

  • See the documentation for the IOService method newUserClient.

    Declaration

    C++

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

    Import Statement

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

    Declaration

    C++

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

    Parameters

    queueLength
    options

    Return Value

    Returns kIOReturnSuccess if the queues were successfully created.

    Import Statement

  • Releases the shared input and output queues.

    Declaration

    C++

    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.

    Import Statement

  • Declaration

    C++

    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.

    Import Statement

  • Declaration

    C++

    virtual IOMemoryDescriptor *getInputQueueMemoryDescriptor( void);

    Return Value

    An IOMemoryDescriptor object repesenting the shared memory input queue buffer.

    Import Statement

  • Declaration

    C++

    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.

    Import Statement

  • Declaration

    C++

    virtual IOMemoryDescriptor *getOutputQueueMemoryDescriptor( void);

    Return Value

    An IOMemoryDescriptor object repesenting the shared memory output queue buffer.

    Import Statement

  • Input callback function to be implemented by a subclass;

    Declaration

    C++

    virtual void inputCallback( UInt32token );

    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.

    Import Statement

  • Input callback function to be implemented by a subclass.

    Declaration

    C++

    virtual void inputSyncCallback( UInt32token );

    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.

    Import Statement

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

    Declaration

    C++

    virtual mach_port_t getInputPort( void);

    Import Statement

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

    Declaration

    C++

    virtual mach_port_t getOutputPort( void);

    Import Statement

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

    Declaration

    C++

    virtual IOReturn sendOutputNotification( void);

    Return Value

    Returns kIOReturnSuccess if the notification was successfully sent.

    Import Statement

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

    Declaration

    C++

    virtual IOReturn setInputPort( mach_port_tport);

    Parameters

    port

    Import Statement

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

    Declaration

    C++

    virtual IOReturn setOutputPort( mach_port_tport);

    Parameters

    port

    Import Statement

  • Add a buffer to an IOStream.

    Declaration

    C++

    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.

    Import Statement

  • Declaration

    C++

    virtual IOReturn addBuffers( OSArray *buffers);

    Parameters

    buffers

    Import Statement

  • Declaration

    C++

    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.

    Import Statement

  • Get an array containing all the buffers in the stream.

    Declaration

    C++

    virtual OSArray *getBuffers( void );

    Discussion

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

    Import Statement

  • Declaration

    C++

    virtual IOStreamBuffer *getBufferWithID( IOStreamBufferIDbufferID);

    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.

    Import Statement

  • Declaration

    C++

    virtual IOReturn removeAllBuffers( void );

    Import Statement

  • Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

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

    Declaration

    C++

    virtual IOReturn removeBuffer( IOStreamBufferIDbufferID);

    Parameters

    bufferID

    The ID of the buffer to remove.

    Return Value

    Returns kIOReturnSuccess if the buffer was removed.

    Import Statement

  • Declaration

    C++

    virtual void free( void);

    Import Statement

  • Declaration

    C++

    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.

    Import Statement

  • Declaration

    C++

    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.

    Import Statement