Overview of NSAPI C Functions

NSAPI provides a set of C functions that are used to implement SAFs. These functions serve several purposes:

• Provide platform independence across operating system and hardware platforms

• Improved performance

• Thread-safe, a requirement for SAFs

• Prevent memory leaks

• Provide functionality necessary for implementing SAFs

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 6, NSAPI Function and Macro 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

• Virtual Server

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. For more information, see pblock_findval() Function.

• pblock_nvinsert adds a new name-value pair entry to a pblock. For more information, see pblock_nvinsert() Function.

• pblock_remove removes a pblock entry by name from a pblock. The entry is not disposed. Use param_free() Function to free the memory used by the entry. For more information, see pblock_remove() Function.

• param_free frees the memory for the given pblock entry. For more information, see param_free() Function.

• pblock_pblock2str creates a new string containing all of the name-value pairs from a pblock in the form “name=value name=value.” This function can be a useful for debugging. For more information, see pblock_pblock2str() Function.

Protocol Utilities for Service SAFs

Protocol utilities provide functionality necessary to implement Service SAFs:

• protocol_status sets the HTTP response status code and reason phrase. For more information, see protocol_status() Function.

• protocol_start_response sends the HTTP response and all HTTP headers to the browser. For more information, see protocol_start_response() Function.

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. Wrappers enable standard memory routines to use permanent memory. To disable the server's pooled memory allocator for debugging,use the built-in SAF pool-init. For more information, see the Sun Java System Web Server 7.0 Update 4 Administrator’s Configuration File Reference.

• MALLOC() Macro

• FREE() Macro

• PERM_STRDUP() Macro

• REALLOC() Macro

• CALLOC() Macro

• PERM_MALLOC() Macro

• PERM_FREE() Macro

• PERM_STRDUP() Macro

• PERM_REALLOC() Macro

• PERM_CALLOC() Macro

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. For more information, see system_fopenRO() Function.

• system_fopenRW opens a file for read-write access, creating the file if necessary. For more information, see system_fopenRW() Function.

• system_fopenWA opens a file for write-append access, creating the file if necessary. For more information, see system_fopenWA() Function.

• system_fclose closes a file. For more information, see system_fclose() Function.

• system_fread reads from a file. For more information, see system_fread() Function.

• system_fwrite writes to a file. For more information, see system_fwrite() Function.

• system_fwrite_atomic locks the given file before writing to it. This locking avoids interference between simultaneous writes by multiple processes or threads. For more information, see system_fwrite_atomic() Function.

Network I/O

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. For more information, see netbuf_grab() Function.

• netbuf_getbytes gets a character from a network buffer. For more information, see netbuf_getbytes() Function.

• net_flush flushes buffered data. For more information, see net_flush() Function.

• net_read reads bytes from a specified socket into a specified buffer. For more information, see net_read() Function.

• net_sendfile sends the contents of a specified file to a specified a socket. For more information, see net_sendfile() Function.

• net_write writes to the network socket. For more information, see net_write() Function.

Threads

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

• systhread_start creates a new thread. For more information, see systhread_start() Function.

• systhread_sleep puts a thread to sleep for a given time. For more information, see systhread_sleep() Function.

• crit_init creates a new critical section variable. For more information, see crit_init() Function.

• crit_enter gains ownership of a critical section. For more information, see crit_enter() Function.

• crit_exit surrenders ownership of a critical section. For more information, see crit_exit() Function.

• crit_terminate disposes of a critical section variable. For more information, see crit_terminate() Function.

• condvar_init creates a new condition variable. For more information, see condvar_init() Function.

• condvar_notify awakens any threads blocked on a condition variable. For more information, see condvar_notify() Function.

• condvar_wait blocks on a condition variable. For more information, see condvar_wait() Function.

• condvar_terminate disposes of a condition variable. For more information, see condvar_terminate() Function.

• prepare_nsapi_thread enables threads that are not created by the server to act like server-created threads. For more information, see prepare_nsapi_thread() Function.

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 registers a user function to be called when the server is sent a restart signal (HUP) or at shutdown. For more information, see daemon_atrestart() Function.

• daemon_atrestart gets the local host name as a fully qualified domain name. For more information, see util_hostname() Function.

• util_later_than compares two dates. For more information, see util_later_than() Function.

• util_sprintf is the same as the standard library routine sprintf(). For more information, see util_sprintf() Function.

• util_strftime is the same as the standard library routine strftime(). For more information, see util_strftime() Function.

• util_uri_escape converts the special characters in a string into URI-escaped format. For more information, see util_uri_escape() Function.

• util_uri_unescape converts the URI-escaped characters in a string back into special characters. For more information, see util_uri_unescape() Function.

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.

Virtual Server

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. For more information, see request_get_vs() Function.

• vs_alloc_slot allocates a new slot for storing a pointer to data specific to a certain virtual server. For more information, see vs_alloc_slot() Function.

• vs_get_data finds the value of a pointer to data for a given virtual server and slot. For more information, see vs_get_data() Function.

• vs_get_default_httpd_object obtains a pointer to the default or root object from the virtual server's virtual server class configuration. For more information, see vs_get_default_httpd_object() Function.

• vs_get_doc_root finds the document root for a virtual server. For more information, see vs_get_doc_root() Function.

• vs_get_httpd_objset obtains a pointer to the virtual server class configuration for a given virtual server. For more information, see

• vs_get_id finds the ID of a virtual server. For more information, see vs_get_id() Function.

• vs_get_mime_type determines the MIME type that would be returned in the content-type: header for the given URI. For more information, see vs_get_mime_type() Function.

• vs_lookup_config_var finds the value of a configuration variable for a given virtual server. For more information, see vs_lookup_config_var() Function.

• vs_register_cb enables a plug-in to register functions that will receive notifications of virtual server initialization and destruction events. For more information, see vs_register_cb() Function.

• vs_set_data sets the value of a pointer to data for a given virtual server and slot. For more information, see vs_set_data() Function.

• vs_translate_uri translates a URI as though it were part of a request for a specific virtual server. For more information, see vs_translate_uri() Function.