Sun Java System Web Server 7.0 Update 3 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


Functionality Filter Implements  

Position in Filter Stack  


Translates content from one form to another, for example, XSLT 



Encodes content, for example, HTTP gzip compression



Encodes entity bodies for transmission, for example, HTTP chunking 


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.


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.


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.


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

See Also

filter_insert() Function, insert() Function, flush() Function, read() Function, sendfile() Function, write() Function, writev() Function, FilterMethods Data Structure