EXTENSION_CONTROL_BLOCK Structure

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:

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