Detailed Description

A StmPipe object models a data pipe consisting of a multi-stage filter chain between a data drain and a data sink.

Pipe.

The number of filters of a StmPipe object is called its order and is at least one and at most 127. The main purpose of a StmPipe object is to read StmByte objects from its StmPipeStream drain object, to process them successively in its orderStmPipeFilter filter objects and finally to write the result StmByte objects into its StmPipeStream sink object.

Although the objects processed by the order filters are in essence StmByte objects in reality StmPipeWord objects consisting of status and data content flow through the filter chain. This way the StmPipe can be controlled.

Pointer to the first element of an order dimensional array of StmPipeFilter objects not already attached to any StmPipe object.

[in]

order

The order of the data pipe.

[in]

bufferSize

The size of the StmPipeWord buffers used to connect the output of a filter stage with the input of its successor in the filter chain of the data pipe. If this value is no power of two it is rounded up to the next greater power of two.

Effects:

Creates the new StmPipe object and sets up the filter chain of length order attaching the orderStmPipeFilter objects with the StmPipe object creating and initializing their internally used filter specific data as needed.

The function destroys the StmPipe object pipe releasing all filter specific internal data, detaching its StmPipeFilter objects and freeing al internally used data buffers. It is no error to call the function for a StmPipe object with value NULL in which case the function does nothing.

The function executes the StmPipe object pipe until all operation functions of all filters of pipe have returned EOF or an error occurs. The function return the current error number of pipe which is also available through stmPipeGetErrno();

Returns:

-1 if pipe is invalid in which case errno is set to EINVAL.

A positive value 256 * i + err with index i of the filter in which an operation error with error code err as its corresponding StmPipeErrnos enumerator occurred.