Appendix A is a complete Internet Server Application Programming Interface (ISAPI) reference. It describes the structures and functions that make up the API.
ISAPI Extensions
This section describes the ISAPI structures and functions that apply to extensions. There are two sets of functions.
Structures
This section describes the structures used in an ISAPI extension.
HTTP_EXTENSION_VERSION
This structure holds the extension version information. It is passed to GetExtensionVersion().
Listing A.1 HTTPEXT.H-The EXTENSION CONTROL BLOCK
typedef struct _HSE_VERSION_INFO {
DWORD dwExtensionVersion;
CHAR lpszExtensionDesc[HSE_MAX_EXT_DLL_NAME_LEN];
} HSE_VERSION_INFO, *LPHSE_VERSION_INFO;
dwExtensionVersion
Form: DWORD
Value: [out] The version of the HTTP specification. The high and low words are the major and minor versions. The version can be set using MAKELONG.
dwExtensionVersion = MAKELONG( HSE_VERSION_MINOR, HSE_VERSION_
MAJOR );
lpszExtensionDesc
Form: Pointer to a null-terminated string.
Value: [out] A description of the extension.
EXTENSION_CONTROL_BLOCK
The ECB holds frequently used information about a request and callback functions to get additional information. This structure is passed to HttpExtensionProc().
Listing A.2 HTTPEXT.H-The Extension Control Block
typedef struct _EXTENSION_CONTROL_BLOCK {
DWORD cbSize;
DWORD dwVersion;
HCONN ConnID;
DWORD dwHttpStatusCode;
CHAR lpszLogData[HSE_LOG_BUFFER_LEN];
LPSTR lpszMethod;
LPSTR lpszQueryString;
LPSTR lpszPathInfo;
LPSTR lpszPathTranslated;
DWORD cbTotalBytes;
DWORD cbAvailable;
LPBYTE lpbData;
LPSTR lpszContentType;
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;
cbSize
Form: DWORD
Value: [in] The size in bytes of the ECB.
dwVersion
Form: DWORD
Value: [in] The version of the HTTP specification. The high and low words hold the major and minor version numbers.
ConnID
Form: HCONN
Value: [in] A unique context number assigned by the server. It is not to be changed by the extension.
dwHttpStatusCode
Form: DWORD
Value: [out] The status code returned by the extension, as shown in Table A.1.
Status Code | Meaning |
HSE_STATUS_SUCCESS | The request was handled successfully. The server can terminate the session. |
HSE_STATUS_SUCCESS_AND_KEEP_CONN | The request was handled successfully. The server should wait for the next HTTP request if the client supports keep-alive connections. Use this only when also returning a keep-alive connection header. |
HSE_STATUS_PENDING | The ISAPI extension will notify the server when it has finished processing the request using ServerSupportFunction(). |
HSE_STATUS_ERROR | An error occurred while processing the request. |
lpszLogData
Form: An array of HSE_LOG_BUFFER_LEN bytes holding a null-terminated string.
Value: [out] Log data that is specific to this extension.
lpszMethod
Form: Pointer to a null-terminated string.
Value: [in] The request method.
lpszQueryString
Form: Pointer to a null-terminated string.
Value: [in] The query data.
lpszPathInfo
Form: Pointer to a null-terminated string.
Value: [in] Additional path data provided by the client.
lpszPathTranslated
Form: Pointer to a null-terminated string.
Value: [in] The path after translation.
cbTotalBytes
Form: DWORD
Value: [in] The number of bytes to be received from the client. When there are 4 gbytes or more of available data, the value is 0xffffffff. In this case, use ReadClient() to read the data until no more is available.
cbAvailable
Form: DWORD
Value: [in] The number of bytes of data transferred to the buffer lpbData. If this is less than cbTotalBytes, use ReadClient() to get the rest of the data.
lpbData
Form: Pointer to the data buffer.
Value: [in] The client data buffer.
lpszContentType
Form: Pointer to a null-terminated string.
Value: [in] The content type of the data sent by the client.
Entry Point Functions
An ISAPI extension DLL must use two entry points: GetExtensionVersion() and HttpExtensionProc(). The extension can also use an optional entry point - TerminateExtentsion(). The server communicates with the extension through these functions.
GetExtensionVersion()
BOOL WINAPI GetExtensionVersion( HSE_VERSION_INFO *pVer);
This function is called when the extension is started. It returns the version of the extension DLL to the server. The ISAPI specification lists the following source code as the recommended implementation of GetExtensionVersion().
BOOL WINAPI GetExtensionVersion( HSE_VERSION_INFO *pVer )
{
pVer->dwExtensionVersion = MAKELONG( HSE_VERSION_MINOR,
HSE_VERSION_MAJOR );
lstrcpyn( pVer->lpszExtensionDesc,
"This is a sample Web Server Application",
HSE_MAX_EXT_DLL_NAME_LEN );
return TRUE;
}
Return Value
Return TRUE if successful, FALSE otherwise.
pVer
Form: Pointer to an HTTP_EXTENSION_VERSION structure.
Value: [out] The extension version and description.
HttpExtensionProc()
DWORD HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB)
The server calls this function when the a request for the extension is received. HTTPExtensionProc processes the request.
Return Value
Return HSE_STATUS_SUCCESS if successful. On error, return an appropriate error condition, such as HSE_STATUS_ERROR or HTTP_STATUS_SERVER_ERROR.
pECB
Form: Pointer to an EXTENSION_CONTROL_BLOCK structure.
Value: [in/out] The extension control block.
TerminateExtension()
TerminateExtension() is an optional entry point that allows shutdown activities.
BOOL WINAPI TerminateExtension( DWORD dwFlags );
Return Value
TRUE or FALSE. See the description of the flags in Error! Reference source not found. for the meaning of the return code.
dwFlags
Form: DWORD
Value: [in] Flags (described in Error! Reference source not found.) that indicate whether the server is requesting or mandating that the extension terminate.
Table A.2 TerminateExtension Flags
Flag | Meaning |
HSE_TERM_ADVISORY_UNLOAD | The server is requesting that the extension be terminated. Return true to allow the server to unload the extension. Return FALSE to indicate that the server is not to unload the extension. |
HSE_TERM_MUST_UNLOAD | The server is notifying the extension that it will be unloaded, unconditionally. |
ISAPI Server Functions
The server provides the GetServerVariable(), ReadClient(), WriteClient(), and ServerSupportFunction()callback functions.
GetServerVariable()
BOOL GetServerVariable(HCONN hConn, LPSTR lpszVariableName,
LPVOID lpvBuffer, LPDWORD lpdwSize);
This function can be used to get variables for this request that are not otherwise included in the ECB.
Return Value
TRUE if successful, FALSE otherwise. On error, use GetLastError() to get the specific error condition, as shown in Table A.3.
Table A.3 Possible Error Conditions
Error Code | Meaning |
ERROR_INVALID_PARAMETER | The connection handle hConn is invalid. |
ERROR_INVALID_INDEX | This lpszVariableName variable name is bad or not compatible. |
ERROR_INSUFFICIENT_BUFFER | The buffer is too small to return the minimal information. lpdwSize has been changed to indicate the minimum buffer size needed. |
ERROR_MORE_DATA | Only part of the data has been returned and the total size is not known. |
ERROR_NO_DATA | There is no data available to fulfill the request. |
hConn
Form: HCONN
Value: [in] The context number.
lpszVariableName
Form: Pointer to a null-terminated string.
Value: [in] The name of the server variable requested. Valid variable names are shown in Table A.4.
Table A.4 Server Variable Names
Name | Meaning |
AUTH_TYPE | The type of authentication, such as NTLM for challenge-response authentication, or Basic for basic authentication. |
CONTENT_LENGTH | The number of bytes of content to be received. |
CONTENT_TYPE | The type of information provided in the body of a POST request. |
PATH_INFO | The path information after the script name (the name of the extension DLL) and before the query string, if any. |
PATH_TRANSLATED | The path information from PATH_INFO after virtual paths are translated into directory paths. |
QUERY_STRING | The information from the URL following the "?". |
REMOTE_ADDR | The IP address of the client that sent the request. This can be the an agent, such as a firewall, rather than the client's IP address. |
REMOTE_HOST | The host name of the client (or its agent). |
REMOTE_USER | The user name that is supplied by client and authenticated by the server. When the user name is anonymous, the REMOTE_USER string is empty. |
UNMAPPED_REMOTE_USER | The user name before it is mapped to user account on the server. (The mapping occurs in an ISAPI filter, for example.) |
REQUEST_METHOD | The request method. |
SCRIPT_NAME | The name of the script (the ISAPI extension). |
SERVER_NAME | The name or IP address of the server. |
SERVER_PORT | The TCP/IP port used for the request. |
SERVER_PORT_SECURE | If the request is handled on a secure port, the value is "1". Otherwise it is "0". |
SERVER_PROTOCOL | The protocol name and version, usually HTTP/1.0. |
SERVER_SOFTWARE | The name and version of the server that is running the ISAPI extension. |
ALL_HTTP | All server variables that have not been parsed into one of the variables in this table. The variables names are prefixed with HTTP.
Each variable is in the form of a header, with each header separated by a line feed. The string is null-terminated. |
HTTP_ACCEPT | All the values of the accept headers on this request are concatenated into a comma- separated string. For example, the headers accept: text/html and accept: image/jpeg become an HTTP_ACCEPT. |
URL | The base portion of the URL. This is new in HTML 2.0. |
lpvBuffer
Form: Pointer to the buffer in which the value of the server variable will be placed.
Value: [out] The value of the server variable requested.
lpdwSize
Form: Pointer to a DWORD.
Value: [in] The size of the buffer. [out] The length of the value of the server variable, including the null-termination character.
ReadClient()
BOOL ReadClient(HCONN ConnID, LPVOID lpvBuffer, LPDWORD lpdwSize );
This function is used to read data from the client that was not included in the extension control block.
Return Value
TRUE if successful, FALSE otherwise. On error, use GetLastError() to get the specific error condition.
ConnID
Form: HCONN
Value: [in] The context number.
lpvBuffer
Form: Pointer to the client data buffer.
Value: [out] The client data.
lpdwSize
Form: Pointer to a DWORD.
Value: [in] The size of the buffer. [out] The length of the returned client data. If the length of the client data exceeds the length of the buffer, the server returns only as many bytes as are in the buffer. The size variable indicates the number of bytes returned.
WriteClient()
This function can be used to write data to the client.
BOOL WriteClient(HCONN ConnID, LPVOID lpvBuffer, LPDWORD lpdwBytes,
DWORD dwReserved );
Return Value
TRUE if successful, FALSE otherwise. On error, use GetLastError() to get the specific error condition.
ConnID
Form: HCONN
Value: [in] The context number.
lpvBuffer
Form: Pointer to the data buffer.
Value: [in] The data to write to the client.
lpdwBytes
Form: Pointer to a DWORD
Value: [in] The length in bytes of the data to be written to the client.
dwReserved
Form: DWORD
Value: This is reserved for future use.
ServerSupportFunction()
BOOL ServerSupportFunction(HCONN hConn, DWORD dwHSERRequest,
LPVOID lpvBuffer, LPDWORD lpdwSize, LPDWORD lpdwDataType );
The ServerSupportFunction() supplies function not otherwise provided by the other callbacks. The value of dwHSERRequest determines what this callback function is doing, as shown in Table A.5.
Return Value
TRUE if successful, FALSE otherwise. On error, use GetLastError() to get the specific error condition.
hConn
Form: HCONN
Value: [in] The context number.
dwHSERRequest
Form: DWORD
Value: [in] The HTTP Server Extension Request type. Table A.5 shows the meaning of the request types.
Table A.5 Extension Request Type
Request Type | Meaning |
HSE_REQ_SEND_URL_REDIRECT_RESP | This sends a URL redirect message (302) to the client. Set lpvBuffer to point to the buffer holding the new URL (which must be a null-terminated string). Set lpdwSize to the address of a DWORD and set the DWORD to the size of lpvBuffer. lpdwDataType is ignored.
The extension does no additional processing after calling ServerSupportFunction() with this request type. |
HSE_REQ_SEND_URL | This informs the server to send the data specified by the new URL to the client as if the client had requested that URL. Set lpvBuffer to a URL that is on the same server and does not include protocol information. The URL must be a null-terminated string.
Set lpdwSize to the address of a DWORD and set the DWORD to the size of lpvBuffer. lpdwDataType is ignored. The extension does no additional processing after calling ServerSupportFunction() with this request type. |
HSE_REQ_SEND_RESPONSE_HEADER | This sends a complete HTTP server response header including the status, server version, message time, and MIME version. The extension adds additional HTTP headers such as the content type and content length.
The headers are separated by carriage-return and line-feed pairs ("\r\n") with an extra "\r\n" at the end. Only text is valid with this response and it is terminated when a null-termination character ("\0") is encountered. |
HSE_REQ_MAP_URL_TO_PATH | This method is used to map a URL to a path. lpvBuffer points to the buffer that holds the physical path when called. The server uses the buffer to return the physical path.
lpdwSize points to a DWORD holding the size of the buffer passed in lpvBuffer. The server returns the number of bytes placed in the buffer in lpdwSize. lpdwDataType is ignored. |
HSE_REQ_DONE_WITH_SESSION | This request type is used to notify the server that the extension is done processing. It is used when a request has been left in a pending state-when HttpExtensionProc returns HSE_STATUS_PENDING. lpvBuffer, lpdwSize, and lpdwDataType are ignored. |
lpvBuffer
Form: Pointer to the buffer holding the primary argument.
Value: [in] The primary argument needed for the support function requested.
lpdwSize
Form: Pointer to a DWORD.
Value: [in] The number of bytes of data passed in lpvBuffer.
lpdwDataType
Form: Pointer to a DWORD.
Value: [in] An additional argument needed by the support function request type. This can be a pointer, a set of flags, or a value, depending on the request type.
ISAPI Filters
This section describes the structures and functions used in an ISAPI filter.
Structures
This section describes the structures used in an ISAPI filter.
HTTP_FILTER_VERSION
This structure holds the filter version information and additional flags. It is passed to GetFilterVersion().
Listing A.3 HTTPFILT.H-The Filter Version Structure
typedef struct _HTTP_FILTER_VERSION
{
DWORD dwServerFilterVersion;
DWORD dwFilterVersion;
CHAR lpszFilterDesc[SF_MAX_FILTER_DESC_LEN];
DWORD dwFlags;
} HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;
dwServerFilterVersion
Form: DWORD
Value: [in] The version of the HTTP specification. The high and low words are the major and minor versions.
dwFilterVersion
Form: DWORD
Value: [out] The version of the HTTP specification. The high and low words are the major and minor versions. The version can be set using MAKELONG.
dwExtensionVersion = MAKELONG( HSE_VERSION_MINOR, HSE_VERSION_
MAJOR );
lpszFilterDesc
Form: A buffer of SF_MAX_FILTER_DESC_LEN bytes in which to place a null-terminated string.
Value: [out] The filter description.
dwFlags
Form: DWORD
Value: [out] The SF_NOTIFY_* flags that determine which notifications are processed by the filter, the priority of the filter, and whether the filter processes secure notifications, nonsecure notifications, or both. These are shown in Table A.6, Table A.7, and Table A.8.
Table A.6 Filter Notification Flags
Flag | Meaning |
SF_NOTIFY_READ_RAW_DATA | The filter handles READ_RAW_DATA notifications. |
SF_NOTIFY_PREPROC_HEADERS | The filter handles PREPROC_HEADERS notifications. |
SF_NOTIFY_AUTHENTICATION | The filter handles AUTHENTICATION notifications. |
SF_NOTIFY_ URL_MAP | The filter handles URL_MAP notifications. |
SF_NOTIFY_ SEND_RAW_DATA | The filter handles SEND_RAW_DATA notifications. |
SF_NOTIFY_ LOG | The filter handles LOG notifications. |
SF_NOTIFY_ END_OF_NET_SESSION | The filter handles END_OF_NET_SESSION notifications. |
SF_NOTIFY_ ACCESS_DENIED | The filter handles ACCESS_DENIED notifications. |
Table A.7 Filter Security Flags
Flag | Meaning |
SF_NOTIFY_SECURE_PORT | Handle notifications on secure ports |
SF_NOTIFY_NONSECURE | Handle notifications on nonsecure ports. |
Table A.8 Filter Priority Flags
Flag | Meaning |
SF_NOTIFY_ORDER_DEFAULT | Load the filter at the default priority. |
SF_NOTIFY_ ORDER_LOW | Load the filter at low priority. |
SF_NOTIFY_ ORDER_MEDIUM | Load the filter at medium priority. |
SF_NOTIFY_ ORDER_HIGH | Load the filter at high priority. |
HTTP_FILTER_CONTEXT
HTTP_FILTER_CONTEXT holds size and revision fields, data fields that are for use by the server, and callbacks.
Listing A.4 HTTPFILT.H-The Filter Context Structure
typedef struct _HTTP_FILTER_CONTEXT
{
DWORD cbSize;
DWORD Revision;
PVOID ServerContext;
DWORD ulReserved;
BOOL fIsSecurePort;
PVOID pFilterContext;
// Server callbacks
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,
enum SF_REQ_TYPE sfReq,
PVOID pData,
DWORD ul1,
DWORD ul2
);
} HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;
cbSize
Form: DWORD
Value: [in] The size of this structure.
Revision
Form: DWORD
Value: [in] The version of this structure. The high and low words hold the major and minor version numbers.
ServerContext
Form: Pointer
Value: Reserved for use by the server.
ulReserved
Form: DWORD
Value: [in] Reserved for use by the server.
fIsSecurePort
Form: BOOL
Value: [in] If this notification is on a secure port, this value is TRUE.
pFilterContext
Form: Pointer to filter context information.
Value: [in/out] A pointer used by the filter to associate context information with this request. The filter can set the pointer to memory allocated by the filter and free that memory when it gets the SF_NOTIFY_END_OF_NET_SESSION notification.
HTTP_FILTER_RAW_DATA
This structure holds the raw data of a request or the response to a request. It is passed to HttpFilterProc() for SF_NOTIFY_READ_RAW_DATA and SF_NOTIFY_SEND_RAW_DATA notifications.
Listing A.5 HTTPFILT.H-The Raw Data structure
typedef struct _HTTP_FILTER_RAW_DATA
{
PVOID pvInData;
DWORD cbInData;
DWORD cbInBuffer;
DWORD dwReserved;
} HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;
pvInData
Form: Pointer to the raw data buffer.
Value: [in] The raw data of the request.
cbInData
Form: DWORD
Value: [in] The number of bytes of data in the raw data buffer.
cbInBuffer
Form: DWORD
Value: [in] The size in bytes of the raw data buffer.
dwReserved
Form: DWORD
Value: This field is reserved for future use.
HTTP_FILTER_PREPROC_HEADERS
This structure provides access to the server callback functions. It is passed to HttpFilterProc() for SF_NOTIFY_PREPROC_HEADERS notification.
Listing A.6 HTTPFILT.H-The Preprocess-Headers Structure
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;
HTTP_FILTER_AUTHENT
This structure holds the authorization user name and password. It is passed to HttpFilterProc() for SF_NOTIFY_AUTHENTICATION notifications.
Listing A.7 HTTPFILT.H-The Authentication Structure
typedef struct _HTTP_FILTER_AUTHENT
{
CHAR * pszUser;
DWORD cbUserBuff;
CHAR * pszPassword;
DWORD cbPasswordBuff;
} HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;
pszUser
Form: Pointer to a string.
Value: [in/out] The authentication user name. If the user name is anonymous, the string is empty.
cbUserBuff
Form: DWORD
Value: [in] The length of the pszUser buffer, which is always at least SF_MAX_USERNAME.
pszPassword
Form: Pointer to a string.
Value: [in/out] The authentication password.
cbPasswordBuff
Form: DWORD
Value: [in] The length of the pszPassword buffer, which is always at least SF_MAX_PASSWORD.
HTTP_FILTER_URL_MAP
This structure holds the URL and the physical path to which it is mapped. It is passed to HttpFilterProc() for SF_NOTIFY_URL_MAP notifications.
Listing A.8 HTTPFILT.H-The URL Map Structure
typedef struct _HTTP_FILTER_URL_MAP
{
const CHAR * pszURL;
CHAR * pszPhysicalPath;
DWORD cbPathBuff;
} HTTP_FILTER_URL_MAP, *PHTTP_FILTER_URL_MAP;
pszURL
Form: Pointer to a string.
Value: [in] The URL that is mapped to a physical path.
pszPhysicalPath
Form: Pointer to a string.
Value: [in/out] The physical path.
cbPathBuff
Form: DWORD
Value: [in] The size of the pszPhysicalPath buffer.
HTTP_FILTER_LOG
This structure holds information that is recorded in the server log. It is passed to HttpFilterProc() for SF_NOTIFY_LOG notifications.
Listing A.9 HTTPFILT.H-The Filter Log Structure
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;
pszClientHostName
Form: Pointer to a null-terminated string.
Value: [in/out] The host name of the client.
pszClientUserName
Form: Pointer to a null-terminated string.
Value: [in/out] The user name of the client.
pszServerName
Form: Pointer to a null-terminated string.
Value: [in/out] The name of the server to which the client is connected.
pszOperation
Form: Pointer to a null-terminated string.
Value: [in/out] The HTTP command.
pszTarget
Form: Pointer to a null-terminated string.
Value: [in/out] The HTTP command target.
pszParameters
Form: Pointer to a null-terminated string.
Value: [in/out] The HTTP command parameters.
dwHttpStatus
Form: DWORD
Value: [in/out] The return status.
dwWin32Status
Form: DWORD
Value: [in/out] The Win32 error code.
HTTP_FILTER_ACCESS_DENIED
This structure provides information about requests for which access was denied. This was introduced in in IIS 3.0. It is passed to HttpFilterProc() for SF_NOTIFY_ACCESS_DENIED notifications.
Listing A.10 HTTPFILT.H-The Filter Log Structure
typedef struct _HTTP_FILTER_ACCESS_DENIED
{
const CHAR * pszURL;
const CHAR * pszPhysicalPath;
DWORD dwReason;
} HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED;
pszUrl
Form: Pointer to a null-terminated string.
Value: [in] The URL to which access was denied.
pszPhysicalPath
Form: Pointer to a null-terminated string.
Value: [in] The physical path from the translation of the requested URL.
dwReason
Form: DWORD
Value: [in] The reason the request was denied.
Table A.9 Reasons for Denied Access
Name | Meaning |
SF_DENIED_LOGON | Denied because of a logon failure. |
SF_DENIED_RESOURCE | Denied because of a resource. |
SF_DENIED_FILTER | Denied by an ISAPI filter. |
SF_DENIED_APPLICATION | Denied by an ISAPI or CGI application. |
SF_DENIED_BY_CONFIG | This can be set when SF_DENIED_LOGON is set if the logon failure was because of the server configuration. |
Entry-Point Functions
There are two entry points to an ISAPI filter DLL: GetFilterVersion(), and HttpFilterProc().
GetFilterVersion()
BOOL GetFilterVersion(PHTTP_FILTER_VERSION pVer)
This function is called when the filter is loaded. It returns to the server the version of the filter DLL, the priority of the filter, and the notifications that the filter is to get.
Return Value
Return TRUE if successful, FALSE otherwise. If the filter returns FALSE, it is unloaded. The server will process requests without using the filter.
pVer
Form: Pointer to an HTTP_FILTER_VERSION structure.
Value: [out] The extension version information.
HttpFilterProc()
DWORD HttpFilterProc(PHTTP_FILTER_CONTEXT pfc,
DWORD dwNotificationType, LPVOID pvNotification)
This function is called to notify the filter of the events it registered for in GetFilterVersion().
Return Value
Return SF_STATUS_REQ_NEXT_NOTIFICATION if the server is to continue processing the request. Table A.10 shows the return values.
Table A.10 HttpFilterProc() Return Codes
Return Code | Meaning |
SF_STATUS_REQ_FINISHED | The filter has handled the HTTP request. The server should disconnect the session. |
SF_STATUS_REQ_FINISHED_KEEP_CONN | The filter handled the HTTP request. The server should end the session but keep the TCP session open if it negotiated to do so. |
SF_STATUS_REQ_NEXT_NOTIFICATION | The next filter in the notification chain should be called. |
SF_STATUS_REQ_HANDLED_NOTIFICATION | This filter handled the notification. No other handles should be called for this notification type. |
SF_STATUS_REQ_ERROR | An error occurred. The server should use GetLastError() and indicate the error to the client. |
SF_STATUS_REQ_READ_NEXT | The filter is an opaque stream filter and the session parameters are being negotiated. This is only valid for raw read notification. |
pfc
Form: Pointer to an HTTP_FILTER_CONTEXT structure.
Value: [in] The filter context information.
dwNotificationType
Form: DWORD
Value: One of the notification types described in Table A.11.
Name | Meaning |
SF_NOTIFY_READ_RAW_DATA | The filter can act on data that is read from the client. |
SF_NOTIFY_SEND_RAW_DATA | The filter can act on data that that is written to the client. |
SF_NOTIFY_PREPROC_HEADERS | The filter can preprocess the request headers. |
SF_NOTIFY_AUTHENTICATION | The filter can participate in the authentication of the client user. |
SF_NOTIFY_URL_MAP | The filter can participate in the mapping of the URL to a physical path. |
SF_NOTIFY_LOG | The filter can participate in logging the request. |
SF_NOTIFY_ACCESS_DENIED | The filter can handle cases in which access is denied. This is new in IIS 3.0. |
SF_NOTIFY_END_OF_NET_SESSION | The filter can act when the client is about to disconnect. |
pvNotification
Form: Pointer to a structure of a type appropriate for the notification type.
Value: [in/out] See the description of the structure associated with the notification type in Table A.12.
Table A.12 Notification Structures
Notification Type | Structure |
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 |
SF_NOTIFY_END_OF_NET_SESSION | None |
© 1996, QUE Corporation, an imprint of Macmillan Publishing USA, a Simon and Schuster Company.