F

fc_open

The fc_open function returns a pointer to PRFileDesc that refers to an open file (fileName). The fileName must be the full path name of an existing file. The file is opened in read-only mode. The application calling this function should not modify the currency of the file pointed to by the PRFileDesc * unless the DUP_FILE_DESC is also passed to this function. In other words, the application (at minimum) should not issue a read operation based on this pointer that would modify the currency for the PRFileDesc *. If such a read operation is required (that may change the currency for the PRFileDesc * ), then the application should call this function with the argument DUP_FILE_DESC.

On a successful call to this function, a valid pointer to PRFileDesc is returned and the handle 'FcHdl'is properly initialized. The size information for the file is stored in the 'fileSize' member of the handle.

Syntax

PRFileDesc *fc_open(const char *fileName, 
FcHdl *hDl, PRUint32 flags, Session *sn, Request *rq);

Returns

Pointer to PRFileDesc, or NULL on failure.

Parameters

const char *fileName is the full path name of the file to be opened.

FcHdl*hDl is a valid pointer to a structure of type FcHdl.

PRUint32 flags can be 0 or DUP_FILE_DESC.

Session *sn is a pointer to the session.

Request *rq is a pointer to the request.

fc_close

The fc_close function closes a file opened using fc_open. This function should only be called with files opened using fc_open.

Syntax

void fc_close(PRFileDesc *fd, FcHdl *hDl);

Returns

void

Parameters

PRFileDesc *fd is a valid pointer returned from a prior call to fc_open.

FcHdl *hDl is a valid pointer to a structure of type FcHdl. This pointer must have been initialized by a prior call to fc_open.

filebuf_buf2sd

The filebuf_buf2sd function sends a file buffer to a socket (descriptor) and returns the number of bytes sent.

Use this function to send the contents of an entire file to the client.

Syntax

int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);

Returns

The number of bytes sent to the socket if successful, or the constant IO_ERROR if the file buffer could not be sent.

Parameters

filebuf *buf is the file buffer that must already have been opened.

SYS_NETFD sd is the platform-independent socket descriptor. Normally this will be obtained from the csd (client socket descriptor) field of the sn (session) structure.

Example

if (filebuf_buf2sd(buf, sn->csd) == IO_ERROR)    return(REQ_EXIT);

See Also

filebuf_close, filebuf_open, filebuf_open_nostat, filebuf_getc

filebuf_close

The filebuf_close function deallocates a file buffer and closes its associated file.

Generally, use filebuf_open first to open a file buffer, and then filebuf_getc to access the information in the file. After you have finished using the file buffer, use filebuf_close to close it.

Syntax

void filebuf_close(filebuf *buf);

Returns

void

Parameters

filebuf *buf is the file buffer previously opened with filebuf_open.

Example

filebuf_close(buf);

See Also

filebuf_open, filebuf_open_nostat, filebuf_buf2sd, filebuf_getc

filebuf_getc

The filebuf_getc function retrieves a character from the current file position and returns it as an integer. It then increments the current file position.

Use filebuf_getc to sequentially read characters from a buffered file.

Syntax

filebuf_getc(filebuf b);

Returns

An integer containing the character retrieved, or the constant IO_EOF or IO_ERROR upon an end of file or error.

Parameters

filebuf b is the name of the file buffer.

See Also

filebuf_close, filebuf_buf2sd, filebuf_open, filter_create

filebuf_open

The filebuf_open function opens a new file buffer for a previously opened file. It returns a new buffer structure. Buffered files provide more efficient file access by guaranteeing the use of buffered file I/O in environments where it is not supported by the operating system.

Syntax

filebuf *filebuf_open(SYS_FILE fd, int sz);

Returns

A pointer to a new buffer structure to hold the data if successful, or NULL if no buffer could be opened.

Parameters

SYS_FILE fd is the platform-independent file descriptor of the file which has already been opened.

int sz is the size, in bytes, to be used for the buffer.

Example

filebuf *buf = filebuf_open(fd, FILE_BUFFERSIZE);if (!buf) {    system_fclose(fd);}

See Also

filebuf_getc, filebuf_buf2sd, filebuf_close, filebuf_open_nostat

filebuf_open_nostat

The filebuf_open_nostat function opens a new file buffer for a previously opened file. It returns a new buffer structure. Buffered files provide more efficient file access by guaranteeing the use of buffered file I/O in environments where it is not supported by the operating system.

This function is the same filebuf_open, but is more efficient, since it does not need to call the request_stat_path function. It requires that the stat information be passed in.

Syntax

filebuf* filebuf_open_nostat(SYS_FILE fd, int sz,     struct stat *finfo);

Returns

A pointer to a new buffer structure to hold the data if successful, or NULL if no buffer could be opened.

Parameters

SYS_FILE fd is the platform-independent file descriptor of the file that has already been opened.

int sz is the size, in bytes, to be used for the buffer.

struct stat *finfo is the file information of the file. Before calling the filebuf_open_nostat function, you must call the request_stat_path function to retrieve the file information.

Example

filebuf *buf = filebuf_open_nostat(fd, FILE_BUFFERSIZE, &finfo);
if (!buf) {
    system_fclose(fd);
}

See Also

filebuf_close, filebuf_open, filebuf_getc, filebuf_buf2sd

filter_create

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 order 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 7–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 first 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 will support.

filter_create returns const Filter *, a pointer to an opaque representation of the filter. This value may 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);

Returns

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

Parameters

const char *name is the name of the filter.

int order is one of the order constants above.

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);

filter_find

The filter_find function finds the filter with the specified name.

Syntax

const Filter *filter_find(const char *name);

Returns

The const Filter * that identifies the filter, or NULL if the specified filter does not exist.

