Home Libraries Author Links

Abstract Data Type StmPipeFilter
[Abstract Data Type StmPipe]

Collaboration diagram for Abstract Data Type StmPipeFilter:

Detailed Description

A StmPipeFilter object models one filter stage of a data pipe.

PipeFilter.

StmPipeFilter objects represent the filter stages of the filter chain of a StmPipe data pipe object. If a StmPipeFilter object is attached to a StmPipe object, its output is connected to the input of the subsequent filter stage by a StmPipeStream object or to the output of the data pipe, if the filter is the last one in the filter chain. If the filter is the first one in the filter chain, its input is connected to the input of the data pipe, else to the output of the preceding filter stage.

Valid objects of type StmPipeFilter visible to the user can be obtained only as return values of one of the functions stmPipeFilterCreate() or stmPipeGetFilter(). Moreover, variables of type StmPipeFilter may have the value NULL meaning invalid or undefined.


Files

file  StmPipeFilterAdtDoc.h
 Documentation of the abstract structure data type type StmPipeFilter.

StmPipeFilter Representation

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

typedef struct StmPipeFilterImpl_ StmPipeFilterImpl_
 Type name of implementation structure.
typedef StmPipeFilterImpl_StmPipeFilter
 Pointer to implementation.
typedef const StmPipeFilterImpl_ConstStmPipeFilter
 Pointer to constant implementation.

StmPipeFilter Creation and Destruction

StmPipeFilter stmPipeFilterCreate (StmPipeWord(*operate)(StmPipeFilter filter, StmPipeWord item), void *(*createData)(StmPipeFilter filter), void(*destroyData)(StmPipeFilter filter), void *env)
 Creation of a new StmPipeFilter object modelling a filter for a StmPipe object not yet attached to any data pipe.
int stmPipeFilterDestroy (StmPipeFilter filter)
 Destruction of the StmPipeFilter object filter.

StmPipeFilter Method Functions

StmPipe stmPipeFilterGetPipe (StmPipeFilter filter)
 Return the StmPipe object the StmPipeFilter object filter is attached to.
StmPipeStream stmPipeFilterGetInput (StmPipeFilter filter)
 Return the input of the StmPipeFilter object filter.
StmPipeStream stmPipeFilterGetOutput (StmPipeFilter filter)
 Return the output of the StmPipeFilter object filter.
int stmPipeFilterGetStage (StmPipeFilter filter)
 Return the filter stage index of the StmPipeFilter object filter.
void * stmPipeFilterGetData (StmPipeFilter filter)
 Return a pointer to the filter internal data of the StmPipeFilter object filter.
void * stmPipeFilterGetEnv (StmPipeFilter filter)
 Return a pointer to the filter environment of the StmPipeFilter object filter.


Typedef Documentation

typedef struct StmPipeFilterImpl_ StmPipeFilterImpl_

Type name of implementation structure.

Definition at line 60 of file StmPipeFilterAdtDoc.h.

typedef StmPipeFilterImpl_* StmPipeFilter

Pointer to implementation.

Definition at line 63 of file StmPipeFilterAdtDoc.h.

typedef const StmPipeFilterImpl_* ConstStmPipeFilter

Pointer to constant implementation.

Definition at line 66 of file StmPipeFilterAdtDoc.h.


Function Documentation

StmPipeFilter stmPipeFilterCreate ( StmPipeWord(*)(StmPipeFilter filter, StmPipeWord item)  operate,
void *(*)(StmPipeFilter filter)  createData,
void(*)(StmPipeFilter filter)  destroyData,
void *  env 
)

Creation of a new StmPipeFilter object modelling a filter for a StmPipe object not yet attached to any data pipe.

Parameters:
[in] operate A not NULL pointer to a filter operation function
          StmPipeWord operateFct (StmPipeFilter filter, StmPipeWord item)
called by stmPipeExec() for each StmPipeWord item read from the filter input. The filter operation function shall process item and return its result as StmPipeWord conforming to the following requirements:
Normally the status content of the StmPipeWord argument item is 0 and its data content contains the StmByte to process. Non-null status contents hi with
          (hi & ::StmPipeCtrl) == 0
are reserved for future extensions. Data contents lo of item with designate synchronous control codes for the operation functions of one or more of the n (1 <= n < 128) filter stages with a meaning dependent on
          i = hi & ~::StmPipeCtrl
according to the following table:
Meaning of the data content lo of item depending on i = hi & ~StmPipeCtrl
i = hi & ~StmPipeCtrl Meaning of data content lo
0 <= i < n lo is a control code for the operation function of the i-th filter stage. The value item shall flow through the filter chain without being used by the operation functions of the j-th (j < i) filter stage, that means they shall pass through unchanged. The operation function of filter stage i shall receive a value item == (StmPipeCtrl, lo) and evaluate the it in a filter specific way. Then the value (StmPipeCtrl, lo) shall vanish from the pipe.
i == 127hi is then 0xff and lo is a control code for the operation function of each of the n filter stages of the pipe. Each of them receives a value item == (0xff, lo) which it shall evaluate in a filter specific way and return it immediately, later or not at all thus forwarding it to the subsequent filter stage or not.
An example of such a case is item == EOF == (0xff, 0xff).

It is an error, if in a filter stage j > i of the pipe appears a control code addressed for filter stage i.
The operation function of filter stage i shall return the StmPipeWord
          ret = (rhi, rlo)
