General-Purpose C Library Functions

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

Ns_AbsoluteUrl

Construct a URL from a URL and location

Syntax

    
    int Ns_AbsoluteUrl(
    Ns_DString *pds,
    char *url,
    char *baseurl
    );

Description

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

Examples

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



Ns_AdpRegisterParser

Register a parser for ADPs.

Syntax

    
    int Ns_AdpRegisterParser (
    char *name,
    Ns_AdpParserProc *newParserProc
    );

    typedef void (Ns_AdpParserProc)(Ns_DString *out, char *in);

Description

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.

The output should be formatted as a series of concatenated "chunks". A chunk is a string of the format: where: = '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 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"



Ns_AuthorizeRequest

Check access of a method and URL

Syntax

    
    int Ns_AuthorizeRequest(
    char *hServer,
    char *method,
    char *URL,
    char *authuser,
    char *authpasswd,
    char *ipaddr
    );

Description

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:

NS_OK

The user's access is authorized.

NS_UNAUTHORIZED

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.

NS_FORBIDDEN

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

NS_ERROR

The authentication function could not perform the permission check.



Ns_AuthorizeUser

Check username and password

Syntax

    
    int Ns_AuthorizeUser(
    char *user,
    char *passwd
    );

Description

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



Ns_ConfigGetBool

Get a boolean configuration file variable

Syntax

    
    int Ns_ConfigGetBool(
    char *hSection,
    char *sKey,
    int *pbValue
    );

Description

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.

Examples

        int opt;

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

   



Ns_ConfigGetInt

Get a configuration file integer variable

Syntax

    
    int Ns_ConfigGetInt(
    char *sectionName,
    char *key,
    int *valuePtr
    );

Description

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.

Examples

        int n;

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

   



Ns_ConfigGetInt64

Get a configuration file 64-bit integer variable

Syntax

    
    int Ns_ConfigGetInt64(
    char *hSection,
    char *key,
    INT64 *valuePtr
    );

Description

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.



Ns_ConfigGetPath

Return configuration file section name

Syntax

    
    char *Ns_ConfigGetPath(
    char *hServer,
    char *module,
    ...
    );

Description

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.

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.

Examples


    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");

        ...

   



Ns_ConfigGetSection

Get the Ns_Set for a configuration file section

Syntax

    
    Ns_Set *Ns_ConfigGetSection(
    char *sectionName
    );

Description

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.

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

Examples


        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);
        }
        ...

   



Ns_ConfigGetSections

Return Ns_Sets with configuration file data

Syntax

    
    Ns_Set **Ns_ConfigGetSections(void);

Description

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.



Ns_ConfigGetValue

Get a configuration file variable

Syntax

    
    char *Ns_ConfigGetValue(
    char *sectionName,
    char *key
    );

Description

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.

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

Examples

        /* Fetch the home directory of the AOLserver. */

        char *home;

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

   



Ns_ConfigGetValueExact

Get configuration variable case-sensitively

Syntax

    
    char *Ns_ConfigGetValueExact(
    char *sectionName,
    char *key,
    );

Description

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.

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

Examples

   See the example for Ns_ConfigGetValue.



Ns_DecodeUrl

Decode URL query data

Syntax

    
    char *Ns_DecodeUrl(
    Ns_DString *pds,
    char *data
    );

Description

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.



Ns_DStringAppend

Append a string to an Ns_DString

Syntax

    
    char *Ns_DStringAppend(
    Ns_DString *dsPtr,
    char *string
    );

Description

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.

Examples

    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.



Ns_DStringAppendArg

Append argument to an Ns_DString

Syntax

    
    char *Ns_DStringAppendArg(
    Ns_DString *dsPtr,
    char *arg
    );

Description

Ns_EncodeUrl

Encode URL query data

Syntax

    
    char *Ns_EncodeUrl(
    Ns_DString *pds,
    char *data
    );

