NSAPI provides a set of C functions that are used to implement SAFs. They serve several purposes. They provide platform independence across 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 detailed in Chapter 5, NSAPI Function and Macro Reference.
The main categories of NSAPI functions are:
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 pair 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 can be a useful function for debugging.
Protocol utilities provide functionality necessary to implement Service SAFs:
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 routines provide fast, platform-independent versions of the standard memory management routines. They 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. To disable the server's pooled memory allocator for debugging, see the built-in SAF pool-init in the Sun Java System Web Server 7.0 Administrator’s Configuration File Reference.
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 processes or threads.
Network I/O functions provide platform-independent, thread-safe network I/O routines. These routines work with SSL when it is enabled.
netbuf_grab reads from a network buffer’s socket into the network buffer.
netbuf_getbytes 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.
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.
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 registers a user function to be called when the server is sent a restart signal (HUP) or at shutdown.
util_hostname gets the local host name as a fully qualified domain name.
util_later_than compares two dates.
util_sprintf 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 does not work.
The virtual server functions provide routines for retrieving information about virtual servers.
request_get_vs finds the virtual server to which a request is directed.
vs_alloc_slot allocates a new slot for storing a pointer to data specific to a certain virtual server.
vs_get_data finds the value of a pointer to data for a given virtual server and slot.
vs_get_default_httpd_object obtains a pointer to the default (or root) object from the virtual server's virtual server class configuration.
vs_get_doc_root finds the document root for a virtual server.
vs_get_httpd_objset obtains a pointer to the virtual server class configuration for a given virtual server.
vs_get_id finds the ID of a virtual server.
vs_get_mime_type determines the MIME type that would be returned in the content-type: header for the given URI.
vs_lookup_config_var finds the value of a configuration variable for a given virtual server.
vs_register_cb allows a plug-in to register functions that will receive notifications of virtual server initialization and destruction events.
vs_set_data sets the value of a pointer to data for a given virtual server and slot.
vs_translate_uri translates a URI as though it were part of a request for a specific virtual server.