Filter Methods

This section describes the filter methods that a filter can implement. To create a filter, a filter developer implements one or more of these methods.

This section describes the following filter methods:

• insert()

• remove()

• flush()

• read()

• write()

• writev()

• sendfile()

For more information about these methods, see Chapter 6, NSAPI Function and Macro Reference.

C Prototypes for Filter Methods

The C prototypes for the filter methods are:

int insert(FilterLayer *layer, pblock *pb);
void remove(FilterLayer *layer);
int flush(FilterLayer *layer);
int read(FilterLayer *layer, void *buf, int amount, int timeout);
int write(FilterLayer *layer, const void *buf, int amount);
int writev(FilterLayer *layer, const struct iovec *iov, int iov_size);
int sendfile(FilterLayer *layer, sendfiledata *sfd);

The layer parameter is a pointer to a FilterLayer data structure, which contains variables related to a particular instance of a filter.

The most important fields in the FilterLayer data structure are:

• context->sn: Contains information relating to a single TCP/IP session (the same sn pointer that’s passed to SAFs).

• context->rq: Contains information relating to the current request (the same rq pointer that’s passed to SAFs).

• context->data: Pointer to filter-specific data.

• lower: A platform-independent socket descriptor used to communicate with the next filter in the stack.

The meaning of the context->data field is defined by the filter developer. Filters that must maintain state information across filter method calls can use context->data to store that information.

For more information about FilterLayer, see FilterLayer Data Structure.

insert Filter Method

The insert filter method is called when an SAF such as insert-filter calls the filter_insert function to request that a specific filter be inserted into the filter stack. Each filter must implement the insert filter method.

When insert is called, the filter can determine whether it should be inserted into the filter stack. For example, the filter could inspect the content-type header in the rq->srvhdrs pblock to determine whether it is interested in the type of data that will be transmitted. If the filter should not be inserted, the insert filter method should indicate this by returning REQ_NOACTION.

If the filter should be inserted, the insert filter method provides an opportunity to initialize this particular instance of the filter. For example, the insert method could allocate a buffer with MALLOC and store a pointer to that buffer in layer->context->data.

The filter is not part of the filter stack until after insert returns. As a result, the insert method should not attempt to read from, write to, or otherwise interact with the filter stack.

For more information, see insert() Function in Chapter 6, NSAPI Function and Macro Reference.

remove Filter Method

The remove filter method is called when a filter stack is destroyed (that is, when the corresponding socket descriptor is closed), when the server finishes processing the request the filter was associated with, or when an SAF such as remove-filter calls the filter_remove function. The remove filter method is optional.

The remove method can be used to clean up any data the filter allocated in insert and to pass any buffered data to the next filter by calling net_write(layer->lower, ...).

For more information, see remove() Function in Chapter 6, NSAPI Function and Macro Reference.

flush Filter Method

The flush filter method is called when a filter or SAF calls the net_flush function. The flush method should pass any buffered data to the next filter by calling net_write(layer->lower, ...). The flush method is optional, but it should be implemented by any filter that buffers outgoing data.

For more information, see flush() Function in Chapter 6, NSAPI Function and Macro Reference.

read Filter Method

The read filter method is called when a filter or SAF calls the net_read function. Filters that are interested in incoming data, that is, data sent from a client to the server implement the read filter method.

Typically, the read method will attempt to obtain data from the next filter by calling net_read(layer->lower, ...). The read method may then modify the received data before returning it to its caller.

For more information, see read() Function in Chapter 6, NSAPI Function and Macro Reference.

write Filter Method

The write filter method is called when a filter or SAF calls the net_write function. Filters that are interested in outgoing data, that is, data sent from the server to a client implement the write filter method.

Typically, the write method will pass data to the next filter by calling net_write(layer->lower, ...). The write method may modify the data before calling net_write. For example, the http-compression filter compresses data before passing it on to the next filter.

If a filter implements the write filter method but does not pass the data to the next layer before returning to its caller, that is, if the filter buffers outgoing data, the filter should also implement the flush method.

For more information, see write() Function in Chapter 6, NSAPI Function and Macro Reference.

sendfile Filter Method

The sendfile filter method performs a function similar to the writev filter method, but it sends a file directly instead of first copying the contents of the file into a buffer. You do not have to implement the sendfile filter method. If a filter implements the write filter method but not the sendfile filter method, the server will use the write method instead of the sendfile method. A filter should not implement the sendfile method unless it also implements the write method.

Under some circumstances, the server might run slightly faster when filters that implement the write filter method also implement the sendfile filter method.

For more information, see sendfile() Function in Chapter 6, NSAPI Function and Macro Reference

writev Filter Method

The writev filter method performs the same function as the write filter method, but the format of its parameters is different. It is not necessary to implement the writev filter method; if a filter implements the write filter method but not the writev filter method, the server uses the write method instead of the writev method. A filter should not implement the writev method unless it also implements the write method.

Under some circumstances, the server may run slightly faster when filters that implement the write filter method also implement the writev filter method.

For more information, see writev() Function in Chapter 6, NSAPI Function and Macro Reference