NSAPI Developer's Guide

{section}
{column:width=30%}
{panel:borderStyle=outset|borderColor=#ff9900|bgColor=#ffffff}
*+[Home]+*
*+[Read Me First]+*
*+[Purpose and Policy]+*
*+[Frequently Asked Questions]+*
*+[Recently Updated Pages]+*
{panel}

{panel:borderStyle=outset|borderColor=#ff9900|bgColor=#ffffff}
{livesearch:spaceKey=WebServerdocs}
{panel}
{panel:borderStyle=outset|borderColor=#ff9900|titleBGColor=#BDBEC0|bgColor=#ffffff}
                           *{color:black}Table of Contents{color}*

----
{toc:minLevel=2|maxLevel=5|indent=15px}
{panel}
\\
{panel:borderStyle=outset|borderColor=#ff9900|bgColor=#ffffff}
                               *{color:black}Top Contributors {color}*

----
   {contributors-summary:columns=edits,comments|order=edits|labels=+nsapiguide}
{panel}
{column}

{column}

{panel:borderStyle=outset|borderColor=#ff9900|title=Related Documents|titleBGColor=#ff9900|bgColor=#ffffff}
*[Sun Java System Web Server 7.0 Update 5 Documentation Center|http://docs.sun.com/app/docs/doc/820-7340]*
*[Sun Java System Web Server 7.0 Update 5 Release Notes|Release Notes]*
*[Sun Java System Web Server 7.0 Update 5 Administrator's Configuration File Reference|Administrator's Configuration File Reference]*
*[Sun Java System Web Server 7.0 Update 5 Performance Tuning, Sizing and Scaling Guide|Performance Tuning, Sizing and Scaling Guide]*
*[Sun Java System Web Server 7.0 Update 5 Developer's Guide|Developer's Guide]*
*[Sun Java System Web Server 7.0 Update 5 Troubleshooting Guide|Troubleshooting Guide]*
*[Sun Java System Web Server 7.0 Update 5 Administrator's Guide|Administrator's Guide]*
*[Sun Java System Web Server 7.0 Update 5 Installation and Migration Guide|Installation and Migration Guide]*
*[Sun Java System Web Server 7.0 Update 5 Developer's Guide to Java Web Applications|Developer's Guide to Java Web Applications]*
*[Sun Java System Web Server 7.0 Update 5 CLI Reference Manual|http://docs.sun.com/app/docs/doc/820-7337]*
{panel}

h2. About NSAPI {anchor:cha1}

This chapter provides an overview of the Netscape Server API (NSAPI).

* h6. [Overview of NSAPI]

h2. Creating Custom Server Application Functions {anchor:cha2}

This chapter describes how to write your own NSAPI plug-ins that define custom Server Application Functions (SAFs). The ability to create custom plug-ins enables you to modify or extend the Sun Java System Web Server’s built-in functionality. For example, you can modify the server to handle user authorization in a special way or generate dynamic HTML pages based on information in a database.

This chapter has the following sections:
* h6. [Before Creating Custom SAFs]
* h6. [Creating and Using Custom SAFs]
* h6. [Overview of NSAPI C Functions]
* h6. [Required Behavior of SAFs for Each Directive]
* h6. [CGI to NSAPI Conversion]

Before writing custom SAFs, you must familiarize yourself with the request-handling process, as described in detail in the [Sun Java System Web Server Administrator's Configuration File Reference|Administrator's Configuration File Reference]. Also, before writing a custom SAF, check to see whether a built-in SAF already accomplishes the tasks you have in mind.

See [Appendix B: Alphabetical List of NSAPI Functions and Macros|#appdB] for a list of the predefined {{Init}} SAFs. For information about predefined SAFs used in the {{obj.conf}} file, see the [Sun Java System Web Server Administrator's Configuration File Reference|Administrator's Configuration File Reference].

For a complete list of the NSAPI routines for implementing custom SAFs, see [#NSAPI Function and Macro Reference].

                                                                                                                                                                                                                                      \[*Back to* *[top|#nsapi]*\]

h2. Creating Custom Filters {anchor:cha3}

This chapter describes how to create custom filters that can be used to intercept and possibly modify the content presented to or generated by another function.

This chapter has the following sections:
* h6. [NSAPI Filter Interface and Filter Methods]
* h6. [Overview of Filter Development]
* h6. [Creating and Using Custom Filters]

h2. Examples of Custom SAFs and Filters {anchor:cha4}

This chapter provides examples of custom Sever Application Functions (SAFs) and filters for each directive in the request-response process. You can use these examples as the basis for implementing your own custom SAFs and filters. For more information about creating your own custom SAFs, see [#Creating Custom Server Application Functions]. For information about creating your own filters, see [#Creating Custom Filters].

Before writing your own SAF, check to see whether an existing SAF serves your purpose. The predefined SAFs are discussed in the [Sun Java System Web Server Administrator's Configuration File Reference|Administrator's Configuration File Reference].

If you need to writer a custom SAF, you should be familiar with the request-response process and the role of the configuration file {{obj.conf}}. See the [Sun Java System Web Server Administrator's Configuration File Reference|Administrator's Configuration File Reference] for information on the {{obj.conf}} file.

For a list of the NSAPI functions for creating new SAFs, see [#NSAPI Function and Macro Reference].

This chapter has the following sections:
* h6. [Using the NSAPI Examples]
* h6. [AuthTrans() Example]
* h6. [NameTrans() Example]
* h6. [PathCheck() Example]
* h6. [ObjectType() Example]
* h6. [Output() Example]
* h6. [Service() Example]
* h6. [AddLog() Example]
* h6. [Quality of Service() Example]

h2. Creating Custom Server-Parsed HTML Tags {anchor:cha5}

This chapter describes the procedure to create custom server-parsed HTML tags. This chapter contains the following section:

* h6. [Define Custom Server-Parsed HTML Tags]

                                                                                                                                                                                                                                      \[*Back to* *[top|#nsapi]*\]

h2. NSAPI Function and Macro Reference {anchor:cha6}

This chapter lists all the public C functions and macros of the Netscape Server Applications Programming Interface (NSAPI). Use these functions when writing your own Server Application Functions (SAFs) and filters.

Each function provides the name, syntax, parameters, return value, a description of what the function does, and sometimes an example of its use and a list of related functions.

For more information on data structures, see [#Data Structure Reference].

For an alphabetical list of function names, see [Appendix B: Alphabetical List of NSAPI Functions and Macros|#appdB].

||h6.                    [C & D] ||h6.                           [F] ||h6.                    [I, L, M & N] ||
|       *Macros*
* {{CALLOC()}} Macro
 
*Functions*
* {{cinfo_find()}} Function
* {{condvar_init()}} Function
* {{condvar_notify()}} Function
* {{condvar_terminate()}} Function
* {{condvar_wait()}} Function
* {{crit_enter()}} Function
* {{crit_exit()}} Function
* {{crit_init()}} Function
* {{crit_terminate()}} Function
* {{daemon_atrestart()}} Function |       *Macros*
* {{FREE()}} Macro
 
*Functions*
* {{fc_close()}} Function
* {{fc_open()}} Function
* {{fc_net_write()}} Function
* {{filebuf_buf2sd()}} Function
* {{filebuf_close()}} Function
* {{filebuf_getc()}} Function
* {{filebuf_open()}} Function
* {{filebuf_open_nostat()}} Function
* {{filter_create()}} Function
* {{filter_find()}} Function
* {{filter_insert()}} Function
* {{filter_layer()}} Function
* {{filter_name()}} Function
* {{filter_remove()}} Function
* {{flush()}} Function
* {{func_exec()}} Function
* {{func_find()}} Function
* {{func_insert()}} Function |       *Macros*
* {{MALLOC()}} Macro
* {{NSAPI_RUNTIME_VERSION()}} Macro
* {{NSAPI_VERSION()}} Macro
 
*Functions*
* {{insert()}} Function
* {{log_error()}} Function
* {{net_flush()}} Function
* {{net_ip2host()}} Function
* {{net_read()}} Function
* {{net_sendfile()}} Function
* {{net_write()}} Function
* {{netbuf_buf2sd()}} Function
* {{netbuf_close()}} Function
* {{netbuf_getbytes()}} Function
* {{netbuf_getc()}} Function
* {{netbuf_grab()}} Function
* {{netbuf_open()}} Function
* {{nsapi_module_init()}} Function |

||h6.                        [P & R] ||h6.                       [S & U] ||h6.                              [V] ||h6.            [W] ||
|       *Macros*
* {{PERM_CALLOC()}} Macro
* {{PERM_FREE()}} Macro
* {{PERM_MALLOC()}} Macro
* {{PERM_REALLOC()}} Macro
* {{PERM_STRDUP()}} Macro
* {{REALLOC()}} Macro
 
*Functions*
* {{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
* {{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
* {{remove()}} Function
* {{request_get_vs()}} Function
* {{request_header()}} Function
* {{request_stat_path()}} Function
* {{request_translate_uri()}} Function |       *Macros*
* {{STRDUP()}} Macro
* {{USE_NSAPI_VERSION()}} Macro
 
*Functions*
* {{sendfile()}} Function
* {{session_dns()}} Function
* {{session_maxdns()}} Function
* {{shexp_casecmp()}} Function
* {{shexp_cmp()}} Function
* {{shexp_match()}} Function
* {{shexp_valid()}} Function
* {{system_errmsg()}} Function
* {{system_fclose()}} Function
* {{system_flock()}} Function
* {{system_fopenRO()}} Function
* {{system_fopenRW()}} Function
* {{system_fopenWA()}} Function
* {{system_fread()}} Function
* {{system_fwrite()}} Function
* {{system_fwrite_atomic()}} Function
* {{system_gmtime()}} Function
* {{system_localtime()}} Function
* {{system_lseek()}} Function
* {{system_rename()}} Function
* {{system_ulock()}} Function
* {{system_unix2local()}} Function
* {{systhread_attach()}} Function
* {{systhread_current()}} Function
* {{systhread_getdata()}} Function
* {{systhread_newkey()}} Function
* {{systhread_setdata()}} Function
* {{systhread_sleep()}} Function
* {{systhread_start()}} Function
* {{systhread_timerset()}} Function
* {{util_can_exec()}} Function (UNIX Only)
* {{util_chdir2path()}} Function
* {{util_cookie_find()}} Function
* {{util_env_find()}} Function
* {{util_env_create()}} Function
* {{util_env_free()}} Function
* {{util_env_replace()}} Function
* {{util_env_str()}} Function
* {{util_getline()}} Function
* {{util_hostname()}} Function
* {{util_is_mozilla()}} Function
* {{util_is_url()}} Function
* {{util_itoa()}} Function
* {{util_later_than()}} Function
* {{util_sh_escape()}} Function
* {{util_snprintf()}} Function
* {{util_sprintf()}} Function
* {{util_strcasecmp()}} Function
* {{util_strftime()}} Function
* {{util_strncasecmp()}} Function
* {{util_uri_escape()}} Function
* {{util_uri_is_evil()}} Function
* {{util_uri_parse()}} Function
* {{util_uri_unescape()}} Function
* {{util_vsnprintf()}} Function
* {{util_vsprintf()}} Function |       *Functions*
* {{vs_alloc_slot()}} Function
* {{vs_get_data()}} Function
* {{vs_get_default_httpd_object()}} Function
* {{vs_get_doc_root()}} Function
* {{vs_get_httpd_objset()}} Function
* {{vs_get_id()}} Function
* {{vs_get_mime_type()}} Function
* {{vs_lookup_config_var()}} Function
* {{vs_register_cb()}} Function
* {{vs_set_data()}} Function
* {{vs_translate_uri()}} Function |       *Functions*
* {{write()}} Function
* {{writev()}} Function |

                                                                                                                                                                                                                                      \[*Back to* *[top|#nsapi]*\]

h2. Data Structure Reference {anchor:cha7}

NSAPI uses many data structures that are defined in the {{nsapi.h}} header file, which is in the _install-dir_{{/include}} directory.

This chapter describes public data structures in {{nsapi.h}}.
{info:title=Note - }The data structures in {{nsapi.h}} that are not described in this chapter are considered private and could change incompatibly in future releases. Some of the data structures described in this chapter might contain additional, undocumented fields. These fields are also considered private and might change incompatibly in future releases. Additional fields may be added in future release, so do not make assumptions regarding the size of data structures.
{info}

This chapter has the following section:

* h6. [Public Data Structures]

h2. Dynamic Results Caching Functions {anchor:cha8}

The functions described in this chapter enables you to write a results caching plug-in for Sun Java System Web Server. A results caching plug-in, which is a {{Service}} SAF, caches data, a page, or part of a page in the web server address space, which the Web Server can refresh periodically on demand. An {{Init}} SAF initializes the callback function that performs the refresh.

This chapter has the following sections:

* h6. [About Results Caching Plug-ins]
* h6. [Dynamic Result Cache Functions]

h2. Appendix A: Hypertext Transfer Protocol {anchor:appdA}

The Hypertext Transfer Protocol (HTTP) is a protocol which is a set of rules that describes how information is exchanged, that enables a client such as a web browser and a Web Server to communicate with each other.

HTTP is based on a request-response model. The browser opens a connection to the server and sends a request to the server. The server processes the request and generates a response, which it sends to the browser. The server then closes the connection.

This chapter provides a short introduction to a few HTTP basics. For more information on HTTP, see the IETF home page at http://www.ietf.org/home.html.

This chapter has the following section:

* h6. [Compliance, Requests and Responses]

h2. Appendix B: Alphabetical List of NSAPI Functions and Macros {anchor:appdB}

This appendix provides an alphabetical list for the easy lookup of NSAPI functions and macros.

* h6. [NSAPI Functions and Macros - Alphabetical]

                                                                                                                                                                                                                                      \[*Back to* *[top|#nsapi]*\]

{column}
{section}