Appendix A

ISAPI Reference


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.

Table A.1 HTTP Status Code

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.

Table A.11 Notification Types

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.