Mac Developer Library

Developer

IOStream Class Reference

Options
Deployment Target:

On This Page
Language:

IOStream

Inheritance


  • IOStream

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.5 and later.

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

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

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

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

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

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

  • Declaration

    C++

    virtual IOReturn dequeueInputEntry( IOStreamBufferQueueEntry *entry );

    Parameters

    entry
  • 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
  • Declaration

    C++

    virtual IOReturn enqueueOutputEntry( IOStreamBufferQueueEntry *entry );

    Parameters

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

    Declaration

    C++

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

    Parameters

    options
  • 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
  • See the documentation for the IOService method newUserClient.

    Declaration

    C++

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

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

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

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

  • Declaration

    C++

    virtual IOMemoryDescriptor *getInputQueueMemoryDescriptor( void);

    Return Value

    An IOMemoryDescriptor object repesenting the shared memory input queue buffer.

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

  • Declaration

    C++

    virtual IOMemoryDescriptor *getOutputQueueMemoryDescriptor( void);

    Return Value

    An IOMemoryDescriptor object repesenting the shared memory output queue buffer.

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

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

  • 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);

  • 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);

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

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

  • Declaration

    C++

    virtual IOReturn addBuffers( OSArray *buffers);

    Parameters

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

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

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

  • Declaration

    C++

    virtual IOReturn removeAllBuffers( void );

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

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

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

  • Declaration

    C++

    virtual void free( void);

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

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