Sun Java System Web Server 6.1 SP6 NSAPI Programmer's Guide

P

param_create

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.

Syntax

pb_param *param_create(char *name, char *value);

Returns

A pointer to a new pb_param structure.

Parameters

char *name is the string containing the name.

char *value is the string containing the value.

Example

pb_param *newpp = param_create("content-type","text/plain");
pblock_pinsert(newpp, rq->srvhdrs);

See Also

param_free, pblock_pinsert, pblock_remove

param_free

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.

Syntax

int param_free(pb_param *pp);

Returns

1 if the parameter was freed or 0 if the parameter was NULL.

Parameters

pb_param *pp is the name-value pair stored in a pblock.

Example

if (param_free(pblock_remove("content-type", rq-srvhdrs)))
    return; /* we removed it */

See Also

param_create, pblock_pinsert, pblock_remove

pblock_copy

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.

Syntax

void pblock_copy(pblock *src, pblock *dst);

Returns

void

Parameters

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.

See Also

pblock_create, pblock_dup, pblock_free, pblock_find, pblock_findval, pblock_remove, pblock_nvinsert

pblock_create

The pblock_create function creates a new pblock. The pblock maintains an internal hash table for fast name-value pair lookups.

Syntax

pblock *pblock_create(int n);

Returns

A pointer to a newly allocated pblock.

Parameters

int n is the size of the hash table (number of name-value pairs) for the pblock.

See Also

pblock_copy, pblock_dup, pblock_find, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove

pblock_dup

The pblock_dup function duplicates a pblock. It is equivalent to a sequence of pblock_create and pblock_copy.

Syntax

pblock *pblock_dup(pblock *src);

Returns

A pointer to a newly allocated pblock.

Parameters

pblock *src is the source pblock.

See Also

pblock_create, pblock_find, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove

pblock_find

The pblock_find function 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.

This function is implemented as a macro.

Syntax

pb_param *pblock_find(char *name, pblock *pb);

Returns

A pointer to the pb_param structure if one was found, or NULL if name was not found.

Parameters

char *name is the name of a name-value pair.

pblock *pb is the pblock to be searched.

See Also

pblock_copy, pblock_dup, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove

pblock_findval

The pblock_findval function finds the value of a specified name in a pblock. If you just 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.

Syntax

char *pblock_findval(char *name, pblock *pb);

Returns

A string containing the value associated with the name or NULL if no match was found.

Parameters

char *name is the name of a name-value pair.

pblock *pb is the pblock to be searched.

Example

see pblock_nvinsert.

See Also

pblock_create, pblock_copy, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, request_header

pblock_free

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.

Syntax

void pblock_free(pblock *pb);

Returns

void

Parameters

pblock *pb is the pblock to be freed.

See Also

pblock_copy, pblock_create, pblock_dup, pblock_find, pblock_findval, pblock_nvinsert, pblock_remove

pblock_nninsert

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.

Syntax

pb_param *pblock_nninsert(char *name, int value, pblock *pb);

Returns

A pointer to the new pb_param structure.

Parameters

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.

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_nvinsert

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.

Syntax

pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);

Returns

A pointer to the newly allocated pb_param structure.

Parameters

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.

Example

pblock_nvinsert("content-type", "text/html", rq->srvhdrs);

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nninsert, pblock_remove, pblock_str2pblock

pblock_pb2env

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.

Syntax

char **pblock_pb2env(pblock *pb, char **env);

Returns

A pointer to the environment.

Parameters

pblock *pb is the pblock to be copied.

char **env is the environment into which the pblock is to be copied.

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_pblock2str

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.

Syntax

char *pblock_pblock2str(pblock *pb, char *str);

Returns

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.

Parameters

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."

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_pinsert

The function pblock_pinsert inserts a pb_param structure into a pblock.

Syntax

void pblock_pinsert(pb_param *pp, pblock *pb);

Returns

void

Parameters

pb_param *pp is the pb_param structure to insert.

pblock *pb is the pblock.

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_remove

The pblock_remove function removes a specified name-value entry from a specified pblock. If you use this function, you should eventually call param_free to deallocate the memory used by the pb_param structure.

Syntax

pb_param *pblock_remove(char *name, pblock *pb);

Returns

A pointer to the named pb_param structure if it was found, or NULL if the named pb_param was not found.

Parameters

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.

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, param_create, param_free

pblock_str2pblock

The pblock_str2pblock function scans a string for parameter pairs, adds them to a pblock, and returns the number of parameters added.

Syntax

int pblock_str2pblock(char *str, pblock *pb);

Returns

The number of parameter pairs added to the pblock, if any, or -1 if an error occurred.

Parameters

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.

