filter_create() Function (Sun Java System Web Server 7.0 Update 7 NSAPI Developer's Guide)

Sun Java System Web Server 7.0 Update 7 NSAPI Developer's Guide

`filter_create()` Function

The filter_create function defines a new filter.

The name parameter specifies a unique name for the filter. If a filter with the specified name already exists, it will be replaced.

Names beginning with magnus- or server- are reserved by the server.

The order parameter indicates the position of the filter in the filter stack by specifying what class of functionality the filter implements.

The following table describes parameters allowed constants and their associated meanings for the filter_create function. The left column lists the name of the constant, the middle column describes the functionality the filter implements, and the right column lists the position the filter occupies in the filter stack.

Table 6–1 filter-create() Constants


Constant	Functionality Filter Implements	Position in Filter Stack
`FILTER_CONTENT_TRANSLATION`	Translates content from one form to another, for example, XSLT	Top
`FILTER_CONTENT_CODING`	Encodes content, for example, HTTP `gzip` compression	Middle
`FILTER_TRANSFER_CODING`	Encodes entity bodies for transmission, for example, HTTP chunking	Bottom

The methods parameter specifies a pointer to a FilterMethods structure. Before calling filter_create, you must initialize the FilterMethods structure using the FILTER_METHODS_INITIALIZER macro, and then assign function pointers to the individual FilterMethods members (for example, insert, read, write, and so on) that correspond to the filter methods the filter supports.

filter_create returns const Filter *, a pointer to an opaque representation of the filter. This value can be passed to filter_insert to insert the filter in a particular filter stack.

Syntax

const Filter *filter_create(const char *name, int order, 
                            const FilterMethods *methods);

Return Values

The const Filter * that identifies the filter, or NULL if an error occurs.

Parameters

const char *name is the name of the filter.

int order is one of the order constants listed in Table Table 6–1.

const FilterMethods *methods contains pointers to the filter methods the filter supports.

Example

FilterMethods methods = FILTER_METHODS_INITIALIZER;
const Filter *filter;
/* This filter will only support the "read" filter method */
methods.read = my_input_filter_read;
/* Create the filter */
filter = filter_create("my-input-filter", FILTER_CONTENT_TRANSLATION,
                        &methods);