P (Sun Java System Web Server 7.0 Update 4 NSAPI Developer's Guide)

Sun Java System Web Server 7.0 Update 4 NSAPI Developer's Guide

P

`param_create()` Function

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);

Return Values

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);

`param_free()` 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.

Syntax

int param_free(pb_param *pp);

Return Values

1 if the parameter is freed or 0 if the parameter is 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 */

`pblock_copy()` 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.

Syntax

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

Return Values

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.

`pblock_create()` 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.

Syntax

pblock *pblock_create(int n);

Return Values

A pointer to a newly allocated pblock.

Parameters

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

`pblock_dup()` Function

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

Syntax

pblock *pblock_dup(pblock *src);

Return Values

A pointer to a newly allocated pblock.

Parameters

pblock *src is the source pblock.

`pblock_find()` 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.

Note –

Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

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

Return Values

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

Parameters

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

pblock *pb is the pblock to be searched.

`pblock_findval()` 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.

Note –

Parameter names are case-sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

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

Return Values

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

Parameters

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

pblock *pb is the pblock to be searched.

`pblock_free()` 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.

Syntax

void pblock_free(pblock *pb);

Return Values

void

Parameters

pblock *pb is the pblock to be freed.

`pblock_nninsert()` 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.

Note –

Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

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

Return Values

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 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_nvinsert()` 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.

Note –

Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

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

Return Values

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);

`pblock_pb2env()` 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.

Syntax

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

Return Values

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.

`pblock_pblock2str()` 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.

Syntax

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

Return Values

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.

Parameters

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_pinsert()` Function

The function pblock_pinsert inserts a pb_param structure into a pblock.

Note –

Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

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

Return Values

void

Parameters

pb_param *pp is the pb_param structure to insert.

pblock *pb is the pblock.

`pblock_remove()` 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.

Syntax

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

Return Values

A pointer to the named pb_param structure if it is found, or NULL if the named pb_param is 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.

`pblock_str2pblock()` Function

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);

Return Values

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

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=), 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.

`PERM_CALLOC()` Macro

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.

Syntax

void *PERM_CALLOC(int size)

Return Values

A void pointer to a block of memory.

Parameters

int size is the number of bytes to allocate.

Example

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

`PERM_FREE()` 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.

Note –

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

Syntax

PERM_FREE(void *ptr);

Return Values

void

Parameters

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.

Example

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

`PERM_MALLOC()` 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.

Syntax

void *PERM_MALLOC(int size)

Return Values

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);

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

Caution –

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

Syntax

void *PERM_REALLOC(vod *ptr, int size)

Return Values

A void pointer to a block of memory.

Parameters

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.

Example

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

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

Syntax

char *PERM_STRDUP(char *ptr);

Return Values

A pointer to the new string.

Parameters

char *ptr is a pointer to a string.

`prepare_nsapi_thread()` Function

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.

Syntax

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

Return Values

void

Parameters

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_dump822()` 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.

Syntax

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

Return Values

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

int tsz is the size of the buffer.

`protocol_set_finfo()` 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.

Syntax

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

Return Values

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

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.

Note –

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.

Syntax

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

Return Values

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.

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 your SAF.

Example

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

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.

Syntax

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

Return Values

void

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 your SAF.

int n is one of the HTTP status code constants.

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

`protocol_uri2url()` 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.

Syntax

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

Return Values

A new string containing the URL.

Parameters

char *prefix is the prefix.

char *suffix is the suffix.

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

Syntax

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

Return Values

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 parameter as the ones passed into your SAF.

P

param_create() Function

Syntax

Return Values

Parameters

Example

See Also

param_free() Function

Syntax

Return Values

Parameters

Example

See Also

pblock_copy() Function

Syntax

Return Values

Parameters

See Also

pblock_create() Function

Syntax

Return Values

Parameters

See Also

pblock_dup() Function

Syntax

Return Values

Parameters

See Also

pblock_find() Function

Syntax

Return Values

Parameters

See Also

pblock_findval() Function

Syntax

Return Values

Parameters

See Also

pblock_free() Function

Syntax

Return Values

Parameters

See Also

pblock_nninsert() Function

Syntax

Return Values

Parameters

See Also

pblock_nvinsert() Function

Syntax

Return Values

Parameters

Example

See Also

pblock_pb2env() Function

Syntax

Return Values

Parameters

See Also

pblock_pblock2str() Function

Syntax

Return Values

Parameters

See Also

pblock_pinsert() Function

Syntax

Return Values

Parameters

See Also

pblock_remove() Function

Syntax

Return Values

Parameters

See Also

pblock_str2pblock() Function

Syntax

Return Values

Parameters

See Also

PERM_CALLOC() Macro

`param_create()` Function

`param_free()` Function

`pblock_copy()` Function

`pblock_create()` Function

`pblock_dup()` Function

`pblock_find()` Function

`pblock_findval()` Function

`pblock_free()` Function

`pblock_nninsert()` Function

`pblock_nvinsert()` Function

`pblock_pb2env()` Function

`pblock_pblock2str()` Function

`pblock_pinsert()` Function

`pblock_remove()` Function

`pblock_str2pblock()` Function

`PERM_CALLOC()` Macro

`PERM_FREE()` Macro

`PERM_MALLOC()` Macro

`PERM_REALLOC()` Macro

`PERM_STRDUP()` Macro

`prepare_nsapi_thread()` Function

`protocol_dump822()` Function

`protocol_set_finfo()` Function

`protocol_start_response()` Function

`protocol_status()` Function

`protocol_uri2url()` Function

`protocol_uri2url_dynamic()` Function