$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
int Ns_AbsoluteUrl( Ns_DString *pds, char *url, char *baseurl );
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".
int Ns_AdpRegisterParser ( char *name, Ns_AdpParserProc *newParserProc ); typedef void (Ns_AdpParserProc)(Ns_DString *out, char *in);
The output should be formatted as a series of concatenated "chunks". A
chunk is a string of the format:
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.
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.
The Ns_Set returned is located in the configuration data. You do not
need to free the set and you must not alter it.
The space for the string returned is located in the configuration
data. You must not deallocate or modify the string.
The space for the string returned is located in the configuration
data. You must not deallocate or modify the string.
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.
For example, Ns_NextWord("abc def") returns a pointer to the 'd' in
that string.
<
<
>
>
&
&
It returns a pointer to the trace.
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
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.
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.
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";
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.
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.
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_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_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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.