GetServerVariable - ISAPI handler callback equivalent to CGI environment
/* given cb = either an extension control block or a filter context */ HCONN connid = (extension) ? cb->ConnID : cb; LPSTR name; /* of variable to enquire */ char buffer[BUFSIZ]; /* choose suitable size */ DWORD bufsiz = BUFSIZ;
if ((*(cb->GetServerVariable))( connid, name, (LPVOID) buffer, &bufsiz )) { /* buffer contains answer, '\0'-terminated; bufsiz contains its length */ } else { /* handle failure: named variable not available or too big for buffer */ }
GetServerVariable determines the value of a named resource and, if enough space has been provided to hold the value, returns this value to the caller. Some of the eligible resources are connection-specific, others are properties of the server handling the connection.
Most variables a CGI script would access via the environment are provided by GetServerVariable. Note, however, that an extension receives its REQUEST_METHOD, QUERY_STRING, PATH_INFO and PATH_TRANSLATED as fields of the EXTENSION_CONTROL_BLOCK, sparing it the need to call GetServerVariable to obtain them.
First parameter is a connection identifier; for the GetServerVariable of an extension control block, this is the ConnID field of the block; for the GetServerVariable of a filter context, this is the filter context itself.
Second argument is a '\0'-terminated char array (i.e. a C string) naming the variable to be queried. Supported names are listed below. Further names are supported based on the headers of the HTTP request being handled: each header's value can be obtained by calling GetServerVariable with a name starting ``HTTP_'' and continuing thereafter with the header name, coerced to upper case and with any dashes replaced by undescores: e.g. ``User-Agent'' becomes ``HTTP_USER_AGENT''. Some names of the latter kind are also listed below, where there is a standard meaning for the relevant header. See also the ENOENT error code on failure, below.
Third argument, buffer, is a pointer to the start of an area of memory; fourth argument, bufsiz, is a pointer to an integer variable whose value, when GetServerVariable is called, is the number of bytes of space in the area of memory pointed to by buffer. GetServerVariable shall not write outside the area of memory indicated by buffer and bufsiz. On successful return from GetServerVariable, buffer shall contain the value of the variable queried and bufsiz shall have been updated to the number of bytes needed to record the variable's value.
Valid variable names (values for the second argument, name) and the meanings of their values (which should be interpreted as C strings unless otherwise stated) are listed below. First, the values corresponding to environment variables in the CGI specification (see http://hoohoo.ncsa.uiuc.edu/cgi/env.html):
The variety of authentication used, if any, else an empty string. Possible values are ``kerberos'', ``user'', ``SSL/PCT'', ``Basic'' and ``NTLM''.
The total number of bytes the client has POSTed (after headers) as input to the ISAPI handler (for extensions, this is available as the cbTotalBytes field of the extension control block).
The MIME type using which the handler should interpret the data POSTed by the client (for extensions, this is available as the lpszContentType of the extension control block).
A comma-separated list of MIME types the client is ready to accept as response (as for a CGI script).
The trailing part (if any) of the URL, requested by the client, after the URL of the script handling the request but before the query string (if any). Extensions can also access this as the lpszPathInfo field of the extension control block.
The local file-system path to which the URL has been expanded (also available to extensions as the lpszPathTranslated field of the extension control block).
The information following the `?' (if any) in the requested URL; or an empty string (also available, to extensions, as the lpszQueryString field of the extension control block).
IP address of the client (directly) making the request. Note that, if the request has come via a proxy, firewall or similar gateway, this is the IP address of the gateway, not originating user.
The user name supplied by the client and authenticated by the server; or an empty string if the user is anonymous.
The HTTP request method (usually ``GET'' or ``POST''), also available to extensions as the lpszMethod field of the extension control structure.
The virtual path of the script processing the request, suitable for use in self-referencing URLs.
The hostname, or IP address, of the server, as it should appear in
self-referencing URLs (or the <BASE HREF="..."
> tag in the HEAD of an HTML document).
The TCP/IP port number on which the request was received.
The name and version of the protocol by which the request is being made (e.g. ``HTTP/1.1'').
The name and version of the web server under which the ISAPI handler is running; format ``name/version''.
Note that the REMOTE_IDENT CGI environment variable has no equivalent; but see below for Zeus extensions to ISAPI covering other CGI environment variables. The following non-CGI variables appear in the ISAPI specification:
The HTTP_* header fields of the HTTP request. It is delivered as a '\0'-terminated string with the individual headers on separate lines.
All the header fields from the HTTP request, as they were sent by the client.
The metabase path of the application.
The local file-system path corresponding to the metabase path.
The password the user supplied, if using `basic authentication', in the authentication dialog box.
The username supplied by the user in the authentication dialog box.
A unique identifier for a client certificate: can be used as a signature for the whole client certificate.
Raw data, to be read as a bit-field: if bit 0 is set, a client certificate is present; if bit 1 is set, the server does not recognize the Certifying Authority of this certificate.
The `issuer' field of the client certificate: this identifies the Certifying Authority who issued it.
Number of bits in the client certificate's key.
Number of bits in the server's certificate's key.
The serial number of the client certificate (supplied by the issuer).
The `issuer' field of the server certificate.
The `subject' field of the server certificate, identifying the web site serving the request being processed.
The `subject' field of the client certificate, identifying the client.
A string indicating security of client's connection: will be ``on'' if the client connected using SSL, otherwise (either an empty string or) the string ``off''.
Number of bits in the bulk encryption key used to mediate SSL.
Number of effective bits in the bulk encryption key used to mediate SSL.
The `issuer' field of the server's certificate.
The `subject' field of the server's certificate.
The ID of the instance of the web server which is handling the request. This can be used to retrieve the retrieve, from the meta-base, information about the web-server instance.
The metabase-path of the web server instance.
Either ``0'' for an insecure connection or ``1'' for a secure one.
The URL requested by the client, with its query-parameters (if any) stripped, as parsed by the web server on receiving the request.
The following further variables are supported by ZWS:
The revision of the interface being supported: e.g. ``ISAPI/4.0''.
The hostname of the client, if available.
The URL from which the client came to the URL being processed by the present ISAPI handler.
The user agent (e.g. web browser) being used by the client.
The (administration) name of the virtual server handling the request.
Returns TRUE on success. Returns FALSE on failure; ZWS sets the ANSI C errno variable to indicate the cause of failure (under IIS, the GetLastError function provides equivalent information). The following values indicate causes of failure:
Invalid parameter (IIS: ERROR_INVALID_PARAMETER) or unsupported variable name (IIS: ERROR_INVALID_INDEX). A name is unsupported if it does not begin ``HTTP_'' and is not listed above.
No such variable (IIS: ERROR_NO_DATA). This is only returned for the HTTP_* variables, when the given variable is unavailable: for any other supported variable name, GetServerVariable will succeed, returning an empty string (i.e. the first byte of buffer shall have the value '\0') if there is no data available for the given variable.
Insufficient space in buffer (IIS: ERROR_INSUFFICIENT_BUFFER). In this case, although GetServerVariable failed, it has set bufsiz to the amount of space needed for the value of the variable: caller can malloc this much space and try again.
isapi(7),
HttpExtensionProc(3),
HttpFilterProc(3),
EXTENSION_CONTROL_BLOCK(5),
HTTP_FILTER_CONTEXT(5).
$ZEUSHOME/web/include/httpext.h $ZEUSHOME/web/include/httpfilt.h $ZEUSHOME/web/include/wintypes.h $ZEUSHOME/webadmin/docroot/docs/modules/isapi/*.html
In ZWS 3.3.7 and earlier one could query the variable ``COOKIE'' to fetch the contents of a ``Cookie: ...'' header. This is deprecated: code relying on this should be converted to use ``HTTP_COOKIE'', as for access to any other header value.
Copyright (C) 2000-2001 Zeus Technology Limited. All rights reserved.