File: general.html

package info (click to toggle)
aolserver4 4.5.1-18.1
links: PTS, VCS
area: main
in suites: stretch
size: 12,008 kB
sloc: ansic: 45,126; tcl: 5,533; sh: 1,037; makefile: 380; pascal: 219; php: 13
file content (2429 lines) | stat: -rw-r--r-- 42,610 bytes
parent folder | download | duplicates (8)
<html>
<head>
<title>AOLserver</title>
</head>
<body>

<h1>General-Purpose C Library Functions</h1>

<p>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
<p>

<h2><a name= href=./>Ns_AbsoluteUrl</a></h2>


Construct a URL from a URL and location

<h3>Syntax</h3>

<pre>    
    int Ns_AbsoluteUrl(
    Ns_DString *pds,
    char *url,
    char *baseurl
    );
</pre>

<h3>Description</h3>

The Ns_AbsoluteUrl function constructs a URL, based on url, which may
be incomplete, and baseurl, which is typically a location.

<h3>Examples</h3>

<pre>
    Ns_DString ds;
    Ns_DStringInit(&ds);
    Ns_AbsoluteUrl(&ds, "/foo/bar.html", "http://www.foo.com:1234/");

   The ds DString will contain "http://www.foo.com:1234/foo/bar.html".
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_AdpRegisterParser</a></h2>


Register a parser for ADPs.

<h3>Syntax</h3>

<pre>    
    int Ns_AdpRegisterParser (
    char *name,
    Ns_AdpParserProc *newParserProc
    );

    typedef void (Ns_AdpParserProc)(Ns_DString *out, char *in);
</pre>

<h3>Description</h3>

This registers a new ADP parser with the name "name". The
newParserProc will be called when an ADP is to be parsed. The content
of the ADP will be in the "in" parameter. The parser should parse it
and append appropriate output into the "out" parameter.

<p>

The output should be formatted as a series of concatenated "chunks". A
   chunk is a string of the format:
    <type character><string><null>
where:

<type character> = 't' or 's'. A 't' means what follows is HTML and should be returneddirectly to the browser. An 's' means what follows is Tcl and should be evaluated.

   After the last chunk there should be an extra <null> character. For
   example, the "adp" parser will take a page like this:
    This is a test page<%ns_puts hi%>The end<%ns_puts bye%>

   And create this output:
    "tThis is a test page\0sns_puts hi\0tThe end\0sns_puts bye\0\0"
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_AuthorizeRequest</a></h2>

Check access of a method and URL

<h3>Syntax</h3>

<pre>    
    int Ns_AuthorizeRequest(
    char *hServer,
    char *method,
    char *URL,
    char *authuser,
    char *authpasswd,
    char *ipaddr
    );
</pre>

<h3>Description</h3>

The Ns_AuthorizeRequest function is used to call the function
   registered by Ns_SetRequestAuthorizeProc to authorize a user's access
   to the given method and URL. Possible return values are:

<p>

NS_OK

<p>

The user's access is authorized.

<p>

NS_UNAUTHORIZED

<p>

Access is not public for this method or URL and either the user and
   password were not verified or the user does not have permission.

<p>

NS_FORBIDDEN

<p>

There is no possible user/password combination that would give
   authorization.

<p>

NS_ERROR

<p>

The authentication function could not perform the permission check.

<p>

<hr>

<br>




<h2><a name= href=./>Ns_AuthorizeUser</a></h2>

Check username and password

<h3>Syntax</h3>

<pre>    
    int Ns_AuthorizeUser(
    char *user,
    char *passwd
    );
</pre>

<h3>Description</h3>

Checks that the cleartext password is correct for the specified user.
   Returns NS_OK if it matches or NS_ERROR if not (or if no authorization
   procedure is registered).


<p>

<hr>

<br>


<h2><a name= href=./>Ns_ConfigGetBool</a></h2>

Get a boolean configuration file variable

<h3>Syntax</h3>

<pre>    
    int Ns_ConfigGetBool(
    char *hSection,
    char *sKey,
    int *pbValue
    );
</pre>

<h3>Description</h3>

The Ns_ConfigGetBool function returns the boolean value of the
   specified key (sKey) in the specified configuration file section
   (hSection) and puts it into the integer pointed to by pbValue as a 1
   or 0. Values of "1", "y", "yes", "on", "t", and "true" are 1, and
   values of "0", "n", "no", "f", and "false" are 0. If any other value
   is found, a warning is written to the log and NS_FALSE is returned.
   Ns_ConfigGetBool returns NS_TRUE if a valid sKey exists and NS_FALSE
   otherwise.

<h3>Examples</h3>

<pre>
        int opt;

        if (Ns_ConfigGetBool("MySect", "MyKey", &opt) != NS_TRUE) {
                /* Option was not present or invalid - set a default. */
                opt = 0;        /* off */
        }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetInt</a></h2>

Get a configuration file integer variable

<h3>Syntax</h3>

<pre>    
    int Ns_ConfigGetInt(
    char *sectionName,
    char *key,
    int *valuePtr
    );
</pre>

<h3>Description</h3>

