NAME

       Ns_UrlSpecificAlloc,   Ns_UrlSpecificDestroy,  Ns_UrlSpecificGet,  Ns_UrlSpecificGetExact,
       Ns_UrlSpecificGetFast, Ns_UrlSpecificSet - Store and retrieve URL-specific data

SYNOPSIS

       #include "ns.h"

       int
       Ns_UrlSpecificAlloc(void)

       void *
       Ns_UrlSpecificDestroy(char *server, char *method, char *url,
           int id, int flags)

       void *
       Ns_UrlSpecificGet(char *server, char *method, char *url,
           int id)

       void *
       Ns_UrlSpecificGetExact(char *server, char *method, char *url,
           int id, int flags)

       void *
       Ns_UrlSpecificGetFast(char *server, char *method, char *url,
           int id)

       void
       Ns_UrlSpecificSet(char *server, char *method, char *url,
           int id, void *data, int flags, void (*deletefunc) (void *))
_________________________________________________________________

DESCRIPTION

       These functions allow you to store URL-specific data in memory for later  retrieval.  They
       are used when registering procedures for example.

       Ns_UrlSpecificAlloc()

              Return  a  unique  ID used to identify a unique virtual URL-space that is then used
              with the Ns_UrlSpecific storage functions. You should only call  this  function  at
              server startup, and not after. Here is an example:

              static int myId;

              void
              Init(void)
              {
                  /* Allocate the id once at startup. */
                  myId = Ns_UrlSpecificAlloc();
              }

              void
              Store(char *server, char *method, char *url, char *data)
              {
                  Ns_UrlSpecificSet(server, method, url, myId,
                  data, 0, NULL);
              }

              char *
              Fetch(char *server, char *method, char *url)
              {
                  char *data;

                  data = Ns_UrlSpecificGet(server, method, url, myId);
                  return (char *) data;
              }

       Ns_UrlSpecificDestroy(server, method, url, id, flags)

              The Ns_UrlSpecificDestroy function deletes URL-specific data previously stored with
              Ns_UrlSpecificSet with the same method/URL combination  and  the  same  inheritance
              setting.

              An  id of -1 matches all ids. For example, Ns_UrlSpecificDestroy("myserver", "GET",
              "/", -1, NS_OP_RECURSE) removes all data for the method GET for server "myserver".

              The flags argument can be:

              NS_OP_NODELETE - If set, the deletefunc specified in Ns_UrlSpeciciSet is run.

              NS_OP_RECURSE - If set, then data for all URLs more specific than the passed-in URL
              are also destroyed.

              NS_OP_NOINHERIT  - If set, data that was stored with this flag in Ns_UrlSpecificSet
              will be deleted.  If not set, the data stored without this flag will be deleted.

       Ns_UrlSpecificGet(server, method, url, id)

              The Ns_UrlSpecificGet function retrieves the best match that it can find for in the
              URL subspace identified by id that the passed-in URL matches. For instance, suppose
              you had previously registered a handle/method/url/id combination of {myserver, GET,
              /,  1}  and {myserver, GET, /inventory, 1}. The following call would match the data
              registered at {myserver, GET, /inventory, 1}:

              Ns_UrlSpecificGet("myserver", "GET", "/inventory/RJ45", 1)

       Ns_UrlSpecificGetExact(server, method, url, id, flags)

              Retrieves stored data for the exact method/URL/id combination  specified  that  was
              stored with the same inheritance setting.

              If   the   flags  argument  is  set  to  NS_OP_NOINHERIT,   the  data  stored  with
              NS_OP_NOINHERIT will be retrieved.  If the flags argument is set  to  0,  the  data
              stored without NS_OP_NOINHERIT will be retrieved.

       Ns_UrlSpecificGetFast(server, method, url, id)

              Same as Ns_UrlSpecificGet but does not support wildcards, making it much faster.

       Ns_UrlSpecificSet(server, method, url, id, data, flags, deletefunc)

              The Ns_UrlSpecificSet function stores data in memory, allowing subsequent retrieval
              using handle, method, url, id, and inheritance flag.

              The flags argument can be NS_OP_NOINHERIT or NS_OP_NODELETE. You can store two sets
              of  data  based  on the same handle, method, url, and id combination-- one set with
              inheritance on and one set with inheritance off. If  the  NS_OP_NOINHERIT  flag  is
              set,  the data is stored based on the exact URL. If NS_OP_NOINHERIT is omitted, the
              data is stored based on the specified URL and any  URL  below  it.  In  this  case,
              Ns_UrlSpecificGetExact will match to the closest URL when retrieving the data.

              The   deletefunc   argument   is   called  with  data  as  an  argument  when  this
              handle/url/method/id combination is re-registered or deleted, or when  this  server
              shuts down. unless NS_OP_NODELETE is set.

              Normally,  calling  Ns_UrlSpecificSet  on  a handle/url/method/id combination which
              already has an operation registered for it causes the previous  operation's  delete
              procedure to be called. You can override this behavior by adding the NS_OP_NODELETE
              flag.

SEE ALSO

       nsd(1), info(n)

KEYWORDS