On Unix platforms we provide a header file wintypes.h that defines several of these types for compatibility with the specification.
The LP prefix is an abbreviation for "Long-Pointer" and dates back to the days of 16-bit memory models under MS-DOS!typedef int BOOL; typedef char* LPSTR; typedef const char * LPCSTR; typedef void* LPVOID; typedef void* PVOID; typedef void VOID; typedef int* LPDWORD; typedef int DWORD; typedef char CHAR; typedef unsigned char* LPBYTE; typedef short WORD; typedef char BYTE; typedef long LONG;
BOOL WINAPI GetExtensionVersion( HSE_VERSION_INFO *Ver )Where the HSE_VERSION_INFO structure is defined as:
typedef struct _HSE_VERSION_INFO { DWORD dwExtensionVersion; CHAR lpszExtensionDesc[ HSE_MAX_EXT_DLL_NAME_LEN ]; } HSE_VERSION_INFO, *LPHSE_VERSION_INFO;The dwExtensionVersion number contains the version of the ISAPI specification that the module expects the server to support.
The module should fill in the description buffer with a textual description of the module. The function should return TRUE on success.
The other function the module must export is:
DWORD WINAPI HttpExtensionProc( LPEXTENSION_CONTROL_BLOCK ecb )The ExtensionControlBlock structure contains data about the connection as well as callback functions allowing the module to get more information and perform various actions.
typedef struct _EXTENSION_CONTROL_BLOCK { DWORD cbSize; /* Size of this struct. */ DWORD dwVersion; /* Version info of this spec */ HCONN ConnID; /* Context number not to be modified! */ DWORD dwHttpStatusCode; /* HTTP Status code */ /* null terminated log info specific to this Extension DLL */ CHAR lpszLogData[HSE_LOG_BUFFER_LEN]; LPCSTR lpszMethod; /* REQUEST_METHOD */ LPCSTR lpszQueryString; /* QUERY_STRING */ LPCSTR lpszPathInfo; /* PATH_INFO */ LPCSTR lpszPathTranslated; /* PATH_TRANSLATED */ DWORD cbTotalBytes; /* Total bytes indicated from client */ DWORD cbAvailable; /* Available number of bytes */ LPBYTE lpbData; /* Pointer to cbAvailable bytes */ LPCSTR lpszContentType; /* Content type of client data */ BOOL (WINAPI * GetServerVariable) ( HCONN hConn, LPSTR lpszVariableName, LPVOID lpvBuffer, LPDWORD lpdwSizeofBuffer ); 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 functions provided by the Extension Control Block are described in detail below.
Modules can optionally export a third function, which gets called when the module is about to be unloaded. This allows the module to free any memory it has allocated, or clear up any background threads.
BOOL WINAPI TerminateExtension( DWORD dwFlags );Where dwFlags is a bitfield consisting of the following values:
Value | Meaning |
HSE_TERM_ADVISORY_UNLOAD | The server wants to unload the extension. The extension can return TRUE if OK, or FALSE if the server should not unload the extension. |
HSE_TERM_MUST_UNLOAD | The server is indicating the extension is about to be unloaded, the extension cannot refuse. |
BOOL GetServerVariable( HCONN ConnID, LPSTR VariableName, LPVOID Bufffer, LPDWORD SizeofBuffer )Arguments:
Variable Name | Description | ||||||
AUTH_TYPE | The HTTP authentication method. e.g. "Basic" | ||||||
CONTENT_LENGTH | The length of the request body data on a POST or PUT | ||||||
GATEWAY_INTERFACE | The CGI interface version supported by the server | ||||||
PATH_INFO | Additional path information after the script name. | ||||||
PATH_TRANSLATED | The PATH_INFO mapped into a physical filename | ||||||
QUERY_STRING | Information following the '?' in the URL | ||||||
REQUEST_METHOD | The HTTP method, e.g. GET | ||||||
REMOTE_HOST | The remote host name, e.g. foo.bar.com | ||||||
REMOTE_USER | The user name, if authenticated. | ||||||
HTTP_ACCEPT | The accept lines sent by the client. | ||||||
SERVER_PORT | The port the server is running on | ||||||
SERVER_NAME | The IP name of the web server | ||||||
HTTP_REFERER | The referring page, as sent by the browser | ||||||
HTTP_USER_AGENT | The name of the client (browser) software. | ||||||
REMOTE_ADDR | The IP address of the client | ||||||
SCRIPT_NAME | The name of the API extension being run. | ||||||
SERVER_SOFTWARE | The name of the web server software. | ||||||
SERVER_PROTOCOL | The HTTP version supported by the server. e.g. HTTP/1.0 | ||||||
ALL_HTTP | All other HTTP request headers. These
variables are of the form
HTTP_SERVER_PORT_SECURE | If the request was over a secure port, this
value is set to "1", otherwise "0".
| URL | The URL.
| VSERVER_NAME | The administrative name of the
virtual server. Zeus specification
extension
| |
BOOL (WINAPI * WriteClient) ( HCONN ConnID, LPVOID Buffer, LPDWORD Bytes, DWORD Reserved );Write out data to the client.
Arguments:
BOOL (WINAPI * ReadClient) ( HCONN ConnID, LPVOID Buffer, LPDWORD Size );Read data from the client.
Arguments:
BOOL (WINAPI * ServerSupportFunction)( HCONN ConnID, DWORD Request, LPVOID Buffer, LPDWORD Size, LPDWORD DataType );Request can be one of the following:
BOOL WINAPI GetFilterVersion( HTTP_FILTER_VERSION *pVer );Where HTTP_FILTER_VERSION is defined as:
typedef struct _HTTP_FILTER_VERSION { DWORD dwServerFilterVersion; DWORD dwFilterVersion; CHAR lpszFilterDesc[SF_MAX_FILTER_DESC_LEN+1]; DWORD dwFlags; } HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;The GetFilterVersion function should set the dwFilterVersion to the version of the Filter specification that the filter supports. This version is defined in the header file as HSE_FILTER_REVISION.
The lpszFilterDesc should be filled in with a textual description of the filter.
The filter should set dwFlags to a combination of the following flags.
DWORD WINAPI HttpFilterProc( PHTTP_FILTER_CONTEXT pfc, DWORD notificationType, LPVOID notificationInfo );The notificationInfo parameter points to a data structure which is specific to the type of notification the server is receiving. The table below shows the type of this argument for each notificationType.
Notification Type | Notification Info |
SF_NOTIFY_READ_RAW_DATA | HTTP_FILTER_RAW_DATA |
SF_NOTIFY_SEND_RAW_DATA | HTTP_FILTER_RAW_DATA |
SF_NOTIFY_PREPROC_HEADERS | HTTP_FILTER_PREPROC_HEADERS |
SF_NOTIFY_AUTHENTICATION | HTTP_FILTER_AUTHENT |
SF_NOTIFY_URL_MAP | HTTP_FILTER_URL_MAP |
SF_NOTIFY_LOG | HTTP_FILTER_LOG |
SF_NOTIFY_ACCESS_DENIED | HTTP_FILTER_ACCESS_DENIED |
The first argument to the HttpFilterProc is of pointer to an HTTP_FILTER_CONTEXT structure. This structure is defined as:
typedef struct _HTTP_FILTER_CONTEXT { DWORD cbSize; /* the size of this structure */ DWORD Revision; /* the revision number of this structure */ PVOID ServerContext; /* reserved for server use */ DWORD ulReserved; /* reserved for server use */ BOOL fIsSecurePort; /* True if the connection is on a secure port */ PVOID pFilterContext; /* a pointer to information the filter wants to associate with the request */ BOOL (WINAPI * GetServerVariable) (struct _HTTP_FILTER_CONTEXT * pfc, LPSTR lpszVariableName, LPVOID lpvBuffer, LPDWORD lpdwSize); BOOL (WINAPI * AddResponseHeaders) (struct _HTTP_FILTER_CONTEXT * pfc, LPSTR lpszHeaders, DWORD dwReserved); BOOL (WINAPI * WriteClient) (struct _HTTP_FILTER_CONTEXT * pfc, LPVOID Buffer, LPDWORD lpdwBytes, DWORD dwReserved); VOID* (WINAPI * AllocMem) (struct _HTTP_FILTER_CONTEXT * pfc, DWORD cbSize, DWORD dwReserved); BOOL (WINAPI * ServerSupportFunction) (struct _HTTP_FILTER_CONTEXT * pfc, DWORD sfReq, LPVOID pData, LPDWORD ul1, LPDWORD ul2); } HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;The functions provided by this structure are described below.
BOOL WINAPI GetServerVariable( HTTP_FILTER_CONTEXT *pfc, LPSTR VariableName, LPVOID Buffer, LPDWORD Size )This function behaves identically the function of the same name in the ExtensionControlBlock described above.
BOOL WINAPI AddResponseHeaders ( HTTP_FILTER_CONTEXT *pfc, LPSTR Headers, DWORD Reserved );Add extra HTTP headers to be sent to the client.
Arguments:
BOOL WINAPI WriteClient) ( HTTP_FILTER_CONTEXT *pfc, LPVOID Buffer, LPDWORD Bytes, DWORD Reserved );Write data to the client.
Arguments:
VOID* WINAPI AllocMem( HTTP_FILTER_CONTEXT *pfc, DWORD size, DWORD Reserved );This function allocated memory in a per-connection memory pool. The memory will get freed automatically by the server when the connection is finished.
Filters should do all their memory allocation through this call, as directly calling malloc() or new() may interfere with the memory server's management.
Arguments:
BOOL WINAPI ServerSupportFunction( HTTP_FILTER_CONTEXT *pfc, DWORD Request, LPVOID Data, LPDWORD ul1, LPDWORD ul2 );The Request argument sets the function to be performed. Supported values are:
typedef struct _HTTP_FILTER_ACCESS_DENIED { const CHAR * pszURL; /* Requesting URL */ const CHAR * pszPhysicalPath; /* Physical path of resource */ DWORD dwReason; /* Bitfield of SF_DENIED flags */ } HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED;The Zeus Server will always set the dwReason bitfield to zero. The pszURL and pszPhysicalPath values indicate the the resource that access was denied to.
typedef struct _HTTP_FILTER_AUTHENT { CHAR * pszUser; DWORD cbUserBuff; CHAR * pszPassword; DWORD cbPasswordBuff; } HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;
typedef struct _HTTP_FILTER_LOG { const CHAR * pszClientHostName; const CHAR * pszClientUserName; const CHAR * pszServerName; const CHAR * pszOperation; const CHAR * pszTarget; const CHAR * pszParameters; DWORD dwHttpStatus; DWORD dwWin32Status; } HTTP_FILTER_LOG, *PHTTP_FILTER_LOG;The filter can alter the value of the pointer (but not the buffer) of the pszTarget, pszOperation and pszClientUserName values.
The dwWin32Status will always be set to zero with the Zeus Server.
typedef struct _HTTP_FILTER_PREPROC_HEADERS { BOOL (WINAPI * GetHeader) (struct _HTTP_FILTER_CONTEXT * pfc, LPSTR lpszName, LPVOID lpvBuffer, LPDWORD lpdwSize); BOOL (WINAPI * SetHeader) (struct _HTTP_FILTER_CONTEXT * pfc, LPSTR lpszName, LPSTR lpszValue); BOOL (WINAPI * AddHeader) (struct _HTTP_FILTER_CONTEXT * pfc, LPSTR lpszName, LPSTR lpszValue); DWORD dwReserved; } HTTP_FILTER_PREPROC_HEADERS, *PHTTP_FILTER_PREPROC_HEADERS;
BOOL WINAPI GetHeader( HTTP_FILTER_CONTEXT *pfc, LPSTR Name, LPVOID Buffer, LPDWORD Size )Gets the current value of a header in the client's HTTP request.
BOOL WINAPI SetHeader( HTTP_FILTER_CONTEXT *pfc, LPSTR Name, LPSTR Value, LPDWORD Size ) BOOL WINAPI AddHeader( HTTP_FILTER_CONTEXT *pfc, LPSTR Name, LPVOID Value );These two allow the filter to modify header lines in the client's request.
SetHeader & AddHeader are very similar, differing only in their behaviour when the header in question already exists. With SetHeader, the previous header value will be replaced; with AddHeader the new value will be merged with the old value.
For example, if the client's input looks like:
Name and Value should both be null terminated strings; with the extension that if Value is a NULL pointer, then both SetHeader & AddHeader will delete the header in question.
All three functions return TRUE on success, or FALSE if an error occurred.
typedef struct _HTTP_FILTER_RAW_DATA { PVOID pvInData; DWORD cbInData; DWORD cbInBuffer; DWORD dwReserved; } HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;
typedef struct _HTTP_FILTER_URL_MAP { const CHAR * pszURL; CHAR * pszPhysicalPath; DWORD cbPathBuff; } HTTP_FILTER_URL_MAP, *PHTTP_FILTER_URL_MAP;