This function converts the specified value into an int and stores it
   in valuePtr. If the key does not exist in the config file or it is not
   an integer, the function returns NS_FALSE. Otherwise it returns
   NS_TRUE.

<h3>Examples</h3>

<pre>
        int n;

        if (Ns_ConfigGetInt("MySect", "MyKey", &n) != NS_TRUE) {
                /* Integer was not present or invalid - set a default. */
                n = 5;  /* off */
        }

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetInt64</a></h2>

Get a configuration file 64-bit integer variable

<h3>Syntax</h3>

<pre>    
    int Ns_ConfigGetInt64(
    char *hSection,
    char *key,
    INT64 *valuePtr
    );
</pre>

<h3>Description</h3>

This function converts the specified value into an INT64 and stores it
   in valuePtr. If the key does not exist in the config file or it is not
   an integer, the function returns NS_FALSE. Otherwise it returns
   NS_TRUE.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetPath</a></h2>

Return configuration file section name

<h3>Syntax</h3>

<pre>    
    char *Ns_ConfigGetPath(
    char *hServer,
    char *module,
    ...
    );
</pre>

<h3>Description</h3>

The Ns_ConfigGetPath function returns a pointer to a configuration
   file section name based on the server (hServer) and module specified.
   The hServer or module may be NULL. A variable number of additional
   path elements are appended. The list must end with NULL. For example,
   Ns_ConfigGetPath("server1", NULL, "special", NULL) will return
   "\NS\Server\server1\special" if such a section exists in the
   configuration file and NULL if it does not.

<p>

The space for the string returned is located in the configuration
   data. You do not need to deallocate the string and you must not alter
   it.

<h3>Examples</h3>

