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 cannot 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 parameter is obtained from the csd, client socket descriptor field of the sn or the session structure.
if (filebuf_buf2sd(buf, sn->csd) == IO_ERROR) return(REQ_EXIT);
filebuf_close() Function, filebuf_open() Function, filebuf_open_nostat() Function, filebuf_getc() Function
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() Function, filebuf_open_nostat() Function, filebuf_buf2sd() Function, filebuf_getc() Function
The filebuf_getc function retrieves a character from the current file position and returns the character as an integer. The function 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 an error.
filebuf b is the name of the file buffer.
filebuf_close() Function, filebuf_buf2sd() Function, filebuf_open() Function, filter_create() Function
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 can 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.
filebuf *buf = filebuf_open(fd, FILE_BUFFERSIZE); if (!buf) { system_fclose(fd); }
filebuf_getc() Function, filebuf_buf2sd() Function, filebuf_close() Function, filebuf_open_nostat() Function
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 as filebuf_open, but is more efficient, because it does not need to call the request_stat_path function. This function 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 can 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() Function, filebuf_open() Function, filebuf_getc() Function, filebuf_buf2sd() Function
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 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 6–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 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 supports.
filter_create returns const Filter *, a pointer to an opaque representation of the filter. This value can 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 occurs.
const char *name is the name of the filter.
int order is one of the order constants listed in Table Table 6–1.
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);
filter_insert() Function, insert() Function, flush() Function, read() Function, sendfile() Function, write() Function, writev() Function, FilterMethods Data Structure
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 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 are 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.
int filter_insert(SYS_NETFD sd, pblock *pb, Session *sn, Request *rq, void *data, const Filter *filter);
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, and is 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 the top filter layer of the filter is destroyed.
When possible, plug-in developers should avoid calling filter_remove directly, and instead use the remove-filter() SAF. this recommendation is applicable in Input-, Output-, Service-, and Error-class directives.
int filter_remove(SYS_NETFD sd, const Filter *filter);
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 occurs.
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); }
net_flush() Function, filter_create() Function
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.
Calling FREE for a block that was allocated with PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP will not work.
FREE(void *ptr);
void
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.
char *name; name = (char *) MALLOC(256); ... ... FREE(name);
CALLOC() Macro, MALLOC() Macro, REALLOC() Macro, STRDUP() Macro, PERM_FREE() Macro
The func_exec function executes the function named by the fn entry in a specified pblock. If the function name is not found, func_exec logs the error and returns REQ_ABORTED.
You can use this function to execute a built-in Server Application Function (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 if successful. REQ_ABORTED, if no function is 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 parameters as the ones passed into the custom SAF.
The func_find function returns a pointer to the function specified by name. If the function does not exist, func_find returns NULL.
FuncPtr func_find(char *name);
A pointer to the chosen function, suitable for de-referencing, or NULL if the function is not 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);
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);