The param_create function creates a pb_param structure containing a specified name and value. The name and value are copied. Use this function to prepare a pb_param structure to be used in calls to pblock routines such as pblock_pinsert.
pb_param *param_create(char *name, char *value);
A pointer to a new pb_param structure.
char *name is the string containing the name.
char *value is the string containing the value.
pb_param *newpp = param_create("content-type","text/plain"); pblock_pinsert(newpp, rq->srvhdrs);
param_free() Function, pblock_pinsert() Function, pblock_remove() Function
The param_free function frees the pb_param structure specified by pp and its associated structures. Use the param_free function to dispose a pb_param after removing it from a pblock with pblock_remove.
int param_free(pb_param *pp);
1 if the parameter is freed or 0 if the parameter is NULL.
pb_param *pp is the name-value pair stored in a pblock.
if (param_free(pblock_remove("content-type", rq-srvhdrs))) return; /* we removed it */
param_create() Function, pblock_pinsert() Function, pblock_remove() Function
The pblock_copy function copies the entries of the source pblock and adds them into the destination pblock. Any previous entries in the destination pblock are left intact.
void pblock_copy(pblock *src, pblock *dst);
void
pblock *src is the source pblock.
pblock *dst is the destination pblock.
Names and values are newly allocated so that the original pblock may be freed, or the new pblock changed without affecting the original pblock.
pblock_create() Function, pblock_dup() Function, pblock_free() Function, pblock_find() Function, pblock_findval() Function, pblock_remove() Function, pblock_nvinsert() Function
The pblock_create function creates a new pblock. The pblock maintains an internal hash table for fast name-value pair lookups. Because the pblock is allocated from the request's memory pool, it should not be shared between threads.
pblock *pblock_create(int n);
A pointer to a newly allocated pblock.
int n is the size of the hash table (the number of name-value pairs) for the pblock.
pblock_copy() Function, pblock_dup() Function, pblock_find() Function, pblock_findval() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function
The pblock_dup function duplicates a pblock. This function is equivalent to a sequence of pblock_create and pblock_copy functions.
pblock *pblock_dup(pblock *src);
A pointer to a newly allocated pblock.
pblock *src is the source pblock.
pblock_create() Function, pblock_find() Function, pblock_findval() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function
The pblock_find macro finds a specified name-value pair entry in a pblock, and returns the pb_param structure. If you only want to find the value associated with the name, use the pblock_findval function.
Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.
pb_param *pblock_find(char *name, pblock *pb);
A pointer to the pb_param structure if found, or NULL if the name is not found.
char *name is the name of a name-value pair.
pblock *pb is the pblock to be searched.
pblock_copy() Function, pblock_dup() Function, pblock_findval() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function
The pblock_findval function finds the value associated with a specified name in a pblock. If you want to find the pb_param structure of the pblock, use the pblock_find function.
The pointer returned is a pointer into the pblock. Do not free it. If you want to modify the pointer, do a STRDUP and modify the copy.
Parameter names are case-sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.
char *pblock_findval(char *name, pblock *pb);
A string containing the value associated with the name if found, or NULL if no match is found.
char *name is the name of a name-value pair.
pblock *pb is the pblock to be searched.
pblock_create() Function, pblock_copy() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function, request_header() Function
The pblock_free function frees a specified pblock and any entries inside it. If you want to save a variable in the pblock, remove the variable using the function pblock_remove and save the resulting pointer.
void pblock_free(pblock *pb);
void
pblock *pb is the pblock to be freed.
pblock_copy() Function, pblock_create() Function, pblock_dup() Function, pblock_find() Function, pblock_findval() Function, pblock_nvinsert() Function, pblock_remove() Function
The pblock_nninsert function creates a new entry with a given name and a numeric value in the specified pblock. The numeric value is first converted into a string. The name and value parameters are copied.
Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.
pb_param *pblock_nninsert(char *name, int value, pblock *pb);
A pointer to the new pb_param structure.
char *name is the name of the new entry.
int value is the numeric value being inserted into the pblock. This parameter must be an integer. If you want to assign a non-numerical value, then use the function pblock_nvinsert to create the parameter.
pblock *pb is the pblock into which the insertion occurs.
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function, pblock_str2pblock() Function
The pblock_nvinsert function creates a new entry with a given name and character value in the specified pblock. The name and value parameters are copied.
Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.
pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);
A pointer to the newly allocated pb_param structure.
char *name is the name of the new entry.
char *value is the string value of the new entry.
pblock *pb is the pblock into which the insertion occurs.
pblock_nvinsert("content-type", "text/html", rq->srvhdrs);
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nninsert() Function, pblock_remove() Function, pblock_str2pblock() Function
The pblock_pb2env function copies a specified pblock into a specified environment. The function creates one new environment entry for each name-value pair in the pblock. Use this function to send pblock entries to a program that you are going to execute.
char **pblock_pb2env(pblock *pb, char **env);
A pointer to the environment.
pblock *pb is the pblock to be copied.
char **env is the environment into which the pblock is to be copied.
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function, pblock_str2pblock() Function
The pblock_pblock2str function copies all parameters of a specified pblock into a specified string. The function allocates additional non-heap space for the string if needed.
Use this function to stream the pblock for archival and other purposes.
char *pblock_pblock2str(pblock *pb, char *str);
The new version of the str parameter. If str is NULL, this string is a new string; otherwise, this string is a reallocated string. In either case, this string is allocated from the request’s memory pool.
pblock *pb is the pblock to be copied.
char *str is the string into which the pblock is to be copied. This string must have been allocated by MALLOC or REALLOC, not by PERM_MALLOC or PERM_REALLOC, which allocate from the system heap.
Each name-value pair in the string is separated from its neighbor pair by a space, and is in the format name="value."
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function, pblock_str2pblock() Function
The function pblock_pinsert inserts a pb_param structure into a pblock.
Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.
void pblock_pinsert(pb_param *pp, pblock *pb);
void
pb_param *pp is the pb_param structure to insert.
pblock *pb is the pblock.
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function, pblock_str2pblock() Function
The pblock_remove macro removes a specified name-value entry from a specified pblock. If you use this function, you must call param_free to deallocate the memory used by the pb_param structure.
pb_param *pblock_remove(char *name, pblock *pb);
A pointer to the named pb_param structure if it is found, or NULL if the named pb_param is not found.
char *name is the name of the pb_param to be removed.
pblock *pb is the pblock from which the name-value entry is to be removed.
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, param_create() Function, param_free() Function
The pblock_str2pblock function scans a string for parameter pairs, adds them to a pblock, and returns the number of parameters added.
int pblock_str2pblock(char *str, pblock *pb);
The number of parameter pairs added to the pblock, if any, or -1 if an error occurs.
char *str is the string to be scanned.
The name-value pairs in the string can have the format name=value or name="value."
All backslashes (\) must be followed by a literal character. If string values are found with no unescaped = signs (no name=), the function assumes the names 1, 2, 3, and so on, depending on the string position. For example, if pblock_str2pblock finds "some strings together," the function treats the strings as if they appeared in name-value pairs as 1="some" 2="strings" 3="together."
pblock *pb is the pblock into which the name-value pairs are stored.
pblock_copy() Function, pblock_create() Function, pblock_find() Function, pblock_free() Function, pblock_nvinsert() Function, pblock_remove() Function, pblock_pblock2str() Function
The PERM_CALLOC macro is a platform-independent substitute for the C library routine calloc. This macro allocates size bytes of memory and initializes the memory to zeros. The memory persists after processing the current request has been completed. The memory should be explicitly freed by a call to PERM_FREE.
void *PERM_CALLOC(int size)
A void pointer to a block of memory.
int size is the number of bytes to allocate.
char **name; name = (char **) PERM_CALLOC(100 * sizeof(char *));
CALLOC() Macro, PERM_FREE() Macro, PERM_STRDUP() Macro, PERM_MALLOC() Macro, PERM_REALLOC() Macro
The PERM_FREE macro is a platform-independent substitute for the C library routine free. This macro deallocates the persistent space previously allocated by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP.
Calling PERM_FREE for a block that was allocated with MALLOC, CALLOC, or STRTUP will not work.
PERM_FREE(void *ptr);
void
void *ptr is a (void *) pointer to a block of memory. If the pointer is not the one created by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP, the behavior is undefined.
char *name; name = (char *) PERM_MALLOC(256); ... PERM_FREE(name);
FREE() Macro, PERM_MALLOC() Macro, PERM_CALLOC() Macro, PERM_REALLOC() Macro, PERM_STRDUP() Macro
The PERM_MALLOC macro is a platform-independent substitute for the C library routine malloc. This macro provides allocation of memory that persists after the request that is being processed has been completed.
void *PERM_MALLOC(int size)
A void pointer to a block of memory.
int size is the number of bytes to allocate.
/* Allocate 256 bytes for a name */ char *name; name = (char *) PERM_MALLOC(256);
MALLOC() Macro, PERM_FREE() Macro, PERM_STRDUP() Macro, PERM_CALLOC() Macro, PERM_REALLOC() Macro
The PERM_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 PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP. The content 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 PERM_REALLOC for a block that was allocated with MALLOC, CALLOC, or STRDUP does not work.
void *PERM_REALLOC(vod *ptr, int size)
A void pointer to a block of memory.
void *ptr is a void pointer to a block of memory created by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP.
int size is the number of bytes to which the memory block should be resized.
char *name; name = (char *) PERM_MALLOC(256); if (NotBigEnough()) name = (char *) PERM_REALLOC(name, 512);
REALLOC() Macro, PERM_CALLOC() Macro, PERM_MALLOC() Macro, PERM_FREE() Macro, PERM_STRDUP() Macro
The PERM_STRDUP macro is a platform-independent substitute for the C library routine strdup. This macro creates a new copy of a string in memory that persists after the request that is being processed has been completed. If pooled memory has been disabled in the configuration file with the built-in pool-init SAF PERM_STRDUP and STRDUP both obtain their memory from the system heap.
The PERM_STRDUP routine is functionally equivalent to the following code:
newstr = (char *) PERM_MALLOC(strlen(str) + 1);strcpy(newstr, str); |
A string created with PERM_STRDUP should be disposed with PERM_FREE.
char *PERM_STRDUP(char *ptr);
A pointer to the new string.
char *ptr is a pointer to a string.
PERM_MALLOC() Macro, PERM_FREE() Macro, PERM_CALLOC() Macro, PERM_REALLOC() Macro, MALLOC() Macro, FREE() Macro, STRDUP() Macro, CALLOC() Macro, REALLOC() Macro
The prepare_nsapi_thread function enables threads that are not created by the server to act like server-created threads. This function must be called before any NSAPI functions are called from a thread that is not server-created.
void prepare_nsapi_thread(Request *rq, Session *sn);
void
Request *rq is the request.
Session *sn is the session.
The Request and Session parameters are the same parameter as the ones passed into your SAF.
protocol_start_response() Function
The protocol_dump822 function prints headers from a specified pblock into a specific buffer, with a specified size and position. Use this function to serialize the headers so that they can be sent, for example, in a mail message.
char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);
A pointer to the buffer, which will be reallocated if necessary.
The function also modifies *pos to the end of the headers in the buffer.
pblock *pb is the pblock structure.
char *t is the buffer, allocated with MALLOC, CALLOC, or STRDUP.
int *pos is the position within the buffer at which the headers are to be inserted.
int tsz is the size of the buffer.
protocol_start_response() Function, protocol_status() Function
The protocol_set_finfo function retrieves the content-length and last-modified date from a specified stat structure and adds them to the response headers (rq->srvhdrs). Call protocol_set_finfo before calling protocol_start_response.
int protocol_set_finfo(Session *sn, Request *rq, struct stat *finfo);
The constant REQ_PROCEED if the request can proceed normally, or the constant REQ_ABORTED if the function should treat the request normally but not send any output to the client.
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.
stat *finfo is the stat structure for the file.
The stat structure contains the information about the file from the file system. You can get the stat structure info using request_stat_path.
protocol_start_response() Function, protocol_status() Function
The protocol_start_response function initiates the HTTP response for a specified session and request. If the protocol version is HTTP/0.9, the function does nothing, because that version has no concept of status. If the protocol version is HTTP/1.0 or higher, the function sends a status line followed by the response headers. Because of buffering, the status line and response headers might not be sent immediately. To flush the status line and response headers, use the net_flush function. Use this function to set up HTTP and prepare the client and server to receive the body or data of the response.
If you do not want the server to send the status line and response headers, set rq->senthdrs = 1 before calling protocol_start_response or sending any data to the client.
int protocol_start_response(Session *sn, Request *rq);
The constant REQ_PROCEED if the operation succeeds, in which case you should send the data you were preparing to send.
The constant REQ_NOACTION if the operation succeeds but the request method is HEAD, in which case no data should be sent to the client.
The constant REQ_ABORTED if the operation fails.
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.
/* REQ_NOACTION means the request was HEAD */ if (protocol_start_response(sn, rq) == REQ_NOACTION) { filebuf_close(groupbuf); /* close our file*/ return REQ_PROCEED; }
protocol_status() Function, net_flush() Function
The protocol_status function sets the session status to indicate whether an error condition occurred. If the reason string is NULL, the server attempts to find a reason string for the given status code. If the function finds none, it returns Unknown reason. The reason string is sent to the client in the HTTP response line. Use this function to set the status of the response before calling the function protocol_start_response or returning REQ_ABORTED.
For the complete list of valid status code constants, refer to the nsapi.h file.
void protocol_status(Session *sn, Request *rq, int n, char *r);
void
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.
int n is one of the HTTP status code constants.
char *r is the reason string.
/* if we find extra path-info, the URL was bad so tell the */ /* browser it was not found */ if (t = pblock_findval("path-info", rq->vars)) { protocol_status(sn, rq, PROTOCOL_NOT_FOUND, NULL); log_error(LOG_WARN, "function-name", sn, rq, "%s not found",path); return REQ_ABORTED; }
protocol_start_response() Function
The protocol_uri2url function takes strings containing the given URI prefix and URI suffix, and creates a newly allocated, fully qualified URL in the form http://(server):(port)(prefix)(suffix). Also see protocol_uri2url_dynamic.
If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter.
char *protocol_uri2url(char *prefix, char *suffix);
A new string containing the URL.
char *prefix is the prefix.
char *suffix is the suffix.
pblock_nvinsert() Function, protocol_start_response() Function, protocol_status() Function, protocol_uri2url_dynamic() Function
The protocol_uri2url function takes strings containing the given URI prefix and URI suffix, and creates a newly allocated, fully qualified URL in the form http://(server):(port)(prefix)(suffix).
If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter.
The protocol_uri2url_dynamic function is similar to the protocol_uri2url function, but should be used whenever the Session and Request structures are available. This function ensures that the URL it constructs refers to the host that the client specified.
char *protocol_uri2url(char *prefix, char *suffix, Session *sn, Request *rq);
A new string containing the URL.
char *prefix is the prefix.
char *suffix is the suffix.
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same parameter as the ones passed into your SAF.
protocol_start_response() Function, protocol_status() Function