Share via

EXTENSION_CONTROL_BLOCK Structure

  • Article

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:

  • HTTP_STATUS_BAD_REQUEST

  • HTTP_STATUS_AUTH_REQUIRED

  • HTTP_STATUS_FORBIDDEN

  • HTTP_STATUS_NOT_FOUND

  • HTTP_STATUS_SERVER_ERROR

  • HTTP_STATUS_NOT_IMPLEMENTED

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:

  • hConn   A handle to a connection.

  • lpszVariableName   Null-terminated string indicating which variable is being requested. Variable names are:

    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: 
    accept: */*; q=0.1
accept: text/html
accept: image/jpeg

    then the HTTP_ACCEPT variable will have a value of:

    */*; q=0.1, text/html, image/jpeg
    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.

  • lpvBuffer   Pointer to buffer to receive the requested information.

  • lpdwSize   Pointer to DWORD indicating the number of bytes available in the buffer. On successful completion the DWORD contains the number of bytes transferred into the buffer (including the null terminating byte).

WriteClient

Sends information to the client from the indicated buffer. WriteClient takes the following parameters:

  • ConnID   A unique connection number assigned by the HTTP server.

  • Buffer   Pointer to the buffer where the data is to be written.

  • lpdwBytes   Pointer to the data to be written.

  • dwReserved   Reserved for future use.

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:

  • ConnID   A unique connection number assigned by the HTTP server.

  • lpvBuffer   Pointer to the buffer area to receive the requested information.

  • lpdwSize   Pointer to DWORD indicating the number of bytes available in the buffer. On return *lpdwSize will contain the number of bytes actually transferred into the buffer.

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:

  • hConn   A handle to a connection.

  • dwHSERRequest   An HTTP Server Extension value. See CHttpServerContext::ServerSupportFunction for a list of possible values and related parameters.

  • lpvBuffer   When used with HSE_REQ_SEND_RESPONSE_HEADER, it points to a null-terminated optional status string (i.e., "401 Access Denied"). If this buffer is null, a default response of "200 Ok" will be sent by this function. When used with HSE_REQ_DONE_WITH_SESSION, it points to a DWORD indicating the status code of the request.

  • lpdwSize   When used with HSE_REQ_SEND_RESPONSE_HEADER, it points to the size of the buffer lpdwDataType.

  • lpdwDataType   A null-terminated string pointing to optional headers or data to be appended and sent with the header. If  NULL, the header will be terminated by a “\r\n” pair.

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