P & R

                                                                                                                                                                                                                                                                                                                                      Back to [Book]     [Topic]

Functions and Macros beginning with P and R

The following functions and macros are discussed in this section:

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 read() Function REALLOC() Macro
remove() Function request_get_vs() Function request_header() Function request_stat_path() Function request_translate_uri() Function

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 Return Values Parameters Example 
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);

See Also

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 Return Values Parameters Example 
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 */

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
pblock *pblock_dup(pblock *src);
A pointer to a newly allocated pblock. pblock *src is the source pblock.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
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 Also

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 Return Values Parameters 
void pblock_free(pblock *pb);
void pblock *pb is the pblock to be freed.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters Example 
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);

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
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" .

See Also

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 Return Values Parameters 
void pblock_pinsert(pb_param *pp, pblock *pb);
void pb_param *pp is the pb_param structure to insert.
pblock *pb is the pblock.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters Example 
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 *));

See Also

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 Return Values Parameters Example 
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);

See Also

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 Return Values Parameters Example 
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);

See Also

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 Return Values Parameters Example 
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);

See Also

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 Return Values Parameters 
char *PERM_STRDUP(char *ptr);
A pointer to the new string. char *ptr is a pointer to a string.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters 
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.

See Also

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 Return Values Parameters Example 
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;
}

See Also

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 Return Values Parameters Example 
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;
}

See Also

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 Return Values Parameters 
char *protocol_uri2url(char *prefix, char *suffix);
A new string containing the URL. char *prefix is the prefix.
char *suffix is the suffix.

See Also

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 Return Values Parameters 
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.

See Also

read() Function

The read filter method is called when input data is required. Filters that modify or consume incoming data should implement the read filter method.

Upon receiving control, a read implementation should fill buf with up to amount bytes of input data. This data can be obtained by calling the net_read() function, as shown in the example below.

Syntax Return Values Parameters Example 
int read(FilterLayer *layer, void *buf, int amount, int timeout);
The number of bytes placed in buf on success. 0 if no data is available, or a negative value if an error occurs. FilterLayer *layer is the filter layer in which the filter is installed.
void *buf is the buffer in which data should be placed.
int amount is the maximum number of bytes that should be placed in the buffer.
int timeout is the number of seconds to allow the read operation to return. The purpose of timeout is to limit the amount of time devoted to waiting until some data arrives, not to return because not enough bytes were read in the given time. 
int myfilter_read(FilterLayer *layer, void *buf, int amount, int timeout)
{        
    return net_read(layer->lower, buf, amount, timeout);
}

See Also

REALLOC() Macro

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

Caution -
Calling REALLOC for a block that was allocated with PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP will not work.
Syntax Return Values Parameters Example 
void *REALLOC(void *ptr, int size);
A pointer to the new space if the request is satisfied. 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.
int size is the number of bytes to allocate. 
char *name;
name = (char *) MALLOC(256);
if (NotBigEnough())    
    name = (char *) REALLOC(name, 512);

See Also

remove() Function

The remove filter method is called when the filter stack is destroyed, or when a filter is removed from a filter stack by the filter_remove function or remove-filter SAF.

Note -
Waiting until the remove method is invoked might be too late to flush buffered data. For this reason, filters that buffer outgoing data should implement the flush filter method.
Syntax Return Values Parameters 
void remove(FilterLayer *layer);
void FilterLayer *layer is the filter layer in which the filter is installed.

See Also

request_get_vs() Function

The request_get_vs function finds the VirtualServer* to which a request is directed.

The returned VirtualServer* is valid only for the current request. To retrieve a virtual server ID that is valid across requests, use vs_get_id().

Syntax Return Values Parameters 
const VirtualServer* request_get_vs(Request* rq);
The VirtualServer* to which the request is directed. Request rq is the request for which the VirtualServer is returned.

See Also

request_header() Function

The request_header function finds an entry in the pblock containing the client’s HTTP request headers (rq->headers). You must use this function rather than pblock_findval when accessing the client headers, because the server might begin processing the request before the headers have been completely read.

Syntax Return Values Parameters 
int request_header(char *name, char **value, Session *sn, Request *rq);
A result code, REQ_PROCEED if the header was found, REQ_ABORTED if the header was not found, or REQ_EXIT if there was an error reading from the client. char *name is the name of the header.
char **value is the address where the function will place the value of the specified header. If no address is found, the function stores a NULL.
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.

request_stat_path() Function

The request_stat_path function returns the file information structure for a specified path or, if no path is specified, the path entry in the vars pblock in the specified request structure. If the resulting file name points to a file that the server can read, request_stat_path returns a new file information structure. This structure contains information about the size of the file, its owner, when it was created, and when it was last modified.

Use request_stat_path to retrieve information on the file you are currently accessing instead of calling stat directly, because this function keeps track of previous calls for the same path and returns its cached information.

Syntax Return Values Parameters Example 
struct stat *request_stat_path(char *path, Request *rq);
Returns a pointer to the file information structure for the file named by the path parameter. Do not free this structure. Returns NULL if the file is not valid or the server cannot read it. In this case, it also leaves an error message describing the problem in rq->staterr. char *path is the string containing the name of the path. If the value of path is NULL, the function uses the path entry in the vars pblock in the request structure denoted by rq.
Request *rq is the request identifier for a Server Application Function call. 
fi = request_stat_path(path, rq);

See Also

request_translate_uri() Function

The request_translate_uri function performs virtual-to-physical mapping on a specified URI during a specified session. Use this function to determine the file to be sent back if a given URI is accessed.

Syntax Return Values Parameters 
char *request_translate_uri(char *uri, Session *sn);
A path string if the function performed the mapping, or NULL if it could not perform the mapping. char *uri is the name of the URI.
Session *sn is the Session parameter that is passed into the SAF.

See Also

Labels

java java Delete
server server Delete
sun sun Delete
webserver webserver Delete
application application Delete
system system Delete
webtier webtier Delete
guide guide Delete
webserver70 webserver70 Delete
sunjava sunjava Delete
nsapi nsapi Delete
nsapidevelopersguide nsapidevelopersguide Delete
developers developers Delete
web web Delete
+nsapiguide +nsapiguide Delete
nsapiguide nsapiguide Delete
developersguide developersguide Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Sun Microsystems community and they might not be employed or in any way formally affiliated with Sun Microsystems. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Sun nor any other party necessarily agrees with them.

Copyright 1994-2009 Sun Microsystems, Inc.
Powered by Atlassian Confluence Sun Guidelines on Public Discourse Privacy Policy Terms of Use Trademarks Site Map Employment Investor Relations Contact