Ns_UrlSpecific(3aolserver)				   AOLserver Library Procedures 				Ns_UrlSpecific(3aolserver)

__________________________________________________________________________________________________________________________________________________

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 com-
	      bination 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

AOLserver								4.0						Ns_UrlSpecific(3aolserver)