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.
PRFileDesc *fc_open(const char *fileName, FcHdl *hDl, PRUint32 flags, Session *sn, Request *rq);
Pointer to PRFileDesc, or NULL on failure.
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.
The fc_close function closes a file opened using fc_open. This function should only be called with files opened using fc_open.
void fc_close(PRFileDesc *fd, FcHdl *hDl);
void
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.
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.
int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);
The number of bytes sent to the socket if successful, or the constant IO_ERROR if the file buffer could not be sent.
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.
if (filebuf_buf2sd(buf, sn->csd) == IO_ERROR) return(REQ_EXIT);
filebuf_close, filebuf_open, filebuf_open_nostat, filebuf_getc
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.
void filebuf_close(filebuf *buf);
void
filebuf *buf is the file buffer previously opened with filebuf_open.
filebuf_close(buf);
filebuf_open, filebuf_open_nostat, filebuf_buf2sd, 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.
filebuf_getc(filebuf b);
An integer containing the character retrieved, or the constant IO_EOF or IO_ERROR upon an end of file or error.
filebuf b is the name of the file buffer.
filebuf_close, filebuf_buf2sd, filebuf_open, filter_create
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.
filebuf *filebuf_open(SYS_FILE fd, int sz);
A pointer to a new buffer structure to hold the data if successful, or NULL if no buffer could be opened.
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.
filebuf *buf = filebuf_open(fd, FILE_BUFFERSIZE);if (!buf) { system_fclose(fd);}
filebuf_getc, filebuf_buf2sd, filebuf_close, 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.
filebuf* filebuf_open_nostat(SYS_FILE fd, int sz, struct stat *finfo);
A pointer to a new buffer structure to hold the data if successful, or NULL if no buffer could be opened.
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.
filebuf *buf = filebuf_open_nostat(fd, FILE_BUFFERSIZE, &finfo); if (!buf) { system_fclose(fd); }
filebuf_close, filebuf_open, filebuf_getc, filebuf_buf2sd
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.
const Filter *filter_create(const char *name, int order, const FilterMethods *methods);
The const Filter * that identifies the filter or NULL if an error occurred.
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.
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);
The filter_find function finds the filter with the specified name.
const Filter *filter_find(const char *name);
The const Filter * that identifies the filter, or NULL if the specified filter does not exist.
const char *name is the name of the filter of interest.
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).
int filter_insert(SYS_NETFD sd, pblock *pb, Session *sn, Request *rq, void *data, const Filter *filter);
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.
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.
The filter_layer function returns the layer in a filter stack that corresponds to the specified filter.
FilterLayer *filter_layer(SYS_NETFD sd, const Filter *filter);
The topmost FilterLayer * associated with the specified filter, or NULL if the specified filter is not part of the specified filter stack.
SYS_NETFD sd is the filter stack to inspect.
const Filter *filter is the filter of interest.
The filter_name function returns the name of the specified filter. The caller should not free the returned string.
const char *filter_name(const Filter *filter);
The name of the specified filter, or NULL if an error occurred.
const Filter *filter is the filter of interest.
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).
int filter_remove(SYS_NETFD sd, const Filter *filter);
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.
SYS_NETFD sd is the filter stack, sn->csd.
const Filter *filter is the filter to remove.
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).
int flush(FilterLayer *layer);
0 on success or -1 if an error occurred.
FilterLayer *layer is the filter layer the filter is installed in.
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); }
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.
FREE(void *ptr);
void
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.
char *name;name = (char *) MALLOC(256);...FREE(name);
CALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_FREE, PERM_REALLOC, PERM_STRDUP
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.
int func_exec(pblock *pb, Session *sn, Request *rq);
The value returned by the executed function, or the constant REQ_ABORTED if no function was executed.
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.
The func_find function returns a pointer to the function specified by name. If the function does not exist, it returns NULL.
FuncPtr func_find(char *name);
A pointer to the chosen function, suitable for dereferencing, or NULL if the function could not be found.
char *name is the name of the function.
/* 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);
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.
FuncStruct *func_insert(char *name, FuncPtr fn);
Returns the FuncStruct structure that identifies the newly inserted function. The caller should not modify the contents of the FuncStruct structure.
char *name is the name of the function.
FuncPtr fn is the pointer to the function.
func_insert("my-service-saf", &my_service_saf);