The read filter method is called when input data is required. Filters that modify or consume incoming data should implement the read filter method.
Upon receiving control, a read implementation should fill buf with up to amount bytes of input data. This data can be obtained by calling the net_read() function, as shown in the example below.
int read(FilterLayer *layer, void *buf, int amount, int timeout);
The number of bytes placed in buf on success. 0 if no data is available, or a negative value if an error occurs.
FilterLayer *layer is the filter layer in which the filter is installed.
void *buf is the buffer in which data should be placed.
int amount is the maximum number of bytes that should be placed in the buffer.
int timeout is the number of seconds to allow the read operation to return. The purpose of timeout is to limit the amount of time devoted to waiting until some data arrives, not to return because not enough bytes were read in the given time.
int myfilter_read(FilterLayer *layer, void *buf, int amount, int timeout) { return net_read(layer->lower, buf, amount, timeout); }
net_read() Function, filter_create() Function
The REALLOC macro is a platform-independent substitute for the C library routine realloc. This macro changes the size of a specified memory block that was originally created by MALLOC, CALLOC, or STRDUP. The contents of the object remains unchanged up to the lesser of the old and new sizes. If the new size is larger, the new space is uninitialized.
Calling REALLOC for a block that was allocated with PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP will not work.
void *REALLOC(void *ptr, int size);
A pointer to the new space if the request is satisfied.
void *ptr is a (void *) pointer to a block of memory. If the pointer is not the one created by MALLOC, CALLOC, or STRDUP, the behavior is undefined.
int size is the number of bytes to allocate.
char *name; name = (char *) MALLOC(256); if (NotBigEnough()) name = (char *) REALLOC(name, 512);
CALLOC() Macro, MALLOC() Macro, FREE() Macro, STRDUP() Macro, PERM_REALLOC() Macro
The remove filter method is called when the filter stack is destroyed, or when a filter is removed from a filter stack by the filter_remove function or remove-filter SAF.
Waiting until the remove method is invoked might be too late to flush buffered data. For this reason, filters that buffer outgoing data should implement the flush filter method.
void remove(FilterLayer *layer);
void
FilterLayer *layer is the filter layer in which the filter is installed.
flush() Function, filter_remove() Function, filter_create() Function
The request_get_vs function finds the VirtualServer* to which a request is directed.
The returned VirtualServer* is valid only for the current request. To retrieve a virtual server ID that is valid across requests, use vs_get_id().
const VirtualServer* request_get_vs(Request* rq);
The VirtualServer* to which the request is directed.
Request *rq is the request for which the VirtualServer* is returned.
The request_header function finds an entry in the pblock containing the client’s HTTP request headers (rq->headers). You must use this function rather than pblock_findval when accessing the client headers, because the server might begin processing the request before the headers have been completely read.
int request_header(char *name, char **value, Session *sn, Request *rq);
A result code, REQ_PROCEED if the header was found, REQ_ABORTED if the header was not found, or REQ_EXIT if there was an error reading from the client.
char *name is the name of the header.
char **value is the address where the function will place the value of the specified header. If no address is found, the function stores a NULL.
Session *sn is the session.
Request *rq is the request.
The Session and Request parameters are the same parameters as the ones passed into your SAF.
request_create, request_free
The request_stat_path function returns the file information structure for a specified path or, if no path is specified, the path entry in the vars pblock in the specified request structure. If the resulting file name points to a file that the server can read, request_stat_path returns a new file information structure. This structure contains information about the size of the file, its owner, when it was created, and when it was last modified.
Use request_stat_path to retrieve information on the file you are currently accessing instead of calling stat directly, because this function keeps track of previous calls for the same path and returns its cached information.
struct stat *request_stat_path(char *path, Request *rq);
Returns a pointer to the file information structure for the file named by the path parameter. Do not free this structure. Returns NULL if the file is not valid or the server cannot read it. In this case, it also leaves an error message describing the problem in rq->staterr.
char *path is the string containing the name of the path. If the value of path is NULL, the function uses the path entry in the vars pblock in the request structure denoted by rq.
Request *rq is the request identifier for a Server Application Function call.
fi = request_stat_path(path, rq);
request_create, request_free, request_header() Function
The request_translate_uri function performs virtual-to-physical mapping on a specified URI during a specified session. Use this function to determine the file to be sent back if a given URI is accessed.
char *request_translate_uri(char *uri, Session *sn);
A path string if the function performed the mapping, or NULL if it could not perform the mapping.
char *uri is the name of the URI.
Session *sn is the Session parameter that is passed into the SAF.
request_create, request_free, request_header() Function