Home Libraries Author Links

Abstract Data Type StmPipeStream
[Abstract Data Type StmPipe]

Collaboration diagram for Abstract Data Type StmPipeStream:

Detailed Description

A StmPipeStream objects model drain and sink ends of a data pipes as well as the data stream between its filter stages.

PipeStream.

StmPipeStream objects represent input and output of the StmPipeFilter objects of a StmPipe data pipe object. The input of the first filter being the drain of the pipe and the output of the last filter being the sink of the pipe each use one of three kinds of data transport media:

The inputs of all but the first and the outputs of all but the last StmPipeFilter object of a StmPipe data pipe object are represented by stmPipeStream objects using an internal data buffer as data transport medium.

Valid objects of type StmPipeStream visible to the user can be obtained only as return values of one of the StmPipeStream create functions or by stmPipeFilterGetInput() or stmPipeFilterGetOutput(). Moreover, variables of type StmPipeStream may have the value NULL meaning invalid or undefined.


Files

file  StmPipeStreamAdtDoc.h
 Documentation of the abstract structure data type type StmPipeStream.

StmPipeStream Representation

An object of abstract data type StmPipeStream is represented as a pointer to its implementation.

typedef struct StmPipeStreamImpl_ StmPipeStreamImpl_
 Type name of implementation structure.
typedef StmPipeStreamImpl_StmPipeStream
 Pointer to implementation.
typedef const StmPipeStreamImpl_ConstStmPipeStream
 Pointer to constant implementation.

StmPipeStream Creation and Destruction

StmPipeStream stmPipeStreamFileDrainCreate (FILE *file)
 Creation of a new StmPipeStream object modelling the drain end of a data pipe reading from a stream represented by a FILE pointer.
StmPipeStream stmPipeStreamFdDrainCreate (int fd)
 Creation of a new StmPipeStream object modelling the drain end of a data pipe reading from an input channel represented by a file descriptor.
StmPipeStream stmPipeStreamAppDrainCreate (void *data, StmBool(*isByteAvailable)(void *data), int(*deliverByte)(void *data))
 Creation of a new StmPipeStream object modelling the drain end of a data pipe reading by means of an application defined protocol.
StmPipeStream stmPipeStreamFileSinkCreate (FILE *file)
 Creation of a new StmPipeStream object modelling the sink end of a data pipe writing to a stream represented by a FILE pointer.
StmPipeStream stmPipeStreamFdSinkCreate (int fd)
 Creation of a new StmPipeStream object modelling the sink end of a data pipe writing to an oiutput channel represented by a file descriptor.
StmPipeStream stmPipeStreamAppSinkCreate (void *data, StmBool(*isByteWelcome)(void *data), int(*acceptByte)(void *data, StmByte byte))
 Creation of a new StmPipeStream object modelling the sink end of a data pipe writing by means of an application defined protocol.
void stmPipeStreamDestroy (StmPipeStream stream)
 Destruction of the StmPipeStream object stream.

StmPipeStream Method Functions

StmBool stmPipeStreamIsItemAvailable (StmPipeStream stream)
 Determine, if a StmPipeWord is available from the StmPipeStream object stream.
StmPipeWord stmPipeStreamDeliverItem (StmPipeStream stream)
 Return a StmPipeWord from the StmPipeStream object stream.
StmBool stmPipeStreamIsItemWelcome (StmPipeStream stream)
 Determine, if the StmPipeStream object stream is able to accept a StmPipeWord.
StmPipeWord stmPipeStreamAcceptItem (StmPipeStream stream, StmPipeWord item)
 Write the StmPipeWord item to the StmPipeStream object stream.


Typedef Documentation

typedef struct StmPipeStreamImpl_ StmPipeStreamImpl_

Type name of implementation structure.

Definition at line 60 of file StmPipeStreamAdtDoc.h.

typedef StmPipeStreamImpl_* StmPipeStream

Pointer to implementation.

Definition at line 63 of file StmPipeStreamAdtDoc.h.

typedef const StmPipeStreamImpl_* ConstStmPipeStream

Pointer to constant implementation.

Definition at line 66 of file StmPipeStreamAdtDoc.h.


Function Documentation

StmPipeStream stmPipeStreamFileDrainCreate ( FILE *  file  ) 

Creation of a new StmPipeStream object modelling the drain end of a data pipe reading from a stream represented by a FILE pointer.

Parameters:
[in] file FILE pointer to the input stream.
Effects:
The function creates a StmPipeStream object. This object is intended to be used as input argument of stmPipeCreate() or as argument of the other StmPipeStream functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeStream object created on success.

See also:
stmPipeStreamFdDrainCreate(), stmPipeStreamAppDrainCreate(), stmPipeStreamDestroy(), stmPipeCreate().

StmPipeStream stmPipeStreamFdDrainCreate ( int  fd  ) 

Creation of a new StmPipeStream object modelling the drain end of a data pipe reading from an input channel represented by a file descriptor.

Parameters:
[in] fd The file descriptor representing the input channel.
Effects:
The function creates a StmPipeStream object. This object is intended to be used as input argument of stmPipeCreate() or as argument of the other StmPipeStream functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeStream object created on success.

See also:
stmPipeStreamFileDrainCreate(), stmPipeStreamAppDrainCreate(), stmPipeStreamDestroy(), stmPipeCreate().

StmPipeStream stmPipeStreamAppDrainCreate ( void *  data,
StmBool(*)(void *data)  isByteAvailable,
int(*)(void *data)  deliverByte 
)