See Also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_pblock2str

PERM_CALLOC

The PERM_CALLOC macro is a platform-independent substitute for the C library routine calloc. It allocates int size bytes of memory that persist 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_CALLOC and CALLOC both obtain their memory from the system heap.

Syntax

void *PERM_CALLOC(int size)

Returns

A void pointer to a block of memory.

Parameters

int size is the size in bytes of each element.

Example

char **name;name = (char **) PERM_CALLOC(100);

See Also

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

PERM_FREE

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. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), both PERM_FREE and FREE deallocates memory in the system heap.

Syntax

PERM_FREE(void *ptr);

Returns

void

Parameters

void *ptr is a (void *) pointer to block of memory. If the pointer is not one created by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP, the behavior is undefined.

Example

char *name;name = (char *) PERM_MALLOC(256);...PERM_FREE(name);

See Also

FREE, MALLOC, CALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_CALLOC, PERM_REALLOC, PERM_STRDUP

PERM_MALLOC

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. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_MALLOC and MALLOC both obtain their memory from the system heap.

Syntax

void *PERM_MALLOC(int size)

Returns

A void pointer to a block of memory.

Parameters

int size is the number of bytes to allocate.

Example

/* Allocate 256 bytes for a name */char *name;name = (char *) PERM_MALLOC(256);

See Also

PERM_FREE, PERM_STRDUP, PERM_CALLOC, PERM_REALLOC, MALLOC, FREE, CALLOC, STRDUP, REALLOC

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 MALLOC, CALLOC, or 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.

Warning

Calling PERM_REALLOC for a block that was allocated with MALLOC, CALLOC, or STRDUP will not work.

Syntax

void *PERM_REALLOC(vod *ptr, int size)

Returns

A void pointer to a block of memory.

Parameters

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.

Example

char *name;name = (char *) PERM_MALLOC(256);if (NotBigEnough())
    name = (char *) PERM_REALLOC(512);

See Also

PERM_MALLOC,PERM_FREE, PERM_CALLOC, PERM_STRDUP, MALLOC, FREE, STRDUP, CALLOC, REALLOC

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.

Syntax

char *PERM_STRDUP(char *ptr);

Returns

A pointer to the new string.

Parameters

char *ptr is a pointer to a string.

See Also

PERM_MALLOC,PERM_FREE, PERM_CALLOC, PERM_REALLOC, MALLOC, FREE, STRDUP, CALLOC, REALLOC

prepare_nsapi_thread

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.

Syntax

void prepare_nsapi_thread(Request *rq, Session *sn);

Returns

void

Parameters

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.

See Also

protocol_start_response

protocol_dump822

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.

Syntax

char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);

Returns

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.

Parameters

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.

See Also

protocol_start_response, protocol_status

protocol_set_finfo

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.

Syntax

int protocol_set_finfo(Session *sn, Request *rq, struct stat *finfo);

Returns

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.

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.

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.

See Also

protocol_start_response, protocol_status

protocol_start_response

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, the function sends a status line followed by the response headers. Use this function to set up HTTP and prepare the client and server to receive the body (or data) of the response.

Syntax

int protocol_start_response(Session *sn, Request *rq);

Returns

The constant REQ_PROCEED if the operation succeeded, in which case you should send the data you were preparing to send.

The constant REQ_NOACTION if the operation succeeded but the request method was HEAD, in which case no data should be sent to the client.

The constant REQ_ABORTED if the operation did not succeed.

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.

Example

/* A noaction response from this function means the request 
was HEAD */if (protocol_start_response(sn, rq) == REQ_NOACTION) 
filebuf_close(groupbuf);  /* close our file*/    return REQ_PROCEED;}

See Also

protocol_status

protocol_status

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.

For the complete list of valid status code constants, please refer to the file "nsapi.h" in the server distribution.

Syntax

void protocol_status(Session *sn, Request *rq, int n, char *r);

Returns

void, but it sets values in the Session/Request designated by sn/rq for the status code and the reason string.

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.

int n is one of the status code constants above.

char *r is the reason string.

Example

/* 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;}

See Also

protocol_start_response

protocol_uri2url

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.

Syntax

char *protocol_uri2url(char *prefix, char *suffix);

Returns

A new string containing the URL.

Parameters

char *prefix is the prefix.

char *suffix is the suffix.

See Also

protocol_start_response, protocol_status, pblock_nvinsert, protocol_uri2url_dynamic

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.

Syntax

char *protocol_uri2url(char *prefix, char *suffix, Session *sn, Request *rq);

Returns

A new string containing the URL.

Parameters

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.

See Also

protocol_start_response, protocol_status, protocol_uri2url_dynamic