Filter Methods

This section describes the filter methods that a filter can implement, which are:

• insert

• remove

• flush

• read

• write

• writev

• sendfile

For more information about these methods, see Chapter 4, NSAPI Function 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. Following is a list of the most important fields in the FilterLayer data structure:

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

• context->rq — Contains information relating to the current request. This pointer is the same rq pointer that is 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.

insert

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, this method can determine whether the filter 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 the type of data that will be transmitted is relevant. If the filter should not be inserted, the insert filter method should return 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.

See Also

insert in Chapter 4, NSAPI Function Reference

remove

The remove filter method is called when a filter stack is destroyed 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, ...).

See Also

remove in Chapter 4, NSAPI Function Reference

flush

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.

See Also

flush in Chapter 4, NSAPI Function Reference

read

The read filter method is called when a filter or SAF calls the net_read function. Filters that deal with in incoming data (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.

See Also

read in Chapter 4, NSAPI Function Reference

write

The write filter method is called when a filter or SAF calls the net_write function. Filters that are deal with outgoing data (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.

See Also

write in Chapter 4, NSAPI Function Reference

writev

The writev filter method performs the same function as the write filter method, but the format of its parameters is different. You do not have 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.

See Also

writev in Chapter 4, NSAPI Function Reference

sendfile

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 may run slightly faster when filters that implement the write filter method also implement the sendfile filter method.

See Also

sendfile in Chapter 4, NSAPI Function Reference