Overview of NSAPI C Functions

NSAPI provides a set of C functions that are used to implement SAFs. These functions serve several purposes; They provide platform independence across Sun Java System Web Proxy Server operating system and hardware platforms. They provide improved performance. They are thread-safe which is a requirement for SAFs. They prevent memory leaks. And they provide functionality necessary for implementing SAFs. You should always use these NSAPI routines when defining new SAFs.

This section provides an overview of the function categories available and some of the more commonly used routines. All of the public routines are described in detail in Chapter 4, NSAPI Function Reference

The main categories of NSAPI functions are:

• Parameter Block Manipulation Routines

• Protocol Utilities for Service SAFs

• Memory Management

• File I/O

• Network I/O

• Threads

• Utilities

Parameter Block Manipulation Routines

The parameter block manipulation functions provide routines for locating, adding, and removing entries in a pblock data structure

• pblock_findval returns the value for a given name in a pblock.

• pblock_nvinsert adds a new name-value entry to a pblock.

• pblock_remove removes a pblock entry by name from a pblock. The entry is not disposed. Use param_free to free the memory used by the entry.

• param_free frees the memory for the given pblock entry.

• pblock_pblock2str creates a new string containing all of the name-value pairs from a pblock in the form “name=value name=value.” This string can be useful for debugging.

Protocol Utilities for Service SAFs

Protocol utilities provide functionality necessary to implement Service SAFs

• request_header returns the value for a given request header name, reading the headers if necessary. This function must be used when requesting entries from the browser header pblock (rq->headers).

• protocol_status sets the HTTP response status code and reason phrase.

• protocol_start_response sends the HTTP response and all HTTP headers to the browser.

Memory Management

Memory management routines provide fast, platform-independent versions of the standard memory management routines. These routines also prevent memory leaks by allocating from a temporary memory, called “pooled” memory for each request, and then disposing the entire pool after each request. There are wrappers for standard memory routines for using permanent memory.

• MALLOC

• FREE

• PERM_STRDUP

• REALLOC

• CALLOC

• PERM_MALLOC

• PERM_FREE

• PERM_REALLOC

• PERM_CALLOC

File I/O

The file I/O functions provide platform-independent, thread-safe file I/O routines.

• system_fopenRO opens a file for read-only access.

• system_fopenRW opens a file for read-write access, creating the file if necessary.

• system_fopenWA opens a file for write-append access, creating the file if necessary.

• system_fclose closes a file.

• system_fread reads from a file.

• system_fwrite writes to a file.

• system_fwrite_atomic locks the given file before writing to it. This avoids interference between simultaneous writes by multiple threads.

Network I/O

Network I/O functions provide platform-independent, thread-safe network I/O routines. These routines work with SSL when SSL is enabled.

• netbuf_grab reads from a network buffer’s socket into the network buffer.

• netbuf_getc gets a character from a network buffer.

• net_flush flushes buffered data.

• net_read reads bytes from a specified socket into a specified buffer.

• net_sendfile sends the contents of a specified file to a specified a socket.

• net_write writes to the network socket.

Threads

Thread functions include functions for creating your own threads that are compatible with the server’s threads. There are also routines for critical sections and condition variables.

• systhread_start creates a new thread.

• systhread_sleep puts a thread to sleep for a given time.

• crit_init creates a new critical section variable.

• crit_enter gains ownership of a critical section.

• crit_exit surrenders ownership of a critical section.

• crit_terminate disposes of a critical section variable.

• condvar_init creates a new condition variable.

• condvar_notify awakens any threads blocked on a condition variable.

• condvar_wait blocks on a condition variable.

• condvar_terminate disposes of a condition variable.

• prepare_nsapi_thread allows threads that are not created by the server to act like server-created threads.

Utilities

Utility functions include platform-independent, thread-safe versions of many standard library functions (such as string manipulation), as well as new utilities useful for NSAPI.

• daemon_atrestart (UNIX only) registers a user function to be called when the server is sent a restart signal (HUP) or at shutdown.

• condvar_init gets the next line (up to a LF or CRLF) from a buffer.

• util_hostname gets the local host name as a fully qualified domain name.

• util_later_than compares two dates.

• util_snprintf is the same as the standard library routine sprintf().

• util_strftime is the same as the standard library routine strftime().

• util_uri_escape converts the special characters in a string into URI-escaped format.

• util_uri_unescape converts the URI-escaped characters in a string back into special characters.

You cannot use an embedded null in a string, because NSAPI functions assume that a null is the end of the string. Therefore, passing Unicode-encoded content through an NSAPI plug-in.