|
Home | Libraries | Author | Links |
|
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 order StmPipeFilter 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.
Files | |
| file | StmPipeAdtDoc.h |
| Documentation of the abstract structure data type type StmPipe. | |
Modules | |
| Abstract Data Type StmPipeWord | |
| A StmPipeWord object encapsulates status and value of one data byte flowing through a StmPipe data pipe object. | |
| Abstract Data Type StmPipeStream | |
| A StmPipeStream objects model drain and sink ends of a data pipes as well as the data stream between its filter stages. | |
| Abstract Data Type StmPipeFilter | |
| A StmPipeFilter object models one filter stage of a data pipe. | |
StmPipe Error Handling | |
| enum | StmPipeErrnos |
| Definition of all possible StmPipe error numbers. More... | |
| int | stmPipeGetErrno (StmPipe pipe) |
| Return the current StmPipe error number. | |
| int | stmPipeClearErrno (StmPipe pipe) |
| Clear the current StmPipe error number. | |
| const char * | stmPipeGetErrorMsg (StmPipe pipe) |
| Return the current StmPipe error message. | |
| const char * | stmPipeGetDebugMsg (StmPipe pipe) |
| Return the current StmPipe debug message. | |
| int | stmPipeSetDebugMsg (StmPipe pipe, const char *debugMsg) |
| Set a user defined StmPipe debug message. | |
| #define | StmPipeErrors |
| Definition of StmPipe error numbers and messages. | |
| #define | StmPipeErr(nr, txt) nr |
| Definition of the StmPipe error number nr for error message text txt. | |
StmPipe Representation | |
| An object of abstract data type StmPipe is represented as a pointer to its implementation. | |
| typedef struct StmPipeImpl_ | StmPipeImpl_ |
| Type name of implementation structure. | |
| typedef StmPipeImpl_ * | StmPipe |
| Pointer to implementation. | |
| typedef const StmPipeImpl_ * | ConstStmPipe |
| Pointer to constant implementation. | |
StmPipe Creation and Destruction | |
| StmPipe | stmPipeCreate (StmPipeStream input, StmPipeStream output, FILE *debug, StmPipeFilter *filters, size_t order, size_t bufferSize) |
| Creation of a new StmPipe object modelling a data pipe consisting of a multi-stage filter chain between a data drain and a data sink. | |
| void | stmPipeDestroy (StmPipe pipe) |
| Destruction of the StmPipe object pipe. | |
StmPipe Method Functions | |
| StmPipeStream | stmPipeGetInput (StmPipe pipe) |
| Return the input of the StmPipe object pipe. | |
| StmPipeStream | stmPipeGetOutput (StmPipe pipe) |
| Return the output of the StmPipe object pipe. | |
| FILE * | stmPipeGetDebug (StmPipe pipe) |
| Return the debug stream of the StmPipe object pipe. | |
| int | stmPipeGetOrder (StmPipe pipe) |
| Return the order of the StmPipe object pipe. | |
| StmPipeFilter | stmPipeGetFilter (StmPipe pipe, size_t stage) |
| Return the StmPipeFilter object at index stage of the filter chain of the StmPipe object pipe. | |
| int | stmPipeGetBufferSize (StmPipe pipe) |
| Return the buffer size used for the internal buffers of the StmPipeStream objects connecting the filters of the filter chain of the StmPipe object pipe. | |
| int | stmPipeExec (StmPipe pipe) |
| Execution of the StmPipe object pipe. | |
| #define StmPipeErrors |
Value:
/* Error number Error message text */ \ StmPipeErr (StmPipeErrOk, "no error"), \ StmPipeErr (StmPipeErrInval, "invalid argument"), \ StmPipeErr (StmPipeErrNoMem, "no more memory on heap"), \ StmPipeErr (StmPipeErrDeadlock, "deadlock"), \ StmPipeErr (StmPipeErrRead, "read error"), \ StmPipeErr (StmPipeErrWrite, "write error"), \ StmPipeErr (StmPipeErrCreate, "error in user function create"), \ StmPipeErr (StmPipeErrCtrl, "invalid control code"), \ StmPipeErr (StmPipeErrOperate, "error in user function operate"), \
The macro StmPipeErrors defines and names the possible StmPipe error numbers and their associated error message text by means of the macro StmPipeErr.
| #define StmPipeErr | ( | nr, | |||
| txt | ) | nr |
| typedef struct StmPipeImpl_ StmPipeImpl_ |
| typedef StmPipeImpl_* StmPipe |
| typedef const StmPipeImpl_* ConstStmPipe |
| enum StmPipeErrnos |
| StmPipe stmPipeCreate | ( | StmPipeStream | input, | |
| StmPipeStream | output, | |||
| FILE * | debug, | |||
| StmPipeFilter * | filters, | |||
| size_t | order, | |||
| size_t | bufferSize | |||
| ) |
Creation of a new StmPipe object modelling a data pipe consisting of a multi-stage filter chain between a data drain and a data sink.
| [in] | input | A StmPipeStream drain object ready for reading and typically created with one of the functions stmPipeStreamFileDrainCreate(), stmPipeStreamFdDrainCreate() or stmPipeStreamAppDrainCreate(). |
| [in] | output | A StmPipeStream sink object ready for writing and typically created with one of the functions stmPipeStreamFileSinkCreate(), stmPipeStreamFdSinkCreate() or stmPipeStreamAppSinkCreate(). |
| [in] | debug | If not NULL, a pointer to a stream used to print debug messages. |
| [in] | filters | 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. |
NULL on error. Then the variable errno reflects the error's cause. The StmPipe object created on success.
| void stmPipeDestroy | ( | StmPipe | pipe | ) |
Destruction of the StmPipe object pipe.
| [in] | pipe | The StmPipe object to destroy. |
NULL in which case the function does nothing. | StmPipeStream stmPipeGetInput | ( | StmPipe | pipe | ) |
Return the input of the StmPipe object pipe.
| [in] | pipe | The StmPipe object. |
NULL, if pipe is invalid (NULL). Then the variable errno is set to EINVAL. The StmPipeStrem object being the pipe input (drain).
| StmPipeStream stmPipeGetOutput | ( | StmPipe | pipe | ) |
Return the output of the StmPipe object pipe.
| [in] | pipe | The StmPipe object. |
NULL, if pipe is invalid (NULL). Then the variable errno is set to EINVAL. The StmPipeStrem object being the pipe output (sink).
| FILE* stmPipeGetDebug | ( | StmPipe | pipe | ) |
Return the debug stream of the StmPipe object pipe.
| [in] | pipe | The StmPipe object. |
NULL, if pipe is invalid (NULL). Then the variable errno is set to EINVAL.
A Pointer to the debug FILE stream of the pipe, or NULL, if no debug streem has been defined.
| int stmPipeGetOrder | ( | StmPipe | pipe | ) |
Return the order of the StmPipe object pipe.
| [in] | pipe | The StmPipe object. |
NULL, if pipe is invalid (NULL). Then the variable errno is set to EINVAL. The order, that is the number of filter stages of the filter chain of the pipe which is at least one and at most 127.
| StmPipeFilter stmPipeGetFilter | ( | StmPipe | pipe, | |
| size_t | stage | |||
| ) |
Return the StmPipeFilter object at index stage of the filter chain of the StmPipe object pipe.
| [in] | pipe | The StmPipe object. |
| [in] | stage | The filter stage index. |
NULL, if pipe is invalid (NULL). Then the variable errno is set to EINVAL.
NULL, if pipe is valid but stage is not less than its order. Then the variable errno is set to EINVAL.
The StmPipeFilter object being the filter at index stage of the filter chain of pipe, if pipe is valid and stage is less than its order.
| int stmPipeGetBufferSize | ( | StmPipe | pipe | ) |
Return the buffer size used for the internal buffers of the StmPipeStream objects connecting the filters of the filter chain of the StmPipe object pipe.
| [in] | pipe | The StmPipe object. |
NULL, if pipe is invalid (NULL). Then the variable errno is set to EINVAL. The the buffer size used for the internal buffers of the StmPipeStream objects connecting the filters of the filter chain of the StmPipe object pipe which is always a power of two.
| int stmPipeExec | ( | StmPipe | pipe | ) |
Execution of the StmPipe object pipe.
| [in] | pipe | The StmPipe object to execute. |
EOF or an error occurs. The function return the current error number of pipe which is also available through stmPipeGetErrno(); -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.
A positive value 256 * 127 + err indicates that a global operation error with error code err as its corresponding StmPipeErrnos enumerator occurred.
0, if pipe was executed successfully.
| int stmPipeGetErrno | ( | StmPipe | pipe | ) |
Return the current StmPipe error number.
| [in] | pipe | The StmPipe object. |
-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.
A positive value 256 * 127 + err indicates that a global operation error with error code err as its corresponding StmPipeErrnos enumerator occurred.
0, if no error occurred.
| int stmPipeClearErrno | ( | StmPipe | pipe | ) |
Clear the current StmPipe error number.
| [in] | pipe | The StmPipe object. |
-1 if pipe is invalid in which case errno is set to EINVAL.
0 on success.
| const char* stmPipeGetErrorMsg | ( | StmPipe | pipe | ) |
Return the current StmPipe error message.
| [in] | pipe | The StmPipe object. |
NULL if pipe is invalid in which case errno is set to EINVAL. The error message determined on success.
| const char* stmPipeGetDebugMsg | ( | StmPipe | pipe | ) |
Return the current StmPipe debug message.
| [in] | pipe | The StmPipe object. |
NULL if pipe is invalid in which case errno is set to EINVAL. The current debug message of pipe on success.
| int stmPipeSetDebugMsg | ( | StmPipe | pipe, | |
| const char * | debugMsg | |||
| ) |
Set a user defined StmPipe debug message.
| [in] | pipe | The StmPipe object. |
| [in] | debugMsg | The message to be set. |
-1 on error in which case the variable errno is set to reflect the error's cause.
0 on success.
© Copyright Tom Michaelis 2002-2007
Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).