The EXTENSION_CONTROL_BLOCK structure has the following form:
typedef struct _EXTENSION_CONTROL_BLOCK {
DWORD cbSize; //IN
DWORD dwVersion //IN
HCONN ConnID; //IN
DWORD dwHttpStatusCode; //OUT
CHAR lpszLogData[HSE_LOG_BUFFER_LEN]; //OUT
LPSTR lpszMethod; //IN
LPSTR lpszQueryString; //IN
LPSTR lpszPathInfo; //IN
LPSTR lpszPathTranslated; //IN
DWORD cbTotalBytes; //IN
DWORD cbAvailable; //IN
LPBYTE lpbData; //IN
LPSTR lpszContentType; //IN
BOOL ( WINAPI * GetServerVariable )
( HCONN hConn,
LPSTR lpszVariableName,
LPVOID lpvBuffer,
LPDWORD lpdwSize );
BOOL ( WINAPI * WriteClient )
( HCONN ConnID,
LPVOID Buffer,
LPDWORD lpdwBytes,
DWORD dwReserved );
BOOL ( WINAPI * ReadClient )
( HCONN ConnID,
LPVOID lpvBuffer,
LPDWORD lpdwSize );
BOOL ( WINAPI * ServerSupportFunction )
( HCONN hConn,
DWORD dwHSERRequest,
LPVOID lpvBuffer,
LPDWORD lpdwSize,
LPDWORD lpdwDataType );
} EXTENSION_CONTROL_BLOCK, *LPEXTENSION_CONTROL_BLOCK;
The server communicates with the ISA via the EXTENSION_CONTROL_BLOCK.
The references to IN and OUT above indicates whether the member applies to messages to the extension (IN) or from the extension (OUT).
Members
The EXTENSION_CONTROL_BLOCK structure contains the following fields:
cbSize
The size of this structure.
dwVersion
The version information of HTTP_FILTER_REVISION. The HIWORD has the major version number and the LOWORD has the minor version number.
ConnID
A unique number assigned by the HTTP server. It must not be modified.
dwHttpStatusCode
The status of the current transaction when the request is completed. Can be one of the following:
lpszLogData
Buffer of size HSE_LOG_BUFFER_LEN. Contains a null-terminated log information string, specific to the ISA, of the current transaction. This log information will be entered in the HTTP server log. Maintaining a single log file with both HTTP server and ISA transactions is very useful for administration purposes.
lpszMethod
The method with which the request was made. This is equivalent to the CGI variable REQUEST_METHOD.
lpszQueryString
Null-terminated string containing the query information. This is equivalent to the CGI variable QUERY_STRING.
lpszPathInfo
Null-terminated string containing extra path information given by the client. This is equivalent to the CGI variable PATH_INFO.
lpszPathTranslated
Null-terminated string containing the translated path. This is equivalent to the CGI variable PATH_TRANSLATED.
cbTotalBytes
The total number of bytes to be received from the client. This is equivalent to the CGI variable CONTENT_LENGTH. If this value is 0xffffffff, then there are four gigabytes or more of available data. In this case, CHttpServerContext::ReadClient should be called until no more data is returned.
cbAvailable
The available number of bytes (out of a total of cbTotalBytes) in the buffer pointed to by lpbData. If cbTotalBytes is the same as cbAvailable the variable lpbData will point to a buffer which contains all the data sent by the client. Otherwise cbTotalBytes will contain the total number of bytes of data received. The ISA will then need to use the callback function CHttpServerContext::ReadClient to read the rest of the data (starting from an offset of cbAvailable).
lpbData
Points to a buffer of size cbAvailable that has the data sent by the client.
lpszContentType
Null-terminated string containing the content type of the data sent by the client. This is equivalent to the CGI variable CONTENT_TYPE.
GetServerVariable
This function copies information (including CGI variables) relating to an HTTP connection, or to the server itself, into a buffer. GetServerVariable takes the following parameters:
Variable Name | Description |
ALL_HTTP | All HTTP headers that were not already parsed into one of the above variables. These variables are of the form HTTP_<header field name>. |
AUTH_PASS | This will retrieve the password corresponding to REMOTE_USER as supplied by the client. It will be a null-terminated string. |
AUTH_TYPE | Contains the type of authentication used. For example, if Basic authentication is used, the string will be "Basic". For Windows NT Challenge-response, it will be "NTLM". Other authentication schemes will have other strings. Because new authentication types can be added to Internet Server, it is not possible to list all possible strings. If the string is empty then no authentication is used. |
CONTENT_LENGTH | The number of bytes which the script can expect to receive from the client. |
CONTENT_TYPE | The content type of the information supplied in the body of a POST request. |
GATEWAY_INTERFACE | The revision of the CGI specification to which this server complies. The current version is CGI/1.1. |
HTTP_ACCEPT | Special case HTTP header. Values of the Accept: fields are concatenated, separated by ", ". For example, if the following lines are part of the HTTP header:
then the HTTP_ACCEPT variable will have a value of:
|
PATH_INFO | Additional path information, as given by the client. This comprises the trailing part of the URL after the script name but before the query string (if any). |
PATH_TRANSLATED | This is the value of PATH_INFO, but with any virtual path name expanded into a directory specification. |
QUERY_STRING | The information which follows the ? in the URL that referenced this script. |
REMOTE_ADDR | The IP address of the client. |
REMOTE_HOST | The hostname of the client. |
REMOTE_USER | This contains the username supplied by the client and authenticated by the server. |
REQUEST_METHOD | The HTTP request method. |
SCRIPT_NAME | The name of the script program being executed. |
SERVER_NAME | The server's hostname (or IP address) as it should appear in self-referencing URLs. |
SERVER_PORT | The TCP/IP port on which the request was received. |
SERVER_PROTOCOL | The name and version of the information retrieval protocol relating to this request. Normally HTTP/1.0. |
SERVER_SOFTWARE | The name and version of the web server under which the CGI program is running. |
WriteClient
Sends information to the client from the indicated buffer. WriteClient takes the following parameters:
ReadClient
Reads information from the body of the Web client's HTTP request into the buffer supplied by the caller. ReadClient takes the following parameters:
ServerSupportFunction
Provide the ISAs with some general-purpose functions as well as functions that are specific to HTTP server implementation. ServerSupportFunction takes the following parameters:
Comments
A server identifies files with the extensions .EXE and .BAT as CGI (Common Gateway Interface) executables. In addition, a server will identify a file with a DLL extension as a script to execute.
When the server loads the DLL, it calls the DLL at the entry point CHttpServer::GetExtensionVersion to get the version number of the HTTP_FILTER_REVISION the ISA is based on and a short text description for server administrators. For every client request, the CHttpServer::HttpExtensionProc entry point is called. The extension receives the commonly-needed information such as the query string, path info, method name, and the translated path.
See Also CHttpServerContext::ReadClient, CHttpServer::GetExtensionVersion, CHttpServer::HttpExtensionProc