Overview of NSAPI C Functions

NSAPI provides a set of C functions that are used to implement SAFs. They serve several purposes. They provide platform independence across Sun Java System Web 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 detailed in Chapter 7, 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

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

• 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 can be a useful function 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. 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 pooled memory for debugging, see the built-in SAF pool-init in Chapter 2, SAFs in the magnus.conf File

• MALLOC

• FREE

• PERM_STRDUP

• REALLOC

• CALLOC

• PERM_MALLOC

• PERM_FREE

• PERM_STRDUP

• 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 processes or threads.

Network I/O

Network I/O functions provide platform-independent, thread-safe network I/O routines. These routines work with SSL when it’s 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_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 doesn’t 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.

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