ns_urlspecific(3)

NAME

Ns_UrlSpecificAlloc, Ns_UrlSpecificDestroy, Ns_UrlSpeci

ficGet, Ns_UrlSpecificGetExact, Ns_UrlSpecificGetFast, Ns_Url

SpecificSet - 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 proce

dures for example.

Ns_UrlSpecificAlloc()

Return a unique ID used to identify a unique virtu

al 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-spe

cific 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_Url

SpecificDestroy("myserver", "GET", "/", -1, NS_OP_RECURSE) re

moves 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 {my

server, GET, /, 1} and {myserver, GET, /inventory, 1}. The fol

lowing call would match the data registered at {myserver, GET,

/inventory, 1}:

Ns_UrlSpecificGet("myserver", "GET", "/invento

ry/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_NOIN

HERIT 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 memo

ry, 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 inheri

tance 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 spec

ified URL and any URL below it. In this case, Ns_UrlSpecificGe

tExact 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-regis

tered or deleted, or when this server shuts down. unless

NS_OP_NODELETE is set.

Normally, calling Ns_UrlSpecificSet on a han

dle/url/method/id combination which already has an operation reg

istered 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

Ns_UrlSpecific(3)