with a meaning according to the following table:
Meaning of the return value of a filter operation function
Status content rhi Meaning of the return value
rhi == StmPipeNormal (0, rlo) is forwarded to the subsequent filter stage and the next value from the preceding filter stage is requested as next input.
rhi == StmPipeAgain (0, rlo) is forwarded to the subsequent filter stage and the last value from the preceding filter stage is requested again as next input.
rhi == StmPipeNeedItem No value is forwarded to the subsequent filter stage and the next value from the preceding filter stage is requested as next input.
rhi == StmPipeError An error with error code rlo occurred in the operation function. The execution of the whole pipe, that means the function stmPipeExec() is terminated with the return value (i, rlo). In the error case the operating function may set an own text for the StmPipe debug message by means of stmPipeSetDebugMsg().
(rhi & StmPipeNormal) != 0 (0, rlo) is forwarded to the subsequent filter stage and the next value from the preceding filter stage is requested as next input. rlo must be either a control code for all filter stages in which case rhi is 0xff, or the control code rlo must be address one of the subsequent filter stages in which case (rhi & ~StmPipeCtrl) > 1 must hold.
[in] createData If not NULL, a pointer to a function
          void *createDataFct (StmPipeFilter filter)
used to create and initialize the internal filter specific data of the StmPipeFilter object to be created. If createData is NULL, the filter has no internal filter specific data. Else the function is called by stmPipeCreate() and shall create and initialize the internal filter specific data and return a pointer to them on success or NULL on error, in which case it shall set the variable errno accodingly.
[in] destroyData If not NULL, a pointer to a function
          void destroyDataFct (StmPipeFilter filter)
which shall be NULL, if and only if createData is NULL. If not NULL, the function is called by stmPipeDestroy() and shall deinitialize and destroy the internal filter specific data created by means of creteData.
[in] env If not NULL, pointer to the filter environment initialized by the caller.
Effects:
The function creates a StmPipeFilter object not yet attached to any StmPipe data pipe object. This object is intended as element of the StmPipeFilter array to be used as filters argument of stmPipeCreate() or as argument of the other StmPipeFilter functions.
Returns:
NULL on error. Then the variable errno reflects the error's cause.

The StmPipeFilter object created on success.

See also:
stmPipeFilterDestroy(), stmPipeCreate().

int stmPipeFilterDestroy ( StmPipeFilter  filter  ) 

Destruction of the StmPipeFilter object filter.

Parameters:
[in] filter The StmPipeFilter object to destroy.
Effects:
If filter is not attached to a StmPipe object, the function destroys the StmPipeFilter object filter releasing all resources held by it. It is no error to call the function for a StmPipeFilter object with value NULL in which case the function does nothing.
Returns:
-1, if filter is attached to a StmPipe object. Then the variable errno is set to EBUSY.

0 on success.

See also:
stmPipeFilterCreate(), stmPipeCreate().

StmPipe stmPipeFilterGetPipe ( StmPipeFilter  filter  ) 

Return the StmPipe object the StmPipeFilter object filter is attached to.

Parameters:
[in] filter The StmPipeFilter object.
Returns:
NULL, if filter is not attached to a StmPipe object.

The StmPipe object filter is attached to, if such a attachment exists.

StmPipeStream stmPipeFilterGetInput ( StmPipeFilter  filter  ) 

Return the input of the StmPipeFilter object filter.

Parameters:
[in] filter The StmPipeFilter object.
Returns:
NULL, if filter is invalid (NULL). Then the variable errno is set to EINVAL.

The StmPipeStrem object being the filter input, if filter is valid. This is NULL, if filter is not attached to a StmPipe object.

Note:
This function is intended to be used by the filter operation function.
See also:
stmPipeFilterGetOutput(), stmPipeCreate().

StmPipeStream stmPipeFilterGetOutput ( StmPipeFilter  filter  ) 

Return the output of the StmPipeFilter object filter.

Parameters:
[in] filter The StmPipeFilter object.
Returns:
NULL, if filter is invalid (NULL). Then the variable errno is set to EINVAL.

The StmPipeStrem object being the filter output, if filter is valid. This is NULL, if filter is not attached to a StmPipe object.

Note:
This function is intended to be used by the filter operation function.
See also:
stmPipeFilterGetInput(), stmPipeCreate().

int stmPipeFilterGetStage ( StmPipeFilter  filter  ) 

Return the filter stage index of the StmPipeFilter object filter.

Parameters:
[in] filter The StmPipeFilter object.
Returns:
-1, if filter is invalid (NULL). Then the variable errno is set to EINVAL.

The filter stage index in the filter chain of the StmPipe object filter is attached to, if filter is valid. This is 255, if filter is not attached to a StmPipe object.

Note:
This function is intended to be used by the filter operation function.
See also:
stmPipeCreate().

void* stmPipeFilterGetData ( StmPipeFilter  filter  ) 

Return a pointer to the filter internal data of the StmPipeFilter object filter.

Parameters:
[in] filter The StmPipeFilter object.
Returns:
NULL, if filter is invalid (NULL). Then the variable errno is set to EINVAL.

A pointer to the filter internal data, if filter is valid. This is NULL, if filter is not attached to a StmPipe object.

Note:
This function is intended to be used by the filter operation function.
See also:
stmPipeFilterCreate(), stmPipeCreate().

void* stmPipeFilterGetEnv ( StmPipeFilter  filter  ) 

Return a pointer to the filter environment of the StmPipeFilter object filter.

Parameters:
[in] filter The StmPipeFilter object.
Returns:
NULL, if filter is invalid (NULL). Then the variable errno is set to EINVAL.

A pointer to the filter environment, if filter is valid.

Note:
This function is intended to be used by the filter operation function.
See also:
stmPipeFilterCreate().


© Copyright Tom Michaelis 2002-2007

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