<pre>

    int
    Ns_ModuleInit(char *hServer, char *hModule)
    {
        char *path;
        char *value;

        /*
         * Construct the MySub section name specific to this
         * server and module. For example, if hServer = "vs1"
         * and hModule = "mymod", path would be:
         * [ns/server/vs1/module/mymod/MySudb]
         */
        path = Ns_ConfigGetPath(hServer, hModule, "MySub", NULL);
        value = Ns_ConfigGetValue(path, "MyKey");

        ...

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetSection</a></h2>

Get the Ns_Set for a configuration file section

<h3>Syntax</h3>

<pre>    
    Ns_Set *Ns_ConfigGetSection(
    char *sectionName
    );
</pre>

<h3>Description</h3>

This function returns the entire section as an Ns_Set, where the
   fields of the set correspond to the entries of the section in the
   config file. The fields are stored in the Ns_Set in the same order in
   which they appear in the configuration file section. This is useful if
   you want to loop through all the entries of a section. If the section
   does not exist, Ns_ConfigGetSection returns NULL.

<p>

The Ns_Set returned is located in the configuration data. You do not
   need to free the set and you must not alter it.

<h3>Examples</h3>

<pre>

        Ns_Set *section;
        int i;
        char *key;

        /* Log the keys of the "MySection" config section. */
        section = Ns_ConfigGetSection("MySection");
        for (i = 0; i < Ns_SetSize(section); ++i) {
                key = Ns_SetKey(section, i);
                Ns_Log(Notice, "key %d: %s", i, key);
        }
        ...

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetSections</a></h2>

Return Ns_Sets with configuration file data

<h3>Syntax</h3>

<pre>    
    Ns_Set **Ns_ConfigGetSections(void);
</pre>

<h3>Description</h3>

The Ns_ConfigGetSections function allocates and returns a
   null-terminated list of Ns_Sets. Each Ns_Set structure contains the
   configuration file data for a configuration file section.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetValue</a></h2>

Get a configuration file variable

<h3>Syntax</h3>

<pre>    
    char *Ns_ConfigGetValue(
    char *sectionName,
    char *key
    );
</pre>

<h3>Description</h3>

This function returns the value for the given key in the section named
   sectionName. If either the section does not exist or the key does not
   exist in the section, the function returns NULL. If multiple keys of
   the same name are in the named section (for example, the multiple Load
   lines of the Modules section), this function returns only the first
   matching entry. The section names must match exactly, but the key will
   be matched case-insensitively. Ns_ConfigGetValueExact is the
   case-sensitive counterpart of this function.

<p>

The space for the string returned is located in the configuration
   data. You must not deallocate or modify the string.

<h3>Examples</h3>

<pre>
        /* Fetch the home directory of the AOLserver. */

        char *home;

        home = Ns_ConfigGetValue("ns/parameters", "Home");

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ConfigGetValueExact</a></h2>

Get configuration variable case-sensitively

<h3>Syntax</h3>

<pre>    
    char *Ns_ConfigGetValueExact(
    char *sectionName,
    char *key,
    );
</pre>

<h3>Description</h3>

The Ns_ConfigGetValueExact function is a case-sensitive counterpart to
   the Ns_ConfigGetValue function. It matches both the section name and
   the key case-sensitively. It returns the value for the given key in
   the section named sectionName.

<p>

The space for the string returned is located in the configuration
   data. You must not deallocate or modify the string.

<h3>Examples</h3>

<pre>
   See the example for Ns_ConfigGetValue.
</pre>


<p>

<hr>

<br>

<h2><a name= href=./>Ns_DecodeUrl</a></h2>

Decode URL query data

<h3>Syntax</h3>

<pre>    
    char *Ns_DecodeUrl(
    Ns_DString *pds,
    char *data
    );
</pre>

<h3>Description</h3>

The Ns_DecodeUrl function decodes data that were encoded as URL query
   data. The decoded data are appended to the given Ns_DString. This
   function can be used to decode arguments that were passed as URL query
   data following a `?'. The return value is the value of pds->string,
   i.e., the address of the character array.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_DStringAppend</a></h2>

Append a string to an Ns_DString

<h3>Syntax</h3>

<pre>    
    char *Ns_DStringAppend(
    Ns_DString *dsPtr,
    char *string
    );
</pre>

<h3>Description</h3>

The Ns_DStringAppend macro appends the specified string plus a
   terminating null character to the end of the Ns_DString. The string
   may overflow from static space to the heap as a result of calling this
   function. It returns the string associated with the current
   Ns_DString.

<h3>Examples</h3>

<pre>
    Ns_DString ds;
    Ns_DStringInit(&ds);
    Ns_DStringAppend(&ds, "foo");
    /* do something with the dstring */
    printf("%s\n", ds.string);
    Ns_DStringFree(&ds); /* finished with dstring */

   The resulting Ns_DString, ds, would contain "foo\0" and have a length
   of 3.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_DStringAppendArg</a></h2>

Append argument to an Ns_DString

<h3>Syntax</h3>

<pre>    
    char *Ns_DStringAppendArg(
    Ns_DString *dsPtr,
    char *arg
    );
</pre>

<h3>Description</h3>


<h2><a name= href=./>Ns_EncodeUrl</a></h2>

Encode URL query data

<h3>Syntax</h3>

<pre>    
    char *Ns_EncodeUrl(
    Ns_DString *pds,
    char *data
    );
</pre>

<h3>Description</h3>

The Ns_EncodeUrl function encodes the data as URL query data and
   appends the encoded data to the given Ns_DString. All characters
   except the alphanumerics are encoded as specified in RFC1738, Uniform
   Resource Locators. This function can be used to append arguments to a
   URL as query data following a `?'.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_Encrypt</a></h2>

Encrypt key

<h3>Syntax</h3>

<pre>    
    char *Ns_Encrypt(
    char *key,
    char *salt,
    char buf[]
    );
</pre>

<h3>Description</h3>

The Ns_Encrypt function encrypts the specified key, perturbed by salt.
   The result is returned in buf, which should be at least
   NS_ENCRYPT_BUFSIZE bytes in size.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_FetchPage</a></h2>

Copy data from URL to dynamic string

<h3>Syntax</h3>

<pre>    
    int Ns_FetchPage(
    Ns_DString *pds,
    char *url,
    char *hServer
    );
</pre>

<h3>Description</h3>

The Ns_FetchPage function copies data from url to the Ns_DString
   pointed to by pds. The URL must be relative and must correspond to a
   file served by this server. Ns_FetchPage returns a status of NS_OK or
   NS_ERROR.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_FetchURL</a></h2>

Fetch a remote URL.

<h3>Syntax</h3>

<pre>    
    int Ns_FetchURL(
    Ns_DString *pds,
    char *URL,
    Ns_Set *headers
    );
</pre>

<h3>Description</h3>

The Ns_FetchURL function connects the AOLserver to another HTTP Web
   server and requests the specified URL. The URL must be fully
   qualified. The content is appended to the given Ns_DString. If the
   headers is not NULL, the HTTP headers returned in the response from
   the remote server are appended to the set. Ns_FetchUrl does not
   currently handle redirects or requests for any protocol except HTTP.
   Use Ns_FetchPage to get pages on the local server.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_FreeRequest</a></h2>

Free memory used by an Ns_Request

<h3>Syntax</h3>

<pre>    
    void Ns_FreeRequest(
    Ns_Request *request
    );
</pre>

<h3>Description</h3>

The Ns_FreeRequest function frees the members of the Ns_Request and
   then frees the Ns_Request structure itself. The request is no longer
   valid and must not be used after a call to Ns_FreeRequest.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_GetConnInterp</a></h2>

Get the Tcl interpreter for the connection

<h3>Syntax</h3>

<pre>    
    EXTERN Tcl_Interp *Ns_GetConnInterp(
    Ns_Conn *conn
    );
</pre>

<h3>Description</h3>

This function, given the conn, returns the interpreter already
   assigned to the conn if one exists. If no interpreter is assigned, it
   allocates a new interpreter and assigns it to the conn. By using this
   function, you can be certain that the same interpreter (and its global
   state) are used by the registered request function and the filters.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_GetMimeType</a></h2>

Get Mime type

<h3>Syntax</h3>

<pre>    
    char* Ns_GetMimeType (
    char* file
    );
</pre>

<h3>Description</h3>

Guess the Mime type based on the filename extension. Case is ignored.
   The return value is of the form: "text/html".
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_GetRequest</a></h2>

Return the parameters of a request

<h3>Syntax</h3>

<pre>    
    typedef void *Ns_OpContext;
    typedef int (Ns_OpProc) (void *context, Ns_Conn *conn);
    typedef void (Ns_OpDeleteProc) (void *context);

    void Ns_GetRequest(
    char *hServer
    char *method,
    char *URL,
    Ns_OpProc **pProc,
    Ns_OpDeleteProc **pDeleteProc,
    Ns_OpContext **pContext
    int *pflags
    );
</pre>

<h3>Description</h3>

The Ns_GetRequest function sets pproc to the procedure the server
   would call to handle a request of method and URL on the specified
   server. pContext is set to the context that would be passed to pProc
   when called, and pDeletepProc is set to the delete procedure that
   would be called if pProc were unregistered (or re-registered). pflags
   points to the flags argument passed to Ns_RegisterRequest. The
   function returned is the best matching function and not necessarily an
   exact matching function.

<p>

You can use Ns_GetRequest and the NS_OP_NODELETE flag for
   Ns_RegisterRequest to implement wrapper-type operation, where you save
   the operation function, delete procedure, and context and register a
   new function that does some type of pre-processing before calling the
   operation or delete procedures.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_HtuuDecode</a></h2>

Perform base64 decode

<h3>Syntax</h3>

<pre>    
    int Ns_HtuuDecode (
    char* string,
    unsigned char* buf,
    int bufsize
    );
</pre>

<h3>Description</h3>

Performs a base64 decode on string and writes the result into buf.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_HtuuEncode</a></h2>

Perform base64 encode

<h3>Syntax</h3>

<pre>    
    int Ns_HtuuEncode (
    unsigned char* string,
    unsigned int bufsize,
    char* buf
    );
</pre>

<h3>Description</h3>

Performs a base64 encode on string and writes the result into buf.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_Match</a></h2>

Compare strings

<h3>Syntax</h3>

<pre>    
    char* Ns_Match (
    char* pattern,
    char* string
    );
</pre>

<h3>Description</h3>

Compare the beginnings of two strings, case insensitively. The
   comparison stops when the end of the shorter string is reached.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_NextWord</a></h2>

Find next word in string

<h3>Syntax</h3>

<pre>    
    char* Ns_NextWord (
    char* line
    );
</pre>

<h3>Description</h3>

Find the next word (after whiteaspace) in a string.

<p>

For example, Ns_NextWord("abc def") returns a pointer to the 'd' in
   that string.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_ParseHeader</a></h2>

Parse Http headers

<h3>Syntax</h3>

<pre>    
    int Ns_ParseHeader (
    Ns_Set* psetHeaders,
    char* sHeader,
    ...
    );
</pre>

<h3>Description</h3>

Parse http headers into the Ns_Set. The trailing arguments exist for
   backwards compatibility and are ignored.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_ParseRequest</a></h2>

Parse an HTTP request line into an Ns_Request

<h3>Syntax</h3>

<pre>    
    Ns_Request *Ns_ParseRequest(
    char *requestLine
    );
</pre>

<h3>Description</h3>

The Ns_ParseRequest function takes an HTTP request line and returns a
   newly allocated Ns_Request structure. You must eventually call
   Ns_FreeRequest to free the memory used by the Ns_Request structure and
   its members.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_ParseUrl</a></h2>

Parse a URL

<h3>Syntax</h3>

<pre>    
    int Ns_ParseUrl(
    char *url,
    char **pprotocol,
    char **phost,
    char **pport,
    char **ppath,
    char **ptail
    );
</pre>

<h3>Description</h3>

Parse a URL into its component parts. Pointers to the protocol, host,
   port, path, and "tail" (last path element) will be set by reference in
   the passed-in pointers. The passed-in url will be modified. Return
   NS_OK on success or NS_ERROR on failure.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_PermPasswordCheck</a></h2>

Check user's encrypted password

<h3>Syntax</h3>

<pre>    
    int Ns_PermPasswordCheck(
    char *user,
    char *password
    );
</pre>

<h3>Description</h3>

Validate a user's encrypted password. This function is only accessible
   if the nsperm module is loaded. NS_TRUE is returned if the password is
   correct.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_QuoteHtml</a></h2>

Quote an HTML string

<h3>Syntax</h3>

<pre>    
    void Ns_QuoteHtml(
    Ns_DString *pds,
    char *string
    );
</pre>

<h3>Description</h3>

The Ns_QuoteHtml function appends the given string to the Ns_DString,
   making the following substitutions that allow HTML to be included in
   another HTML page as plain text:

<p>

<

<p>

&lt;

<p>

>

<p>

&gt;

<p>

&

<p>

&amp;
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_RegisterCleanup</a></h2>

Register a procedure for connection cleanup trace

<h3>Syntax</h3>

<pre>    
    void *Ns_RegisterCleanup(
    Ns_TraceProc *proc,
    void *arg
    );
</pre>

<h3>Description</h3>

Register a connection cleanup trace procedure. Traces registered with
   this procedure are always called in LIFO order at the end of
   connection, regardless of the result code from the connection's
   request procedure. In other words, the procedure is called even if the
   client drops connection.

<p>

It returns a pointer to the trace.
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_RegisterFilter</a></h2>

Register a filter function to handle a method/URL combination

<h3>Syntax</h3>

<pre>    
    typedef int (Ns_FilterProc) (void *context, Ns_Conn *conn, int
why);

    Ns_ProcHandle Ns_RegisterFilter(
    char *hServer,
    char *method,
    char *URLpatterns,
    Ns_FilterProc *proc,
    int why,
    void *context
    );
</pre>

<h3>Description</h3>

This function will register a filter procedure for a method/URL
   combination on a server. This function will be called at the specified
   stage of a connection, if the method/URL combination for the filter
   matches the method/URL combination for the connection using glob style
   matching. The procedures are run in last-registered last-run order. A
   filter procedure is often used for logging.

<p>

The why argument can be any of the following, or some combination of
   them by bitwise OR-ing (with "|") them together:

<p>

       NS_FILTER_PRE_AUTH: the filter will be called before
          authorization of a page
          NS_FILTER_POST_AUTH: the filter will be called after
          authorization but before a page has been returned
          NS_FILTER_TRACE: the filter will be called after the connection
          has been totally processed
          
   Using pre-authorization, the procedure will be called (assuming that
   the method/URL combination matches) just before authorization. If the
   procedure returns:
     * NS_OK: The server will continue to the next pre-authorization
       filter for this connection, or, if there are no more
       pre-authorization filters, it will continue on with authorization.
     * NS_FILTER_BREAK: The server will not process any more
       pre-authorization filters for this connection, and it will
       continue on with authorization.
     * NS_FILTER_RETURN: The server will close the connection and will
       not run any more pre-authorization filters. It will not authorize
       the request, and it will not run the function registered for this
       METHOD/URL. It WILL run any trace functions registered for this
       METHOD/URL, usually including logging. It is assumed that the
       filter has returned a proper response to the client before
       returning NS_FILTER_RETURN.
       
   Using post-authorization, the procedure will be called (assuming that
   the method/URL combination matches) just after successful
   authorization. If the procedure returns:
     * NS_OK: The server will continue to the next post-authorization
       filter for this connection, or, if there are no more
       post-authorization filters, it will run the function registered to
       handle this request.
     * NS_FILTER_BREAK: The server will not process any more
       post-authorization filters for this connection, and it will run
       the function registered to handle this request.
     * NS_FILTER_RETURN: The server will close the connection and will
       not run any more post-authorization filters and it will not run
       the function registered for this METHOD/URL. It WILL run any trace
       functions registered for this METHOD/URL, usually including
       logging. It is assumed that the filter has returned a proper
       response to the client before returning NS_FILTER_RETURN.
       
   Using trace, the procedure will be called (assuming that the
   method/URL combination match) after the connection has been totally
   processed and closed. If the procedure returns:
     * NS_OK: The server will continue to the next trace filter.
     * NS_FILTER_BREAK, NS_FILTER_RETURN: The rest of the trace filters
       are ignored
       
   The URLpatterns can contain standard string-matching characters. For
   example, these are valid URLpatterns:

<p>

       /employees/*.tcl
          /accounts/*/out
       
<h3>Examples</h3>

<pre>
    static int
    ReportUse(void *context, Ns_Conn *conn, int why){
     int status=NS_OK;
     switch(why){
      case NS_FILTER_PRE_AUTH:
       Ns_Log(Notice, "User trying to access %s",conn->request->url);
         break;
        case NS_FILTER_POST_AUTH:
          Ns_Log(Notice, "User authorized to access %s",conn->request-
>url);
          break;
        case NS_FILTER_TRACE:
          Ns_Log(Notice, "User has retrieved %s",conn->request->url);
          break;
        default:
          status=NS_ERROR;
      }
      return status;
    }
    int
    Ns_ModuleInit(char *hServer, char *hModule){
      Ns_RegisterFilter(hServer, "GET", "/test/a*", ReportUse,
        Ns_FILTER_PRE_AUTH, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/b*", ReportUse,
        Ns_FILTER_POST_AUTH, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/c*", ReportUse,
        Ns_FILTER_TRACE, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/d*", ReportUse,
        Ns_FILTER_PRE_AUTH | NS_FILTER_POST_AUTH, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/e*", ReportUse,
        Ns_FILTER_POST_AUTH | NS_FILTER_TRACE, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/f*", ReportUse,
        Ns_FILTER_PRE_AUTH | Ns_FILTER_POST_AUTH | NS_FILTER_TRACE,
NULL);

   
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_RegisterProxyRequest</a></h2>

Register a function to proxy requests for a method/protocol
   combination

<h3>Syntax</h3>

<pre>    
    typedef void *Ns_OpContext;
    typedef int (Ns_OpProc) (void *context, Ns_Conn *conn);
    typedef void (Ns_OpDeleteProc) (void *context);

    void Ns_RegisterProxyRequest(
    char        *Server,
    char        *method,
    char        *protocol,
    Ns_OpProc   *proc,
    Ns_Callback *deleteProc,
    void        *context
    );
</pre>

<h3>Description</h3>

The Ns_RegisterProxyRequest function registers function proc to handle
   HTTP requests. When the specified server receives a proxy request, it
   finds the appropriate registered function.

<p>

The server passes your procedure the context you specify here and the
   Ns_Conn structure associated with the new HTTP connection.

<p>

When a procedure is unregistered with either
   Ns_UnRegisterProxyRequest, the server calls the deleteProc with the
   same context. You can use this to do any cleanup you might require
   (e.g., close an index file or free something from the heap). If the
   value of deleteProc is NULL, the server does nothing.

<h3>Examples</h3>

<pre>
   See the example in the examples/c/nsproxy directory.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_RegisterRequest</a></h2>

Register one or two functions to handle HTTP requests for a method/URL
   combination

<h3>Syntax</h3>

<pre>    
    typedef void *Ns_OpContext;
    typedef int (Ns_OpProc) (void *context, Ns_Conn *conn);
    typedef void (Ns_OpDeleteProc) (void *context);

    void Ns_RegisterRequest(
    char *hServer,
    char *method,
    char *URL,
    Ns_OpProc *proc,
    Ns_OpDeleteProc *deleteProc,
    Ns_OpContext context,
    int flags
    );
</pre>

<h3>Description</h3>

The Ns_RegisterRequest function registers function proc to handle HTTP
   requests. When the specified server receives an HTTP request, it finds
   the most specific registered operation. The default operation for a
   GET (i.e., the one registered with URL \Q/') serves up a page out of
   the file system.

<p>

The server passes your procedure the context you specify here and the
   Ns_Conn structure associated with the new HTTP connection.

<p>

When a procedure is unregistered with either Ns_UnRegisterRequest or
   by registering another procedure with the same method and URL, the
   server calls the deleteProc with the same context. You can use this to
   do any cleanup you might require (e.g., close an index file or free
   something from the heap). If the value of deleteProc is NULL, the
   server does nothing.

<p>

The flags parameter specifies one or more constants that can be OR'ed
   together. The available flags are NS_OP_NOINHERIT and NS_OP_NODELETE.

<p>

NS_OP_NOINHERIT tells AOLserver to only call your procedure if the URL
   matches exactly (the default behavior is to look for the closest
   match). You can register two procedures for the same method/URL
   combination by calling Ns_RegisterRequest once with NS_OP_NOINHERIT
   specified and once without NS_OP_NOINHERIT specified. The first
   procedure will be called if there is an exact match with the specified
   URL. The second procedure will be called if the requested URL is below
   the specified URL, provided there is not already another procedure
   registered with a closer match.

<p>

NS_OP_NODELETE specifies that the previous procedure's deleteproc
   should not be called. NS_OP_NODELETE can be used in conjunction with
   Ns_GetRequest to implement wrappers.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_RegisterReturn</a></h2>

Register a return status for a URL

<h3>Syntax</h3>

<pre>    
    void Ns_RegisterReturn (
    int status,
    char* url
    );
</pre>

<h3>Description</h3>

Associate a URL with a return status (for custom error pages). For
   exmaple:
    Ns_RegisterReturn(404, "http://www.foo.com/notfound.html");

   will send redirects to http://www.foo.com/notfound.html whenever a 404
   error is to be returned.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_RegisterServerTrace</a></h2>

Register a trace procedure for a server.

<h3>Syntax</h3>

<pre>    
    typedef void (Ns_TraceProc) (void *context, Ns_Conn *conn);

    Ns_ProcHandle Ns_RegisterServerTrace(
    char *hServer,
    Ns_TraceProc *proc,
    void *context
    );
</pre>

<h3>Description</h3>

The Ns_RegisterServerTrace function registers proc as a trace for the
   specified server. The server calls all trace procedures after every
   HTTP connection with the context and the Ns_Conn for that connection.
   The procedures are run in last-registered first-run order. A trace
   procedure is often used for logging.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_RelativeUrl</a></h2>

Get relative filename portion of URL

<h3>Syntax</h3>

<pre>    
    char *Ns_RelativeUrl(
    char *url,
    char *location
    );
</pre>

<h3>Description</h3>

Given a URL and a location, Ns_RelativeUrl returns a pointer to the
   relative filename portion of the specified URL. The example below
   returns a pointer to /index.html.

<h3>Examples</h3>

<pre>
    /* returns a pointer to /index.html */
    Ns_RelativeUrl("http://www.foo.com/index.html",
                                        "http://www.foo.com");

   
</pre>


<p>

<hr>

<br>


<h2><a name= href=./>Ns_SkipUrl</a></h2>

Skip past path elements in the URL of a request

<h3>Syntax</h3>

<pre>    
    char *Ns_SkipUrl(
    Ns_Request *request,
    int nurl
    );
</pre>

<h3>Description</h3>

The Ns_SkipUrl function returns the request URL after skipping past
   the first nurl elements.

<h3>Examples</h3>

<pre>
    /* PathInfo - Request to return URL after the first 2 parts. */
    int
    PathInfo(Ns_Conn *conn, void *ctx)
    {
        char *info;

        /* Skip past the first two parts */
        info = Ns_SkipUrl(conn->request, 2);
        return Ns_ConnReturnNotice(conn, 200, info, NULL);
    }

   
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_StrCaseFind</a></h2>

Perform strstr

<h3>Syntax</h3>

<pre>    
    char* Ns_StrCaseFind (
    char* string,
    char* substr
    );
</pre>

<h3>Description</h3>

This function performs a case-insensitive strstr(3C).
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrCopy</a></h2>

Copy a string or NULL value using Ns_Malloc

<h3>Syntax</h3>

<pre>    
    char *Ns_StrCopy(
    char *string
    );
</pre>

<h3>Description</h3>

The Ns_StrCopy function is identical to the Ns_StrDup function but
   allows for the string parameter to be NULL, in which case Ns_StrCopy
   does nothing and returns NULL.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrDup</a></h2>

Copy a string using Ns_Malloc

<h3>Syntax</h3>

<pre>    
    char *Ns_StrDup(
    char *string
    );
</pre>

<h3>Description</h3>

The Ns_StrDup function calls Ns_Malloc to allocate enough memory to
   make a copy of the given string. This function replaces the system
   strdup function.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StringPrint</a></h2>

Print string

<h3>Syntax</h3>

<pre>    
    void Ns_StringPrint (
    char* s
    );
</pre>

<h3>Description</h3>

This function prints the specified string to stdout.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_Strtok</a></h2>

Perform strtok_r

<h3>Syntax</h3>

<pre>    
    char* Ns_Strtok (
    char* s1,
    const char* s2
    );
</pre>

<h3>Description</h3>

This function wraps strtok_r(3C).
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrToLower</a></h2>

Lowercase string

<h3>Syntax</h3>

<pre>    
    char* Ns_StrToLower (
    char* string
    );
</pre>

<h3>Description</h3>

This function converts the specified string to lowercase.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrToUpper</a></h2>

Uppercase string

<h3>Syntax</h3>

<pre>    
    char* Ns_StrToUpper (
    char* string
    );
</pre>

<h3>Description</h3>

This function converts the specified string to uppercase.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrTrim</a></h2>

Trim string

<h3>Syntax</h3>

<pre>    
    char* Ns_StrTrim (
    char* string
    );
</pre>

<h3>Description</h3>

This function trims all blanks from the specified string.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrTrimLeft</a></h2>

Trim blanks from left

<h3>Syntax</h3>

<pre>    
    char* Ns_StrTrimLeft (
    char* string
    );
</pre>

<h3>Description</h3>

This function trims all blanks from the left of the string.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_StrTrimRight</a></h2>

Trim blanks from right

<h3>Syntax</h3>

<pre>    
    char* Ns_StrTrimRight (
    char* string
    );
</pre>

<h3>Description</h3>

This function trims all blanks from the right of the string.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclAllocateInterp</a></h2>

Allocate an interpreter for a server

<h3>Syntax</h3>

<pre>    
    Tcl_Interp *Ns_TclAllocateInterp(
    char *hServer
    );
</pre>

<h3>Description</h3>

This function reserves and returns a Tcl interpreter associated with
   the server. You will usually want to use the Ns_GetConnInterp function
   instead, since connections often already have interpreters associated
   with them.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclAppendInt</a></h2>

Append integer to Tcl result

<h3>Syntax</h3>

<pre>    
    void Ns_TclAppendInt (
    Tcl_Interp* interp,
    int value
    );
</pre>

<h3>Description</h3>

Append an integer to the Tcl result. This is essentially a safe
   version of sprintf(interp->result, "%d", value).
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclDeAllocateInterp</a></h2>

Perform cleanup after deallocating a Tcl interpreter

<h3>Syntax</h3>

<pre>    
    int Ns_TclDeAllocateInterp(
    Tcl_Interp *interp
    );
</pre>

<h3>Description</h3>

This function is called automatically after each Tcl request procedure
   if the AutoClose configuratin parameter is set on. Sets created by
   Ns_TclEnterSet are deleted or not deleted, depending on the flags set
   in the Ns_TclEnterSet function.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclDestroyInterp</a></h2>

Mark Tcl interpreter for deletion

<h3>Syntax</h3>

<pre>    
    void Ns_TclDestroyInterp (
    Tcl_Interp*
    );
</pre>

<h3>Description</h3>

Mark the Tcl interpreter for deletion. At thread death, clean up its
   state, close files, free memory, etc.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_TclEval</a></h2>

Execute a Tcl script

<h3>Syntax</h3>

<pre>    
    int Ns_TclEval (
    Ns_DString *pds,
    char *hServer
    char *script
    );
</pre>

<h3>Description</h3>

The Ns_TclEval function executes the Tcl function specified by script
   on the server specified by hServer. It writes the results to the
   passed-in pds variable.

<p>

Note that the string in script may be temporarily modified by Tcl, so
   it must be writable. For example, use:
    char script[*]="sometcl";

   instead of:
    char *script="sometcl";

    <h3>Examples</h3>

    
<pre>
   Use this code to call ns_sendmail from C:
    NS_DStringVarAppend(&dsScript, "ns_sendmail", to, " ",
      from, " ", subject, " ", body);
    status=Ns_TclEval(&dsResult, Ns_ConnServer(conn),
      dsScript.string)

   
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_TclGetOpenChannel</a></h2>

Get open channel in interpreter

<h3>Syntax</h3>

<pre>    
    int Ns_TclGetOpenChannel (
    Tcl_Interp* ,
    char* chanId,
    int write,
    int check,
    Tcl_Channel* channPtr
    );
</pre>

<h3>Description</h3>

This function fills in channptr with a channel open in the passed-in
   interpreter if one exists. It returns TCL_OK or TCL_ERROR. The chanId
   is a channel name (the handle that Tcl uses).

<p>

This function also has the ability to check if a channel is opened for
   reading or writing. If check is true, the check is performed. If write
   is true, the channel is checked for writeability. If write is false,
   the channel is checked for readability. If the check is performed and
   fails, then an error is returned and appended to the interpreter.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclGetOpenFd</a></h2>

Get open file descriptor

<h3>Syntax</h3>

<pre>    
    int Ns_TclGetOpenFd (
    Tcl_Interp* ,
    char* chanId,
    int write,
    int* fdPtr
    );
</pre>

<h3>Description</h3>

This function returns an open Unix file descriptor for the specified
   channel. The value at fdPtr is updated with a valid Unix file
   descriptor.

<p>

The write parameter specifies if a writable (TRUE) or readable (FALSE)
   channel is being requested. See the Tcl 7.6 documentation for
   Tcl_GetChannelFile.

<p>

This function returns TCL_ERROR or TCL_OK.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_TclInitInterps</a></h2>

Call a Tcl init procedure in the parent interpreter

<h3>Syntax</h3>

<pre>    
    int Ns_TclInitInterps(
    char *hServer,
    Ns_TclInterpInitProc *proc,
    void *context
    );
</pre>

<h3>Description</h3>

Ns_TclInitInterps runs the specified procedure (proc) in the parent
   interpreter of the specified server. The definition of
   Ns_TclInterpInitProc is:
    typedef int (Ns_TclInterpInitProc) (Tcl_Interp *interp, void
*context);

   
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclInitModule</a></h2>

Source Tcl module before server startup

<h3>Syntax</h3>

<pre>    
    int Ns_TclInitModule (
    char* server,
    char* module
    );
</pre>

<h3>Description</h3>

Put this module on this list of modules whose Tcl is to be sourced
   before server startup and after modules are loaded. The server
   parameter is ignored.

<p>

For example, calling Ns_TclInitModule(NULL, "nsfoo") from
   Ns_ModuleInit will cause the following directories to be sourced after
   all modules are loaded:

<p>

       (aolserver home)/servers/server1/modules/tcl/nsfoo/*.tcl
          (aolserver home)/modules/tcl/nsfoo/*.tcl
       </pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclInterpServer</a></h2>

Return name of server

<h3>Syntax</h3>

<pre>    
    char* Ns_TclInterpServer (
    Tcl_Interp* interp
    );
</pre>

<h3>Description</h3>

Return the name of the server, such as "server1". The interp argument
   is ignored.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclLibrary</a></h2>

Return private Tcl directory

<h3>Syntax</h3>

<pre>    
    char* Ns_TclLibrary (void);
</pre>

<h3>Description</h3>

This function returns the name of the private Tcl directory, such as
   "(aolserver home)/servers/server1/modules/tcl".
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclLogError</a></h2>

Write errorInfo to log file

<h3>Syntax</h3>

<pre>    
    char* Ns_TclLogError (
    Tcl_Interp* interp
    );
</pre>

<h3>Description</h3>

This function writes the value of the errorInfo variable out to the
   log. See the Tcl documentation for more on the global errorInfo
   variable.
</pre>


<p>

<hr>

<br>




<h2><a name= href=./>Ns_TclMarkForDelete</a></h2>

Mark Tcl interpreter for deletion

<h3>Syntax</h3>

<pre>    
    void Ns_TclMarkForDelete (
    Tcl_Interp*
    );
</pre>

<h3>Description</h3>

Mark this interpreter for deletion. When the thread terminates (and it
   must be a connection thread), the tcl interpreter will be deleted.
</pre>


<p>

<hr>

<br>





<h2><a name= href=./>Ns_UnRegisterProxyRequest</a></h2>

Unregister a proxy request function

<h3>Syntax</h3>

<pre>    
    void Ns_UnRegisterProxyRequest(
    char *Server,
    char *method,
    char *protocol
    );
</pre>

<h3>Description</h3>

The Ns_UnRegisterProxyRequest function unregisters the function for
   the specified method and protocol on a specific server. If the
   deleteProc is not null, it is called with the function's context as an
   argument.
</pre>


<p>

<hr>

<br>



<h2><a name= href=./>Ns_UnRegisterRequest</a></h2>

Unregister a function

<h3>Syntax</h3>

<pre>    
    void Ns_UnRegisterRequest(
    char *hServer,
    char *method,
    char *URL,
    int flags
    );
</pre>

<h3>Description</h3>

The Ns_UnRegisterRequest function unregisters the function with the
   specified method/URL combination and with the same inheritance setting
   on a specific server. That is, if the flags argument is set to
   NS_OP_NOINHERIT in Ns_UnRegisterRequest, the function registered with
   the NS_OP_NOINHERIT flag in Ns_RegisterRequest (or the -noinherit flag
   in ns_register_proc) will be unregistered. If the flags argument is
   set to 0, the function registered without the NS_OP_NOINHERIT flag (or
   the -noinherit flag) will be unregistered.
</pre>


<p>

<hr>

<br>


</body>
</html>