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, pblock_pinsert, pblock_remove
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, pblock_pinsert, pblock_remove
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, pblock_dup, pblock_free, pblock_find, pblock_findval, pblock_remove, pblock_nvinsert
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 (number of name-value pairs) for the pblock.
pblock_copy, pblock_dup, pblock_find, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove
The pblock_dup function duplicates a pblock. It is equivalent to a sequence of pblock_create and pblock_copy.
pblock *pblock_dup(pblock *src);
A pointer to a newly allocated pblock.
pblock *src is the source pblock.
pblock_create, pblock_find, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove
The pblock_find macro finds a specified name-value pair entry in a pblock, and returns the pb_param structure. If you only want 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 name is not found.
char *name is the name of a name-value pair.
pblock *pb is the pblock to be searched.
pblock_copy, pblock_dup, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove
The pblock_findval function finds the value associated with a specified name in a pblock. If you want 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 it, 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.
See pblock_nvinsert.
pblock_create, pblock_copy, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, request_header
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, pblock_create, pblock_dup, pblock_find, pblock_findval, pblock_nvinsert, pblock_remove
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 the value you assign is not a number, then instead use the function pblock_nvinsert to create the parameter.
pblock *pb is the pblock into which the insertion occurs.
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
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, pblock_create, pblock_find, pblock_free, pblock_nninsert, pblock_remove, pblock_str2pblock
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, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
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 is a new string; otherwise, it is a reallocated string. In either case, it 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. It 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, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
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, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
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, pblock_create, pblock_find, pblock_free, pblock_nvinsert, param_create, param_free
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=), it 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, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_pblock2str
The PERM_CALLOC macro is a platform-independent substitute for the C library routine calloc. It 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, PERM_FREE, PERM_STRDUP, PERM_MALLOC, PERM_REALLOC
The PERM_FREE macro is a platform-independent substitute for the C library routine free. It 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 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, PERM_MALLOC, PERM_CALLOC, PERM_REALLOC, PERM_STRDUP
The PERM_MALLOC macro is a platform-independent substitute for the C library routine malloc. It 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, PERM_FREE, PERM_STRDUP, PERM_CALLOC, PERM_REALLOC
The PERM_REALLOC macro is a platform-independent substitute for the C library routine realloc. It changes the size of a specified memory block that was originally created by PERM_MALLOC, PERM_CALLOC, or PERM_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 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 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, PERM_CALLOC, PERM_MALLOC, PERM_FREE, PERM_STRDUP
The PERM_STRDUP macro is a platform-independent substitute for the C library routine strdup. It 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 pool-init built-in SAF), PERM_STRDUP and STRDUP both obtain their memory from the system heap.
The PERM_STRDUP routine is functionally equivalent to:
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, PERM_FREE, PERM_CALLOC, PERM_REALLOC, MALLOC, FREE, STRDUP, CALLOC, REALLOC
The prepare_nsapi_thread function allows 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 as the ones passed into your SAF.
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 dumped.
int tsz is the size of the buffer.
protocol_start_response, protocol_status
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 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, protocol_status
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 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; }
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 it 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 as the ones passed into your SAF.
int n is an HTTP status code constants above.
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; }
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). 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, protocol_start_response, protocol_status, protocol_uri2url_dynamic
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 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 as the ones passed into your SAF.