Parameters

const char *name is the name of the filter of interest.

filter_insert

The filter_insert function inserts a filter into a filter stack, creating a new filter layer and installing the filter at that layer. The filter layer's position in the stack is determined by the order value specified when filter_create was called, and any explicit ordering configured by init-filter-order. If a filter layer with the same order value already exists in the stack, the new layer is inserted above that layer.

Parameters may be passed to the filter using the pb and data parameters. The semantics of the data parameter are defined by individual filters. However, all filters must be able to handle a data parameter of NULL.

When possible, plug-in developers should avoid calling filter_insert directly, and instead use the insert-filter SAF (applicable in Input-class directives).

Syntax

int filter_insert(SYS_NETFD sd, pblock *pb, Session *sn, Request 
*rq, void *data, const Filter *filter);

Returns

Returns REQ_PROCEED if the specified filter was inserted successfully, or REQ_NOACTION if the specified filter was not inserted because it was not required. Any other return value indicates an error.

Parameters

SYS_NETFD sd is NULL (reserved for future use).

pblock *pb is a set of parameters to pass to the specified filter's init method.

Session *sn is the Session.

Request *rq is the Request.

void *data is filter-defined private data.

const Filter *filter is the filter to insert.

filter_layer

The filter_layer function returns the layer in a filter stack that corresponds to the specified filter.

Syntax

FilterLayer *filter_layer(SYS_NETFD sd, const Filter *filter);

Returns

The topmost FilterLayer * associated with the specified filter, or NULL if the specified filter is not part of the specified filter stack.

Parameters

SYS_NETFD sd is the filter stack to inspect.

const Filter *filter is the filter of interest.

filter_name

The filter_name function returns the name of the specified filter. The caller should not free the returned string.

Syntax

const char *filter_name(const Filter *filter);

Returns

The name of the specified filter, or NULL if an error occurred.

Parameters

const Filter *filter is the filter of interest.

filter_remove

The filter_remove function removes the specified filter from the specified filter stack, destroying a filter layer. If the specified filter was inserted into the filter stack multiple times, only that filter's topmost filter layer is destroyed.

When possible, plug-in developers should avoid calling filter_remove directly, and instead use the remove-filter SAF (applicable in Input-, Output-, Service-, and Error-class directives).

Syntax

int filter_remove(SYS_NETFD sd, const Filter *filter);

Returns

Returns REQ_PROCEED if the specified filter was removed successfully or REQ_NOACTION if the specified filter was not part of the filter stack. Any other return value indicates an error.

Parameters

SYS_NETFD sd is the filter stack, sn->csd.

const Filter *filter is the filter to remove.

flush

The flush filter method is called when buffered data should be sent. Filters that buffer outgoing data should implement the flush filter method.

Upon receiving control, a flush implementation must write any buffered data to the filter layer immediately below it. Before returning success, a flush implementation must successfully call the net_flush function:

net_flush(layer->lower).

Syntax

int flush(FilterLayer *layer);

Returns

0 on success or -1 if an error occurred.

Parameters

FilterLayer *layer is the filter layer the filter is installed in.

Example

int myfilter_flush(FilterLayer *layer)
{
    MyFilterContext context = (MyFilterContext *)layer->context->data;
    if (context->buf.count) {
       int rv;
       rv = net_write(layer->lower, context->buf.data, context->buf.count);
       if (rv != context->buf.count)
           return -1; /* failed to flush data */
       context->buf.count = 0;
    }
    return net_flush(layer->lower);
}

See Also

net_flush

FREE

The FREE macro is a platform-independent substitute for the C library routine free. It deallocates the space previously allocated by MALLOC, CALLOC, or STRDUP from the request’s memory pool.

Syntax

FREE(void *ptr);

Returns

void

Parameters

void *ptr is a (void *) pointer to a block of memory. If the pointer is not one created by MALLOC, CALLOC, or STRDUP, the behavior is undefined.

Example

char *name;name = (char *) MALLOC(256);...FREE(name);

See Also

CALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_FREE, PERM_REALLOC, PERM_STRDUP

func_exec

The func_exec function executes the function named by the fn entry in a specified pblock. If the function name is not found, it logs the error and returns REQ_ABORTED.

You can use this function to execute a built-in SAF by identifying it in the pblock.

Syntax

int func_exec(pblock *pb, Session *sn, Request *rq);

Returns

The value returned by the executed function, or the constant REQ_ABORTED if no function was executed.

Parameters

pblock pb is the pblock containing the function name (fn) and parameters.

Session *sn is the Session.

Request *rq is the Request.

The Session and Request parameters are the same as the ones passed into your SAF.

See Also

log_error

func_find

The func_find function returns a pointer to the function specified by name. If the function does not exist, it returns NULL.

Syntax

FuncPtr func_find(char *name);

Returns

A pointer to the chosen function, suitable for dereferencing, or NULL if the function could not be found.

Parameters

char *name is the name of the function.

Example

/* this block of code does the same thing as func_exec */char 
*afunc = pblock_findval("afunction", pb);FuncPtr afnptr = func_find(afunc);
if (afnptr)     return (afnptr)(pb, sn, rq);

See Also

func_exec

func_insert

The func_insert function dynamically inserts a named function into the server's table of functions. This function should only be called during the Init stage.

Syntax

FuncStruct *func_insert(char *name, FuncPtr fn);

Returns

Returns the FuncStruct structure that identifies the newly inserted function. The caller should not modify the contents of the FuncStruct structure.

Parameters

char *name is the name of the function.

FuncPtr fn is the pointer to the function.

Example

func_insert("my-service-saf", &my_service_saf);

See Also

func_exec, func_find