Description

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 `?'.



Ns_Encrypt

Encrypt key

Syntax

    
    char *Ns_Encrypt(
    char *key,
    char *salt,
    char buf[]
    );

Description

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.



Ns_FetchPage

Copy data from URL to dynamic string

Syntax

    
    int Ns_FetchPage(
    Ns_DString *pds,
    char *url,
    char *hServer
    );

Description

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.



Ns_FetchURL

Fetch a remote URL.

Syntax

    
    int Ns_FetchURL(
    Ns_DString *pds,
    char *URL,
    Ns_Set *headers
    );

Description

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.



Ns_FreeRequest

Free memory used by an Ns_Request

Syntax

    
    void Ns_FreeRequest(
    Ns_Request *request
    );

Description

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.



Ns_GetConnInterp

Get the Tcl interpreter for the connection

Syntax

    
    EXTERN Tcl_Interp *Ns_GetConnInterp(
    Ns_Conn *conn
    );

Description

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.



Ns_GetMimeType

Get Mime type

Syntax

    
    char* Ns_GetMimeType (
    char* file
    );

Description

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



Ns_GetRequest

Return the parameters of a request

Syntax

    
    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
    );

Description

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.

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.



Ns_HtuuDecode

Perform base64 decode

Syntax

    
    int Ns_HtuuDecode (
    char* string,
    unsigned char* buf,
    int bufsize
    );

Description

Performs a base64 decode on string and writes the result into buf.



Ns_HtuuEncode

Perform base64 encode

Syntax

    
    int Ns_HtuuEncode (
    unsigned char* string,
    unsigned int bufsize,
    char* buf
    );

Description

Performs a base64 encode on string and writes the result into buf.



Ns_Match

Compare strings

Syntax

    
    char* Ns_Match (
    char* pattern,
    char* string
    );

Description

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



Ns_NextWord

Find next word in string

Syntax

    
    char* Ns_NextWord (
    char* line
    );

Description

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

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



Ns_ParseHeader

Parse Http headers

Syntax

    
    int Ns_ParseHeader (
    Ns_Set* psetHeaders,
    char* sHeader,
    ...
    );

Description

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



Ns_ParseRequest

Parse an HTTP request line into an Ns_Request

Syntax

    
    Ns_Request *Ns_ParseRequest(
    char *requestLine
    );

Description

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.



Ns_ParseUrl

Parse a URL

Syntax

    
    int Ns_ParseUrl(
    char *url,
    char **pprotocol,
    char **phost,
    char **pport,
    char **ppath,
    char **ptail
    );

Description

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.



Ns_PermPasswordCheck

Check user's encrypted password

Syntax

    
    int Ns_PermPasswordCheck(
    char *user,
    char *password
    );

Description

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.



Ns_QuoteHtml

Quote an HTML string

Syntax

    
    void Ns_QuoteHtml(
    Ns_DString *pds,
    char *string
    );

Description

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:

<

<

>

>

&

&



Ns_RegisterCleanup

Register a procedure for connection cleanup trace

Syntax

    
    void *Ns_RegisterCleanup(
    Ns_TraceProc *proc,
    void *arg
    );

Description

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.

It returns a pointer to the trace.



Ns_RegisterFilter

Register a filter function to handle a method/URL combination

Syntax

    
    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
    );

Description

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.

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

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:

/employees/*.tcl /accounts/*/out

Examples

    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);

   



Ns_RegisterProxyRequest

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

Syntax

    
    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
    );

Description

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.

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

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.

Examples

   See the example in the examples/c/nsproxy directory.



Ns_RegisterRequest

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

Syntax

    
    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
    );

Description

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.

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

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.

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.

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.

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.



Ns_RegisterReturn

Register a return status for a URL

Syntax

    
    void Ns_RegisterReturn (
    int status,
    char* url
    );

Description

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.



Ns_RegisterServerTrace

Register a trace procedure for a server.

Syntax

    
    typedef void (Ns_TraceProc) (void *context, Ns_Conn *conn);

    Ns_ProcHandle Ns_RegisterServerTrace(
    char *hServer,
    Ns_TraceProc *proc,
    void *context
    );

Description

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.



Ns_RelativeUrl

Get relative filename portion of URL

Syntax

    
    char *Ns_RelativeUrl(
    char *url,
    char *location
    );

Description

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.

Examples

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

   



Ns_SkipUrl

Skip past path elements in the URL of a request

Syntax

    
    char *Ns_SkipUrl(
    Ns_Request *request,
    int nurl
    );

Description

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

Examples

    /* 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);
    }

   



Ns_StrCaseFind

Perform strstr

Syntax

    
    char* Ns_StrCaseFind (
    char* string,
    char* substr
    );

Description

This function performs a case-insensitive strstr(3C).



Ns_StrCopy

Copy a string or NULL value using Ns_Malloc

Syntax

    
    char *Ns_StrCopy(
    char *string
    );

Description

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.



Ns_StrDup

Copy a string using Ns_Malloc

Syntax

    
    char *Ns_StrDup(
    char *string
    );

Description

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.



Ns_StringPrint

Print string

Syntax

    
    void Ns_StringPrint (
    char* s
    );

Description

This function prints the specified string to stdout.



Ns_Strtok

Perform strtok_r

Syntax

    
    char* Ns_Strtok (
    char* s1,
    const char* s2
    );

Description

This function wraps strtok_r(3C).



Ns_StrToLower

Lowercase string

Syntax

    
    char* Ns_StrToLower (
    char* string
    );

Description

This function converts the specified string to lowercase.



Ns_StrToUpper

Uppercase string

Syntax

    
    char* Ns_StrToUpper (
    char* string
    );

Description

This function converts the specified string to uppercase.



Ns_StrTrim

Trim string

Syntax

    
    char* Ns_StrTrim (
    char* string
    );

Description

This function trims all blanks from the specified string.



Ns_StrTrimLeft

Trim blanks from left

Syntax

    
    char* Ns_StrTrimLeft (
    char* string
    );

Description

This function trims all blanks from the left of the string.



Ns_StrTrimRight

Trim blanks from right

Syntax

    
    char* Ns_StrTrimRight (
    char* string
    );

Description

This function trims all blanks from the right of the string.



Ns_TclAllocateInterp

Allocate an interpreter for a server

Syntax

    
    Tcl_Interp *Ns_TclAllocateInterp(
    char *hServer
    );

Description

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.



Ns_TclAppendInt

Append integer to Tcl result

Syntax

    
    void Ns_TclAppendInt (
    Tcl_Interp* interp,
    int value
    );

Description

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



Ns_TclDeAllocateInterp

Perform cleanup after deallocating a Tcl interpreter

Syntax

    
    int Ns_TclDeAllocateInterp(
    Tcl_Interp *interp
    );

Description

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.



Ns_TclDestroyInterp

Mark Tcl interpreter for deletion

Syntax

    
    void Ns_TclDestroyInterp (
    Tcl_Interp*
    );

Description

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



Ns_TclEval

Execute a Tcl script

Syntax

    
    int Ns_TclEval (
    Ns_DString *pds,
    char *hServer
    char *script
    );

Description

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.

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";

Examples

   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)

   



Ns_TclGetOpenChannel

Get open channel in interpreter

Syntax

    
    int Ns_TclGetOpenChannel (
    Tcl_Interp* ,
    char* chanId,
    int write,
    int check,
    Tcl_Channel* channPtr
    );

Description

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

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.



Ns_TclGetOpenFd

Get open file descriptor

Syntax

    
    int Ns_TclGetOpenFd (
    Tcl_Interp* ,
    char* chanId,
    int write,
    int* fdPtr
    );

Description

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

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

This function returns TCL_ERROR or TCL_OK.



Ns_TclInitInterps

Call a Tcl init procedure in the parent interpreter

Syntax

    
    int Ns_TclInitInterps(
    char *hServer,
    Ns_TclInterpInitProc *proc,
    void *context
    );

Description

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);



Ns_TclInitModule

Source Tcl module before server startup

Syntax

    
    int Ns_TclInitModule (
    char* server,
    char* module
    );

Description

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.

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

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



Ns_TclInterpServer

Return name of server

Syntax

    
    char* Ns_TclInterpServer (
    Tcl_Interp* interp
    );

Description

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



Ns_TclLibrary

Return private Tcl directory

Syntax

    
    char* Ns_TclLibrary (void);

Description

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



Ns_TclLogError

Write errorInfo to log file

Syntax

    
    char* Ns_TclLogError (
    Tcl_Interp* interp
    );

Description

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



Ns_TclMarkForDelete

Mark Tcl interpreter for deletion

Syntax

    
    void Ns_TclMarkForDelete (
    Tcl_Interp*
    );

Description

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



Ns_UnRegisterProxyRequest

Unregister a proxy request function

Syntax

    
    void Ns_UnRegisterProxyRequest(
    char *Server,
    char *method,
    char *protocol
    );

Description

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.



Ns_UnRegisterRequest

Unregister a function

Syntax

    
    void Ns_UnRegisterRequest(
    char *hServer,
    char *method,
    char *URL,
    int flags
    );

Description

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.