Plug-In Filter Channel

Syntax

dp_connect plugfilter -channel channel_name -infilter filter_name -outfilter filter_name

Comments

Arguments: 

Description of Filter Functions
 
Prototype: int Filter (char *inBuf, int inLength, char **outBuf, int *outLength, void **data, Tcl_Interp *interp, int mode) 

Arguments: We provide below the parameters' default interpretation. For the other cases, please refer to the description of the mode parameter below.

Return value: If no error is detected, the return value must be zero. A non-zero return value signals an error, if needed, POSIX error codes can be used to indicate the type of the error.

Before being used, a filter function has to be registered by calling function Dp_RegisterPlugInFilter. TCL_OK is returned upon successful completion of registration. 

Prototype: int Dp_RegisterPlugInFilter (Tcl_Interp interp, Dp_PlugInFilter *newPlugInPtr) 

Arguments: 

Filter functions can also be pre-registered, by adding them to the array builtInPlugs in file generic/dpChan.c, and recompiling Tcl-DP. As of now, the following plug-in filters are provided (unless specified otherwise, the filters have no internal parameters):

Filters as Independent Channels

When some peculiar requirement or Tcl's idiosyncracies make it inconvenient or impossible to implement some filters using plug-in channels, one can obtain the desired functionality by creating a standalone filter channel. We provide two such examples:

identity: This channel reproduces the functionality of the identity plug-in filter. It is provided as a skeleton that can be modified to implement more complex filters. This channel does not accept any non-standard options. Note: do not confuse the identity (standalone) filter channel with the identity filter function.

packoff: This filter identifies packets generated by the packon plug-in filter (see above) and separates them from the input stream, returning them separately. Since this operation makes sense only when reading data, this channel is not writable. This channel does not accept any non-standard options.

Properties of the Provided In-Built Filter Functions

Plug1to2(Plug2to1(X)) = X. 

Plug2to1(Plug1to2(X)) = X. 

xor(xor(X,Y),Y) = X.

packon(packoff(X)) = packoff(packon(X)).

uudecode(uuencode(X)) = X.

hexin(hexout(X)) = X

hexout(hexin(X)) = X

hexin(hexout(X)) != hexout(hexin(X))

Order of Operations

When flushing or closing a sequence of channels linked through filters, one should follow the flow of data. 

Example: filter1-->filter2-->TCP_channel 

When closing this composite channel the sequence of operations should be 

close $filter1
close $filter2
close $tcp_channel

Configuration of Filter Channels 

The subordinated channel and the input and output filter functions of a filter channel can not be changed.

The peek option is forwarded to the subordinated channel, but it does not act on the filter channel itself. 

There are two options, -inset and -outset, that can be used to transmit arguments to the input and output filter functions, respectively. The argument of -inset and -outset is a string that will be passed to the corresponding filter function "as is". It is the responsability of the filter function to interpret the string. 

If the user wishes to change an option for the subordinated channel, this must be done directly. 

A filter channel will always be non-blocking. Seek is not allowed. A plug-in filter channel will always be both readable and writeable, but the real behavior will depend on the characteristics of the internal buffering of filter functions, and on the behavior of the subordinated channel. 

Note: though tcl itself can not handle binary data, the plug-in filters can. Care must be taken to set the -translation option to binary for the appropriate channels.

Composition of Filters

Both plug-in and independent channel filters can be composed with no restrictions.

Examples 

dp_connect plugfilter -channel tcp1 -infilter plug2to1 -outfilter plug1to2

dp_connect plugfilter -channel email0 -outfilter pgp -infilter un_pgp

set xout [dp_connect plugfilter -channel file540 -outfilter uuencode
fconfigure $xout -translation binary
set xxout [dp_connect plugfilter -channel $xout -outfilter xor]
fconfigure $xxout -translation binary -outset "my secret string goes here"

set xin [dp_connect plugfilter -channel file100 -infilter tclfilter]
fconfigure $xin -inset MyTclProcedure

dp_connect packoff -channel tcp10

For more details, please refer to the tests/plugin2.test file in the standard distribution.