Plug-in developers can define the USE_NSAPI_VERSION macro before including the nsapi.h header file to request a particular version of NSAPI. The requested NSAPI version is encoded by multiplying the major version number by 100 and then adding the resulting value to the minor version number. For example, the following code requests NSAPI 3.2 features:
#define USE_NSAPI_VERSION 302 /* We want NSAPI 3.2 (Web Server 6.1) */ #include "nsapi.h"
To develop a plug-in that is compatible across multiple server versions, define USE_NSAPI_VERSION as the highest NSAPI version supported by all of the target server versions.
The following table lists server versions and the highest NSAPI version supported by each.
Table 6–2 NSAPI Versions Supported by Different Servers
Server Version |
NSAPI Version |
---|---|
iPlanet Web Server 4.1 |
3.0 |
iPlanet Web Server 6.0 |
3.1 |
Netscape Enterprise Server 6.0 |
3.1 |
Netscape Enterprise Server 6.1 |
3.1 |
Sun ONE Application Server 7.0 |
3.1 |
Sun ONE Web Server 6.1 |
3.2 |
Sun Java System Web Proxy Server 4.0 |
3.3 |
Sun Java System Web Server 7.0 Update 2 |
3.3 |
Do not request a version of NSAPI higher than the highest version supported by the nsapi.h header that the plug-in is being compiled against. Additionally, to use USE_NSAPI_VERSION, you must compile against an nsapi.h header file that supports NSAPI 3.2 or higher.
int USE_NSAPI_VERSION
The following code can be used when building a plug-in designed to work with iPlanet Web Server 4.1 and Sun Java System Web Server 7.0 Update 2:
#define USE_NSAPI_VERSION 300 /* We want NSAPI 3.0 (Web Server 4.1) */ #include "nsapi.h"
NSAPI_RUNTIME_VERSION() Macro, NSAPI_VERSION() Macro
The util_can_exec function checks that a specified file can be executed, returning either a 1 (executable) or a 0. The function checks whether the file can be executed by the user with the given user and group ID.
Use this function before executing a program using the exec system call.
int util_can_exec(struct stat *finfo, uid_t uid, gid_t gid);
1 if the file is executable, or 0 if the file is not executable.
stat *finfo is the stat structure associated with a file.
uid_t uid is the UNIX user ID.
gid_t gid is the UNIX group ID. Together with uid, this value determines the permissions of the UNIX user.
util_env_create() Function, util_getline() Function, util_hostname() Function
The util_chdir2path function changes the current working directory. Because a server process can service multiple requests concurrently but has only a single current working directory, this function should not be used.
int util_chdir2path(char *path);
0 if the directory change succeeds, or -1 if the directory can not be changed.
char *path is the name of a directory.
The parameter must be a writable string.
The util_cookie_find function finds a specific cookie in a cookie string and returns its value.
char *util_cookie_find(char *cookie, char *name);
If successful, this function returns a pointer to the NULL-terminated value of the cookie. Otherwise, this function returns NULL. This function modifies the cookie string parameter by null-terminating the name and value.
char *cookie is the value of the Cookie: request header.
char *name is the name of the cookie whose value is to be retrieved.
The util_env_find function locates the string denoted by a name in a specified environment and returns the associated value. Use this function to find an entry in an environment.
char *util_env_find(char **env, char *name);
The value of the environment variable if the string is found, or NULL if the string was not found.
char **env is the environment.
char *name is the name of an environment variable in env.
util_env_replace() Function, util_env_str() Function, util_env_free() Function, util_env_create() Function
The util_env_create function creates and allocates the environment specified by env and returns a pointer to the environment. If the parameter env is NULL, the function allocates a new environment. Use util_env_create to create an environment when executing a new program.
#include <base/util.h> char **util_env_create(char **env, int n, int *pos);
A pointer to an environment.
char **env is the environment or NULL.
int n is the maximum number of environment entries that you want in the environment.
int *pos is an integer that keeps track of the number of entries used in the environment.
util_env_replace() Function, util_env_str() Function, util_env_free() Function, util_env_find() Function
The util_env_free function frees a specified environment. Use this function to deallocate an environment you created using the function util_env_create.
void util_env_free(char **env);
void
char **env is the environment to be freed.
util_env_replace() Function, util_env_str() Function, util_env_create() Function, util_env_create() Function
The util_env_replace function replaces the occurrence of the variable denoted by a name in a specified environment with a specified value. Use this function to change the value of a setting in an environment.
void util_env_replace(char **env, char *name, char *value);
void
char **env is the environment.
char *name is the name of a name-value pair.
char *value is the new value to be stored.
util_env_str() Function, util_env_free() Function, util_env_create() Function, util_env_create() Function
The util_env_str function creates an environment entry and returns the entry. This function does not check for non-alphanumeric symbols in the name, for example, the equal sign “=”. You can use this function to create a new environment entry.
char *util_env_str(char *name, char *value);
A newly allocated string containing the name-value pair.
char *name is the name of a name-value pair.
char *value is the new value to be stored.
util_env_replace() Function, util_env_free() Function, util_env_create() Function, util_env_create() Function
The util_getline function scans the specified file buffer to find a line feed or carriage return/line feed terminated string. The string is copied into the specified buffer, and NULL-terminates it. The function returns a value that indicates whether the operation stored a string in the buffer, encountered an error, or reached the end of the file.
Use this function to scan lines out of a text file, such as a configuration file.
int util_getline(filebuf *buf, int lineno, int maxlen, char *line);
0 if successful, line contains the string.
1 if the end of file is reached, line contains the string.
-1 if an error occurs, line contains a description of the error.
filebuf *buf is the file buffer to be scanned.
int lineno is used to include the line number in the error message when an error occurs. The caller is responsible for making sure the line number is accurate.
int maxlen is the maximum number of characters that can be written into l.
char *l is the buffer in which to store the string. The user is responsible for allocating and deallocating line.
The util_hostname function retrieves the local host name and returns it as a string. If the function cannot find a fully qualified domain name, it returns NULL. You can reallocate or free this string. Use this function to determine the name of the system you are on.
char *util_hostname(void);
A string containing the name, if a fully qualified domain name is found. Otherwise, the function returns NULL.
None
The util_is_mozilla function checks whether a specified user-agent header string is a Mozilla browser of at least a specified revision level. The function returns a 1 if the level matches, and 0 otherwise. This function uses strings to specify the revision level to avoid ambiguities such as 1.56 > 1.5.
int util_is_mozilla(char *ua, char *major, char *minor);
1 if the user-agent is a Mozilla browser, or 0 if the user-agent is not a Mozilla browser.
char *ua is the user-agent string from the request headers.
char *major is the major release number, found to the left of the decimal point.
char *minor is the minor release number, found to the right of the decimal point.
util_is_url() Function, util_later_than() Function
The util_is_url function checks whether a string is a URL, returns 1 if the string is a URL and 0 otherwise. The string is a URL if it begins with alphabetic characters followed by a colon (:).
int util_is_url(char *url);
1 if the string specified by url is a URL, or 0 if the string specified by url is not a URL.
char *url is the string to be examined.
util_is_mozilla() Function, util_later_than() Function
The util_itoa function converts a specified integer to a string, and returns the length of the string. Use this function to create a textual representation of a number.
int util_itoa(int i, char *a);
The length of the string created.
int i is the integer to be converted.
char *a is the ASCII string that represents the value. The user is responsible for the allocation and deallocation of a. The string should be at least 32 bytes long.
The util_later_than function compares the date specified in a time structure against a date specified in a string. If the date in the string is later than or equal to the one in the time structure, the function returns 1. Use this function to handle RFC 822, RFC 850, and ctime formats.
int util_later_than(struct tm *lms, char *ims);
1 if the date represented by ims is the same as or later than that represented by the lms, or 0 if the date represented by ims is earlier than that represented by the lms.
tm *lms is the time structure containing a date.
char *ims is the string containing a date.
The util_sh_escape function parses a specified string and places a backslash (\) in front of any shell-special characters, returning the resulting string. Use this function to ensure that strings from clients do not cause a shell to do anything unexpected.
The shell-special characters are the space plus the following characters:
&;`'"|*?~<>^()[]{}$\#!
char *util_sh_escape(char *s);
A newly allocated string.
char *s is the string to be parsed.
The util_snprintf function formats a specified string, using a specified format, into a specified buffer using the printf-style syntax and performs bounds checking. This function returns the number of characters in the formatted buffer.
For more information, see the documentation on the printf function for the runtime library of your compiler.
int util_snprintf(char *s, int n, char *fmt, ...);
The number of characters formatted into the buffer.
char *s is the buffer to receive the formatted string.
int n is the maximum number of bytes allowed to be copied.
char *fmt is the format string. The function handles only %d and %s strings; it does not handle any width or precision strings.
... represents a sequence of parameters for the printf function.
util_sprintf() Function, util_vsnprintf() Function, util_vsprintf() Function
The util_sprintf function formats a specified string, using a specified format, into a specified buffer, using the printf-style syntax without bounds checking. This function returns the number of characters in the formatted buffer.
Because util_sprintf does not perform bounds checking, use this function only if you are certain that the string fits the buffer. Otherwise, use the function util_snprintf. For more information, see the documentation on the printf function for the runtime library of your compiler.
int util_sprintf(char *s, char *fmt, ...);
The number of characters formatted into the buffer.
char *s is the buffer to receive the formatted string.
char *fmt is the format string. The function handles only %d and %s strings. The function does not handle any width or precision strings.
... represents a sequence of parameters for the printf function.
char *logmsg; int len; logmsg = (char *) MALLOC(256); len = util_sprintf(logmsg, "%s %s %s\n", ip, method, uri);
util_snprintf() Function, util_vsnprintf() Function, util_vsprintf() Function
The util_strcasecmp function performs a comparison of two alphanumeric strings and returns a -1, 0, or 1 to signal which string is larger or the strings are identical.
The comparison is not case sensitive.
int util_strcasecmp(const char *s1, const char *s2);
1 if s1 is greater than s2.
0 if s1 is equal to s2.
-1 if s1 is less than s2.
char *s1 is the first string.
char *s2 is the second string.
The util_strftime function translates a tm structure, which is a structure describing a system time, into a textual representation. util_strftime is a thread-safe version of the standard strftime function.
int util_strftime(char *s, const char *format, const struct tm *t);
The number of characters placed into s, not counting the terminating NULL character.
char *s is the string buffer to put the text into. This function does not perform bounds checking, so you must make sure that the buffer is large enough for the text of the date.
const char *format is a format string, similar to printf string in that it consists of text with certain %x substrings. You can use the constant HTTP_DATE_FMT to create date strings in the standard Internet format. For more information, see the documentation on the printf function for the runtime library of your compiler. For more information on time formats, see the Sun Java System Web Server 7.0 Update 3 Administrator’s Configuration File Reference.
const struct tm *t is a pointer to a calendar time (tm) structure, usually created by the function system_localtime or system_gmtime.
system_localtime() Function, system_gmtime() Function
The util_strncasecmp function performs a comparison of the first n characters in the alphanumeric strings and returns a -1, 0, or 1 to signal which string is larger or that the strings are identical.
The function’s comparison is not case-sensitive.
int util_strncasecmp(const char *s1, const char *s2, int n);
1 if s1 is greater than s2.
0 if s1 is equal to s2.
-1 if s1 is less than s2.
char *s1 is the first string.
char *s2 is the second string.
int n is the number of initial characters to compare.
The util_uri_escape function converts any special characters in the URI into the URI format. This format is %XX, where XX is the hexadecimal equivalent of the ASCII character. This function returns the escaped string. The special characters are %?#:+&*"<>, space, carriage return, and line feed.
Use util_uri_escape before sending a URI back to the client.
char *util_uri_escape(char *d, char *s);
The string possibly newly allocated with escaped characters replaced.
char *d is a string. If d is not NULL, the function copies the formatted string into d and returns it. If d is NULL, the function allocates a properly sized string and copies the formatted special characters into the new string, then returns it.
The util_uri_escape function does not check bounds for the parameter d. Therefore, if d is not NULL, it should be at least three times as large as the string s.
char *s is the string containing the original unescaped URI.
util_uri_is_evil() Function, util_uri_parse() Function, util_uri_unescape() Function
The util_uri_is_evil function checks a specified URI for insecure path characters. Insecure path characters include //, /./, /../ and/., /.. (also for Windows./) at the end of the URI. Use this function to see whether a URI requested by the client is insecure.
int util_uri_is_evil(char *t);
1 if the URI is insecure, or 0 if the URI is secure.
char *t is the URI to be checked.
util_uri_parse() Function, util_uri_escape() Function
The util_uri_parse function converts //, /./, and /*/../ into / in the specified URI, where * is any character other than /. You can use this function to convert a URI’s bad sequences into valid ones. First, use the function util_uri_is_evil to determine whether the function has a bad sequence.
void util_uri_parse(char *uri);
void
char *uri is the URI to be converted.
util_uri_is_evil() Function, util_uri_unescape() Function
The util_uri_unescape function converts the encoded characters of a URI into their ASCII equivalents. Encoded characters appear as %XX, where XX is a hexadecimal equivalent of the character.
You cannot use an embedded null in a string, because NSAPI functions assume that a null is the end of the string. Therefore, passing Unicode-encoded content through an NSAPI plug-in does not work.
void util_uri_unescape(char *uri);
void
char *uri is the URI to be converted.
util_uri_escape() Functionutil_uri_is_evil() Function, util_uri_parse() Function
The util_vsnprintf function formats a specified string, using a specified format, into a specified buffer using the vprintf-style syntax and performs bounds checking. This function returns the number of characters in the formatted buffer.
For more information, see the documentation on the printf function for the runtime library of your compiler.
int util_vsnprintf(char *s, int n, register char *fmt, va_list args);
The number of characters formatted into the buffer.
char *s is the buffer to receive the formatted string.
int n is the maximum number of bytes allowed to be copied.
register char *fmt is the format string. The function handles only %d and %s strings. This function does not handle any width or precision strings.
va_list args is an STD argument variable obtained from a previous call to va_start.
util_sprintf() Function, util_vsprintf() Function
The util_vsprintf function formats a specified string, using a specified format, into a specified buffer using the vprintf-style syntax without bounds checking. This function returns the number of characters in the formatted buffer.
For more information, see the documentation on the printf function for the runtime library of your compiler.
int util_vsprintf(char *s, register char *fmt, va_list args);
The number of characters formatted into the buffer.
char *s is the buffer to receive the formatted string.
register char *fmt is the format string. The function handles only %d and %s strings; it does not handle any width or precision strings.
va_list args is an STD argument variable obtained from a previous call to va_start.