Creation of a new StmPipeStream object modelling the drain end of a data pipe reading by means of an application defined protocol.

Parameters:
[in] data A pointer to an application provided input data buffer.
[in] isByteAvailable Pointer to a function which shall return StmTrue, if at least one StmByte is available from data, else StmFalse.
[in] deliverByte Pointer to a function which shall return the next StmByte available from data as int. No value greater tham 256 shall be returned. A value less than 0 leads to the error condition StmPipeErrRead.
Effects:
The function creates a StmPipeStream object. This object is intended to be used as input argument of stmPipeCreate() or as argument of the other StmPipeStream functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeStream object created on success.

See also:
stmPipeStreamFileDrainCreate(), stmPipeStreamFpDrainCreate(), stmPipeStreamDestroy(), stmPipeCreate().

StmPipeStream stmPipeStreamFileSinkCreate ( FILE *  file  ) 

Creation of a new StmPipeStream object modelling the sink end of a data pipe writing to a stream represented by a FILE pointer.

Parameters:
[in] file FILE pointer to the output stream.
Effects:
The function creates a StmPipeStream object. This object is intended to be used as output argument of stmPipeCreate() or as argument of the other StmPipeStream functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeStream object created on success.

See also:
stmPipeStreamFdSinkCreate(), stmPipeStreamAppSinkCreate(), stmPipeStreamDestroy(), stmPipeCreate().

StmPipeStream stmPipeStreamFdSinkCreate ( int  fd  ) 

Creation of a new StmPipeStream object modelling the sink end of a data pipe writing to an oiutput channel represented by a file descriptor.

Parameters:
[in] fd The file descriptor representing the output channel.
Effects:
The function creates a StmPipeStream object. This object is intended to be used as output argument of stmPipeCreate() or as argument of the other StmPipeStream functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeStream object created on success.

See also:
stmPipeStreamFileSinkCreate(), stmPipeStreamAppSinkCreate(), stmPipeStreamDestroy(), stmPipeCreate().

StmPipeStream stmPipeStreamAppSinkCreate ( void *  data,
StmBool(*)(void *data)  isByteWelcome,
int(*)(void *data, StmByte byte)  acceptByte 
)

Creation of a new StmPipeStream object modelling the sink end of a data pipe writing by means of an application defined protocol.

Parameters:
[in] data A pointer to an application provided output data buffer.
[in] isByteWelcome Pointer to a function which shall return StmTrue, if data is able to accept at least one StmByte, else StmFalse.
[in] acceptByte Pointer to a function which shall deliver the StmByte byte to data. On success it shall return 0. A return value less than 0 leads to the error condition StmPipeErrWrite.
Effects:
The function creates a StmPipeStream object. This object is intended to be used as output argument of stmPipeCreate() or as argument of the other StmPipeStream functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeStream object created on success.

See also:
stmPipeStreamFileSinkCreate(), stmPipeStreamFpSinkCreate(), stmPipeStreamDestroy(), stmPipeCreate().

void stmPipeStreamDestroy ( StmPipeStream  stream  ) 

Destruction of the StmPipeStream object stream.

Parameters:
[in] stream The StmPipeStream object to destroy.
Effects:
The function destroys the StmPipeStream object stream releasing all resources held by it. It is no error to call the function for a StmPipeStream object with value NULL in which case the function does nothing.
See also:
stmPipeStreamFileDrainCreate(), stmPipeStreamFpDrainCreate(), stmPipeStreamAppDrainCreate(), stmPipeStreamFileSinkCreate(), stmPipeStreamFpSinkCreate(), stmPipeStreamAppSinkCreate().

StmBool stmPipeStreamIsItemAvailable ( StmPipeStream  stream  ) 

Determine, if a StmPipeWord is available from the StmPipeStream object stream.

Parameters:
[in] stream The StmPipeStream object.
Returns:
StmFalse, if no StmPipeWord is available from stream.

StmTrue, if a StmPipeWord is available from stream.

See also:
stmPipeStreamDeliverItem().

StmPipeWord stmPipeStreamDeliverItem ( StmPipeStream  stream  ) 

Return a StmPipeWord from the StmPipeStream object stream.

Parameters:
[in] stream The StmPipeStream object.
Returns:
The StmPipeWord with the error code StmPipeErrInval, if stream is invalid.

The StmPipeWord with the error code StmPipeErrRead, if no StmPipeWord could be retrieved from stream.

The StmPipeWord retrieved from stream on success.

See also:
stmPipeStreamIsItemAvailable().

StmBool stmPipeStreamIsItemWelcome ( StmPipeStream  stream  ) 

Determine, if the StmPipeStream object stream is able to accept a StmPipeWord.

Parameters:
[in] stream The StmPipeStream object.
Returns:
StmFalse, if stream is not able to accept a StmPipeWord.

StmTrue, if stream is able to accept a StmPipeWord.

See also:
stmPipeStreamAcceptItem().

StmPipeWord stmPipeStreamAcceptItem ( StmPipeStream  stream,
StmPipeWord  item 
)

Write the StmPipeWord item to the StmPipeStream object stream.

Parameters:
[in] stream The StmPipeStream object.
[in] item The StmPipeWord stream has to accept.
Returns:
The StmPipeWord with the error code StmPipeErrInval, if stream is invalid.

The StmPipeWord with the error code StmPipeErrWrite, if stream could not accept item.

The StmPipeWord StmPipeErrOk on success.

See also:
stmPipeStreamIsItemWelcome().


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).