Data Structure C Library Functions
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
Append the specified argument plus a terminating null character to the
end of the Ns_DString. It is useful for making strings like:
"foo\0bar\0baz\0". It returns the string associated with the current
Ns_DString.
Export the string of an Ns_DString
Syntax
char *Ns_DStringExport(
Ns_DString *src
);
Description
The Ns_DStringExport function returns the current Ns_DString string
and leaves the Ns_DString in the initialized state. The string
returned needs to be freed eventually with Ns_Free.
Examples
Ns_DString ds;
char *stringdest;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "foo");
stringdest = Ns_DStringExport(&ds);
/* do something with `stringdest' */
Ns_Free(stringdest);
Free any allocated memory used by an Ns_DString
Syntax
void Ns_DStringFree(
Ns_DString *dsPtr
);
Description
The Ns_DStringFree function frees any memory associated with an
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 */
Initialize an Ns_DString
Syntax
void Ns_DStringInit(
Ns_DString *dsPtr
);
Description
Before using an Ns_DString, you must initialize it with
Ns_DStringInit. Storage for a Ns_DString is often on the stack in the
calling function. The example below shows a typical usage.
Examples
int MyFunctions(int a, int b)
{
Ns_DString ds;
Ns_DStringInit(&ds);
/* ds is now initialized and ready to pass to
another function */
...
}
Return the current length of an Ns_DString
Syntax
int Ns_DStringLength(
Ns_DString *dsPtr
);
Description
The Ns_DStringLength macro returns the current length of the
Ns_DString.
Examples
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "");
printf("len=%d\n", Ns_DStringLength(&ds));
Ns_DStringFree(&ds); /* finished with dstring */
Append n-characters of a string to an Ns_DString
Syntax
char *Ns_DStringNAppend(
Ns_DString *dsPtr,
char *string,
int length
);
Description
The Ns_DStringNAppend function appends a string up to the specified
number of characters, plus a terminating null character.( Unlike the
Tcl_DStringAppend function, which only works with string data, the
AOLserver Ns_DStringNAppend function can append binary data.) 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
The resulting Ns_DString in this example, ds, would contain "foo\0"
and have a length of 3:
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringNAppend(&ds, "fooasdf", 3);
printf("%s\n", ds.string);
Ns_DStringFree(&ds); /* finished with dstring */
If you need a null-terminated list of null-terminated strings, such as
"foo\0bar\0\0", you would add one to the length of the appended
strings to get the extra terminating null character. For example:
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringNAppend(&ds, "foo", 4);
Ns_DStringNAppend(&ds, "bar", 4);
Append a formatted string to an Ns_DString
Syntax
char *Ns_DStringPrintf(
Ns_DString *dsPtr,
char *fmt,
...
);
Description
The Ns_DStringPrintf function appends a string that has been created
by calling the sprintf function with the given format and optional
arguments. This function currently uses a fixed length buffer of 1024
characters to sprintf() the data before appending to the Ns_DString.
Examples
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringPrintf(&ds, "/path%d", getpid());
/* do something with dstring */
printf ("%s\n", ds.string);
Ns_DStringFree(&ds); /* finished with dstring */
Truncate an Ns_DString
Syntax
void Ns_DStringTrunc(
Ns_DString *dsPtr,
int length
);
Description
The Ns_DStringTrunc function truncates an Ns_DString to the given
length. Unlike Ns_DStringFree, which truncates the Ns_DString to
length 0 and frees any memory that may have been allocated on the
heap, Ns_DStringTrunc allows you to truncate the string to any length.
It maintains any memory allocated on the heap. This function is useful
in a loop where the Ns_DString is likely to overflow the static space
each time through. Using Ns_DStringTrunc instead of Ns_DStringFree
will avoid having the Ns_DString call malloc to obtain the addition
space in each iteration. You will need to call Ns_DStringFree
eventually to free any space that may have been allocated for the
Ns_DString.
Examples
Ns_DString ds;
int i;
Ns_DStringInit(&ds);
for (i=0; i < 50; i++) {
Ns_DStringPrintf(&ds, "%s%d", "aBigString", i);
/* do something with the dstring constructed above*/
Ns_DStringTrunc(&ds, 0);
}
Ns_DStringFree(&ds); /* finished with dstring */
Return the current value of an Ns_DString
Syntax
char *Ns_DStringValue(
Ns_DString *dsPtr
);
Description
The Ns_DStringValue macro returns a pointer to the current value of an
Ns_DString. This may be a pointer to the Ns_DString's static space or
to a string allocated on the heap if the static space has overflowed.
It is not safe to use the value returned by this macro after an
intervening call to Ns_DStringAppend because the Ns_DString string
could overflow to or move within the heap.
Examples
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "foo");
/* do something with the dstring */
printf ("%s\n", Ns_DStringValue(&ds));
Ns_DStringFree(&ds); /* finished with dstring */
Append a variable number of strings to an Ns_DString
Syntax
char *Ns_DStringVarAppend(
Ns_DString *dsPtr,
...
);
Description
The Ns_DStringVarAppend function appends a variable number of strings
to an Ns_DString. The list must end with NULL.
Examples
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringVarAppend(&ds, "foo", "bar", NULL);
/* do something with the dstring */
printf ("%s\n", ds.string);
Ns_DStringFree(&ds); /* finished with dstring */
Parse query data into Ns_Set
Syntax
int Ns_QueryToSet (
char* query,
Ns_Set* set
);
Description
Parse query data (such as "a=b&c=d&jkl=rew") into an Ns_Set.
Return unique integer to use in other functions
Syntax
int Ns_ServerSpecificAlloc(void);
Description
The Ns_ServerSpecificAlloc function returns a unique integer to be
used in the Ns_ServerSpecific* storage functions, below.
Delete server-specific data
Syntax
void *Ns_ServerSpecificDestroy(
char *handle,
int id,
int flags
);
Description
The Ns_ServerSpecificDelete function deletes server-specific data
previously stored with Ns_ServerSpecificSet. The flags argument can be
NS_OP_NODELETE or NS_OP_RECURSE. NS_OP_NODELETE determines whether the
deletefunc specified in Ns_ServerSpecificSet is called. NS_OP_RECURSE
determines whether this operation is applied recursively. An id of -1
matches all ids.
Retrieve server-specific data
Syntax
void *Ns_ServerSpecificGet(
char *handle,
int id
);
Description
The Ns_ServerSpecificGet function retrieves server-specific data
stored previously with the Ns_ServerSpecificSet function.
Store server-specific data for subsequent retrieval
Syntax
void Ns_ServerSpecificSet(
char *handle,
int id,
void *data,
int flags,
void (*deletefunc) (void *)
);
Description
The Ns_ServerSpecificSet function stores server-specific data,
allowing subsequent retrieval using handle and id. The flags argument
can be NS_OP_NODELETE. The deletefunc function is called with data as
an argument when this handle/id combination is re-registered or
deleted, or when this server shuts down, unless NS_OP_NODELETE is set.
Create a new copy of a set
Syntax
Ns_Set *Ns_SetCopy(
Ns_Set *old
);
Description
This function returns a newly allocated set that contains the same
fields as the original set. The two sets share no memory and can be
freed individually.
Examples
Ns_Set *setA;
Ns_Set *setB;
setA = Ns_SetCreate("setA");
Ns_SetPut(setA, "foo", "foovalue");
setB = Ns_SetCopy(setA);
Ns_SetFree(setA);
/* do something with setB */
Ns_SetFree(setB);
Create a new Ns_Set
Syntax
Ns_Set *Ns_SetCreate(
char *name
);
Description
The Ns_SetCreate function allocates and returns a pointer to a new
Ns_Set. You must eventually call Ns_SetFree to release the memory used
by the set.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate(""); /* set name can be NULL */
Ns_SetPut(aSet, "foo", "foovalue");
/* do something with aSet */
Ns_SetFree(aSet);
Remove a field from a set by field index
Syntax
void Ns_SetDelete(
Ns_Set *set,
int index
);
Description
The Ns_SetDelete function removes the field of the given index from
the set. Any fields that follow the deleted field are moved up to keep
the set contiguous.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "foo", "foovalue");
Ns_SetPut(aSet, "bar", "barvalue");
Ns_SetDelete(aSet, 0); /* deletes foo->foovalue */
/* finish processing of aSet */
Ns_SetFree(aSet);
Remove a field from a set by key name
Syntax
void Ns_SetDeleteKey(
Ns_Set *set,
char *key
);
Description
The Ns_SetDeleteKey function removes the field whose key name matches
the given key. Any fields that follow the deleted field are moved up
to keep the set contiguous. If more than one field in the set has the
same key name, Ns_Set-DeleteKey deletes just the first field.
The Ns_SetIDeleteKey function is this function's case-insensitive
counterpart.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "foo", "foovalue");
Ns_SetPut(aSet, "bar", "barvalue");
Ns_SetDeleteKey(aSet, "foo"); /* deletes foo->foovalue */
/* finish processing of aSet */
Ns_SetFree(aSet);
Set socket driver callback
Syntax
int Ns_SetDriverProc (
Ns_Driver driver,
Ns_DrvId id,
void* proc
);
Description
Set a single socket driver callback procedure.
Wake up one waiting event
Syntax
int Ns_SetEvent(
Ns_Event * event
);
Description
Wake up one waiter, if there are any waiters to be awakened.
Locate the index of a field within an Ns_Set
Syntax
int Ns_SetFind(
Ns_Set *set,
char *key
);
Description
The Ns_SetFind function returns the index of the first field whose key
name matches the given key. The index is in C array order, i.e., 0 is
the index of the first field. If no fields are found, Ns_SetFind
returns -1. If more than one field in the set has the same key name,
Ns_SetFind returns just the first field index.
The Ns_SetIFind function is this function's case-insensitive
counterpart.
Examples
Ns_Set *aSet;
int index;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "Foo", "foovalue");
Ns_SetPut(aSet, "Bar", "barvalue");
index = Ns_SetFind(aSet, "Foo"); /* case sensitive search*/
if (index == -1) {
Ns_Log(Warning, "set key Foo not found");
} else {
Ns_Log(Notice, "Value for Foo is %s",
Ns_SetGet(aSet, "Foo"));
}
Ns_SetFree(aSet);
Free memory used by an Ns_Set
Syntax
void Ns_SetFree(
Ns_Set *set
);
Description
The Ns_SetFree function deletes all the fields of an Ns_Set and frees
the set structure. After calling Ns_SetFree, the set is no longer
valid and cannot be used.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate(""); /* set name can be NULL */
Ns_SetPut(aSet, "foo", "foovalue");
/* do something with aSet */
Ns_SetFree(aSet);
Return the value for a field
Syntax
char *Ns_SetGet(
Ns_Set *set,
char *key
);
Description
The Ns_SetGet function returns the value of the first field whose key
name matches the given key. Ns_SetGet returns NULL if no field is
found. If more than one field in the set has the same key name,
Ns_SetGet returns just the first field.
The Ns_SetIGet function is this function's case-insensitive
counterpart.
Examples
Ns_Set *aSet;
int index;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "Foo", "foovalue");
Ns_SetPut(aSet, "Bar", "barvalue");
Ns_Log(Notice, "Value for Foo is %s", Ns_SetGet(aSet, "Foo"));
Ns_SetFree(aSet);
Remove a field from a set by key name case-insentively
Syntax
void Ns_SetIDeleteKey(
Ns_Set *set,
char *key
);
Description
The Ns_SetIDeleteKey function is the case-insensitive counterpart to
the Ns_SetDeleteKey function. It removes the field whose key name
matches the given key case-insensitively. Any fields that follow the
deleted field are moved up to keep the set contiguous. If more than
one field in the set has the same key name, Ns_Set-IDeleteKey deletes
just the first field.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "foo", "foovalue");
Ns_SetPut(aSet, "bar", "barvalue");
Ns_SetIDeleteKey(aSet, "Foo"); /* deletes foo->foovalue */
/* finish processing of aSet */
Ns_SetFree(aSet);
Locate the index of a field case-insensitively
Syntax
int Ns_SetIFind(
Ns_Set *set,
char *key
);
Description
The Ns_SetIFind function is the case-insensitive counterpart of the
Ns_SetFind function. It returns the index of the first field whose key
name matches the given key case-insensitively. The index is in C array
order, i.e., 0 is the index of the first field. If no fields are
found, Ns_SetIFind returns -1. If more than one field in the set has
the same key name, Ns_SetIFind returns just the first field index.
Examples
Ns_Set *aSet;
int index;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "Foo", "foovalue");
Ns_SetPut(aSet, "Bar", "barvalue");
index = Ns_SetIFind(aSet, "foo"); /* case insensitive search*/
if (index == -1) {
Ns_Log(Warning, "set key foo not found");
} else {
Ns_Log(Notice, "Value for Foo is %s",
Ns_SetGet(aSet, "ooo"));
}
Ns_SetFree(aSet);
Return the value for a field case-insensitively
Syntax
char *Ns_SetIGet(
Ns_Set *set,
char *key
);
Description
The Ns_SetIGet function is the case-insensitive counterpart to the
Ns_SetGet function. It returns the value of the first field whose key
name matches the given key case-insensitively. Ns_SetIGet returns NULL
if no field is found. If more than one field in the set has the same
key name, Ns_SetIGet returns just the first field.
Examples
Ns_Set *aSet;
int index;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "Foo", "foovalue");
Ns_SetPut(aSet, "Bar", "barvalue");
Ns_Log(Notice, "Value for foo is %s", Ns_SetIGet(aSet, "foo"));
Ns_SetFree(aSet);
Check if a key in an Ns_Set is unique (case insensitive)
Syntax
int Ns_SetIUnique(
Ns_Set *set,
char *key
);
Description
Ns_SetIUnique returns 1 if the specified key is unique in the
specified set and 0 if it is not. The test for uniqueness is performed
case-insensitively. The case-sensitive counterpart to this function is
Ns_SetUnique.
For example, a client could send multiple "Accept:" headers which
would end up in the header set for the connection. Ns_SetIUnique would
then return 0 for the header set and the "Accept" key, because there
are multiple fields with the key "Accept".
Return the key name of a field
Syntax
char *Ns_SetKey(
Ns_Set *set,
int index
);
Description
The Ns_SetKey macro returns the field key name of the field at the
given index.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "foo", "foovalue");
Ns_SetPut(aSet, "bar", "barvalue");
printf("Key at index 0 is %s\n", Ns_SetKey(aSet, 0));
/* finish processing of aSet */
Ns_SetFree(aSet);
Return the index of the last element of a set
Syntax
void Ns_SetLast(
Ns_Set *set
);
Description
The Ns_SetLast function returns the index of the last element of the
set.
Locate a set by name in a set list
Syntax
Ns_Set *Ns_SetListFind(
Ns_Set **sets,
char *name
);
Description
The Ns_SetListFind function returns the set of the given name in
NULL-terminated array of sets most likely generated by the Ns_SetSplit
function.
Free a list of sets
Syntax
void Ns_SetListFree(
Ns_Set **sets
);
Description
The Ns_SetListFree function frees the sets in a NULL-terminated array
of sets and then frees the array itself. This function is normally
used to free a list of sets generated by Ns_SetSplit.
Merge two sets
Syntax
void Ns_SetMerge(
Ns_Set *high,
Ns_Set *low
);
Description
The Ns_SetMerge function appends any fields from the low set to the
high set if a field with the name key name does not already exist in
the high set.
Move fields from one set to the end of another
Syntax
void Ns_SetMove(
Ns_Set *to,
Ns_Set *from
);
Description
The Ns_SetMove function moves all fields from the from set to the end
of the to set. Ns_SetMove leaves from as a valid empty set.
Return the name of a set
Syntax
char *Ns_SetName(
Ns_Set *set
);
Description
The Ns_SetName function returns the name of the set, which may be
NULL.
Print the contents of a set to the AOLserver error log
Syntax
void Ns_SetPrint(
Ns_Set *set
);
Description
The Ns_SetPrint function prints all fields in a set to the AOLserver
error log file (or the terminal if the AOLserver is running in
foreground mode). It is useful for debugging.
Add a field to an Ns_Set
Syntax
int Ns_SetPut(
Ns_Set *set,
char *key,
char *value
);
Description
The Ns_SetPut function adds a new field to a set whose key name is the
given key and value is the given value. The value of the new field may
be NULL. The index of the new field is returned. Ns_SetPut strcpy's
the value and uses realloc's to adjust the size of the fields to
accommodate.
Examples
Ns_Set *aSet;
aSet = Ns_SetCreate("");
Ns_SetPut(aSet, "foo", "foovalue");
Ns_SetPut(aSet, "bar", "barvalue");
/* finish processing of aSet */
Ns_SetFree(aSet);
Set the value of a field
Syntax
void Ns_SetPutValue(
Ns_Set *set,
int index,
char *value
);
Description
The Ns_SetPutValue function sets the value of the field at the given
index to the new value. Any existing value of the affected field
overwritten. If the specified index is greater than the number of
fields in the set, this function does nothing.
Set function used by Ns_AuthorizeRequest
Syntax
typedef int (Ns_RequestAuthorizeProc) (
char *hServer,
char *method,
char *url,
char *authuser,
char *authpasswd,
char *peeraddr
);
void Ns_SetRequestAuthorizeProc(
char *hServer,
Ns_RequestAuthorizeProc *proc
);
Description
The Ns_SetRequestAuthorizeProc can be used to set the procedure used
by Ns_AuthorizeRequest to authenticate users accessing URLs on your
system. The authentication procedure must match the
Ns_RequestAuthorizeProc prototype and return one of the values listed
in the description of Ns_AuthorizeRequest above.
The AOLserver permissions module calls Ns_SetRequestAuthorizeProc at
startup to register its file-based permission system. If your site
already has a permission system in place, you could write a C module
whose initialization function opens a connected to the existing system
and then calls Ns_SetRequestAuthorizeProc to override the permission
module's authentication system.
Fill in request structure
Syntax
void Ns_SetRequestUrl (
Ns_Request* request,
char* url
);
Description
Fill in a request structure.
Return the current size of a set
Syntax
int Ns_SetSize(
Ns_Set *set
);
Description
The Ns_SetSize macro returns the current number of fields in a set.
Split a set into an array of new sets
Syntax
Ns_Set **Ns_SetSplit(
Ns_Set *set,
char sep
);
Description
The Ns_SetSplit function assumes that each key name in the fields of a
set contains a separating character. The fields of the set are
partitioned into new sets whose set names are the characters before
the separator and whose field key names are the characters after the
separator. For example, if the separator is `.' and the set has fields
whose key names are the following:
dog.sound
dog.food
cat.sound
cat.food
Ns_SetSplit would create two new sets named dog and cat, each
containing two fields whose key names are sound and food.
Ns_SetSplit returns a newly allocated NULL-terminated array of new
sets. The original set is left unaltered. The list of new sets can be
freed at once with the Ns_SetListFree function.
Truncate an Ns_Set
Syntax
void Ns_SetTrunc(
Ns_Set *set,
int size
);
Description
The Ns_SetTrunc function reduces the set to the first size key-value
pairs and frees the memory for the rest of the key-value pairs that
may have been in the set.
Examples
/* Eliminate the headers sent by a browser. */
Ns_SetTrunc(conn->headers, 0);
Check if a key in an Ns_Set is unique (case sensitive)
Syntax
int Ns_SetUnique(
Ns_Set *set,
char *key
);
Description
Ns_SetUnique returns 1 if the specified key is unique in the specified
set and 0 if it is not. The test for uniqueness is performed
case-sensitively. The case-insensitive counterpart to this function is
Ns_SetIUnique.
Update an Ns_Set value
Syntax
void Ns_SetUpdate (
Ns_Set* set,
char* key,
char* value
);
Description
Remove an item from the Ns_Set whose key = key, if one exists, and
then re-add the item with the new value.
Return the value of a field
Syntax
char *Ns_SetValue(
Ns_Set *set,
int index
);
Description
The Ns_SetValue macro returns the value of the field at the given
index.
Make an Ns_Set accessible through Tcl
Syntax
int Ns_TclEnterSet(
Tcl_Interp *interp,
Ns_Set *set,
int flags
);
Description
Ns_TclEnterSet makes an Ns_Set accessible through Tcl. The new set ID
is sprintf'ed directly into interp->result. It returns either NS_OK or
NS_ERROR. The flags can be one or more of the following:
NS_TCL_SET_TEMPORARY:
The set is temporary and private to the Tcl interpreter. The set ID
will be automatically deleted by Ns_TclDeAllocateInterp().
NS_TCL_SET_PERSISTENT:
The set can be accessed by any Tcl interpreter in the server and the
set ID will persist beyond the interpreter's next call to
Ns_TclDeAllocateInterp().
NS_TCL_SET_DYNAMIC:
The set was dynamically allocated for use by Tcl and will be
garbage-collected when the cooresponding set ID is deleted through
either Ns_TclFreeSet() or Ns_TclDeAllocateInterp().
Sets created by Tcl are normally DYNAMIC and TEMPORARY unless the
-persist option is used in the Tcl function when creating the set.
Examples
set = Ns_SetCreate(name);
return Ns_TclEnterSet(interp, set,
NS_TCL_SET_TEMPORARY | NS_TCL_SET_DYNAMIC);
Free an Ns_Set
Syntax
int Ns_TclFreeSet(
Tcl_Interp *interp,
char *setId
);
Description
Ns_TclFreeSet frees the set specified by the set ID for the
interpreter. If the set was initially entered with the
NS_TCL_SET_DYNAMIC flag with Ns_TclEnterSet, the actual Ns_Set is also
freed. Otherwise, the actual Ns_Set is not freed and the programmer is
responsible for eventually freeing it.
The ns_set free Tcl function calls this function.
Return the Ns_Set for the specified set ID
Syntax
Ns_Set *Ns_TclGetSet(
Tcl_Interp *interp,
char *setId
);
Description
Ns_TclGetSet returns the Ns_Set for the specified set ID. It returns
NULL if the set ID is invalid or if there is no such set ID. The
Ns_TclGetSet2 function does essentially the same thing, except the
Ns_Set is stored in a pointer.
Return the Ns_Set for the specified set ID in a pointer
Syntax
int Ns_TclGetSet2(
Tcl_Interp *interp,
char *setId,
Ns_Set **setPtr
);
Description
Ns_TclGetSet2 returns the Ns_Set in setPtr for the specified set ID.
It returns TCL_OK if the set ID is valid and found. It returns
TCL_ERROR if the set is invalid or can't be found.
Examples
if (Ns_TclGetSet2(interp, argv[1], &set) != TCL_OK {
return TCL_ERROR;
}
You can then access the Ns_Set pointed to by set.
Return unique integer to use in other functions
Syntax
int Ns_UrlSpecificAlloc(void);
Description
The Ns_UrlSpecificAlloc function returns a unique integer to be used
in the Ns_UrlSpecific* storage functions below.
Examples
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;
}
Delete URL-specific data
Syntax
void *Ns_UrlSpecificDestroy(
char *handle,
char *method,
char *url,
int id,
int flags
);
Description
The Ns_UrlSpecificDestroy function deletes URL-specific data
previously stored with Ns_UrlSpecificSet with the same method/URL
combination and the same inheritance setting.
The flags argument can be NS_OP_NODELETE, NS_OP_RECURSE, or
NS_OP_NOINHERIT. NS_OP_NODELETE determines whether the deletefunc
specified in Ns_UrlSpecificSet is called. If NS_OP_RECURSE is set,
then data for all URLs more specific than the passed-in URL is also
destroyed. If the flags argument specifies NS_OP_NOINHERIT in
Ns_UrlSpecificDestroy, the data stored with the NS_OP_NOINHERIT flag
in Ns_UrlSpecificSet will be deleted. If the flags argument does not
specify NS_OP_NOINHERIT, the data stored without the NS_OP_NOINHERIT
flag will be deleted.
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".
Retrieve URL-specific data
Syntax
void *Ns_UrlSpecificGet(
char *handle,
char *method,
char *url,
int id
);
Description
The Ns_UrlSpecificGet function retrieves the best match that it can
find. 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, then, would match
the data registered at {myserver, GET, /inventory, 1}:
Ns_UrlSpecificGet("myserver", "GET", "/inventory/RJ45", 1)
Examples
See the example for Ns_UrlSpecificAlloc.
Retrieve URL-specific data
Syntax
void *Ns_UrlSpecificGetExact(
char *handle,
char *method,
char *url,
int id,
int flags
);
Description
The Ns_UrlSpecificGetExact function retrieves stored data for the
exact specified method/URL/id combination and with the same
inheritance setting.
If the flags argument is set to NS_OP_NOINHERIT in
Ns_UrlSpecificGetExact, the data stored with the NS_OP_NOINHERIT flag
in Ns_UrlSpecificSet will be retrieved. If the flags argument is set
to 0, the data stored without the NS_OP_NOINHERIT flag will be
retrieved.
Store URL-specific data for subsequent retrieval
Syntax
void Ns_UrlSpecificSet(
char *handle,
char *method,
char *url,
int id,
void *data,
int flags
void (*deletefunc) (void *)
);
Description
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.
Examples
See the example for Ns_UrlSpecificAlloc.