IPassportManager::OnStartPageFilter

IPassportManager::OnStartPageFilter

Enables creating an ISAPI filter that interacts with Passport Manager. Requires a pointer to the HTTP_FILTER_CONTEXT structure obtained through an HTTP filter's entry functions.

Important  IPassportManager::OnStartPageFilter, IPassportManager::OnStartPageECB, or IPassportManager::OnStartPageManual must be called in order to initialize the Passport Manager object when writing a C++ ISAPI filter before any other IPassportManager methods will give correct results. This method accesses the necessary Microsoft® Internet Information Services (IIS) built-in objects in cases in which the Passport Manager object method OnStartPage is never called, such as if Passport Manager is used as part of an IIS filter and not on an Active Server Pages (ASP) page.

Syntax

HRESULT OnStartPageFilter(
    LPBYTE pvPFC,
    DWORD* bufSize,
    LPSTR pCookieHeader
);

Parameters

• pvPFC
  [in] A pointer to the HTTP_FILTER_CONTEXT data structure given as LPBYTE data type.

  Note  You should explicitly cast the lpPFC pointer from ISAPI HttpFilterProc entry point function as (unsigned char *) to make this work.

• bufSize
  [in, out] A pointer to a buffer size given as a DWORD. The caller should pass in the size of the buffer pointed to by pCookieHeader. On successful return, this pointer will contain the actual size of the data copied into the buffer. A good initial estimate of buffer size is 2048 (2 KB).

• pCookieHeader
  [out] A pointer to a buffer location (string). The Passport Manager object will copy into this buffer any HTTP headers and content that it requires the calling ISAPI filter to pass to the client in the ensuing HTTP response.

Return values

Returns one of the following values:

S_OK	Success.
PP_E_NOT_CONFIGURED	Passport Manager object is misconfigured.

Remarks

This method is to be used when implementing an ISAPI filter to emulate certain Passport Manager functions and use HTTP_FILTER_CONTEXT data exchange between ISAPI filter code, IIS, and Passport Manager. The pCookieHeader buffer will typically contain any modified Ticket or Profile information that must be passed via the filter to the client, through WriteClient or similar methods. The buffer string will include the necessary headers, and any information in the body of the cookies will already be encrypted. It is up to the filter code to actually write cookies using the buffer. The built-in methods of the Passport Manager for cookie handling rely on the presence of the Request and Response objects, and thus only work in an ASP environment.

Cookie headers will contain the path and domain specified in the registry for the Passport Manager object. The path and domain can be changed using the Passport Manager Administration utility.

Make sure that requests will not be cached by users' proxies: specify INTERNET_FLAG_PRAGMA_NOCACHE or INTERNET_FLAG_NO_CACHE_WRITE for requests from your ISAPI, especially if the filter or other ISAPI code on your site is using a specialized (non-standard) MIME type that is not recognized by common proxies.

This method has no scripting equivalent and is deliberately marked as Hidden in the headers to prevent it from being visible to automation typelib browsers. It should not be run from automation.

You should note what happens when OnStartPageFilter is called and MSPAuth, MSPSecAuth, MSPProf, and MSPConsent are already present as HTTP_COOKIES on the Login server. The first out parameter, bufSize, equals the initial buffer size passed in and the second, pCookieHeader, is a NULL string.

When the cookies mentioned in the preceding paragraph are received by means of the QUERY_STRING or Microsoft Windows XP client, bufsize contains the size of the data contained in the pCookieHeader parameter after it was populated with the actual header information to send to the Web client.

See Also

IPassportManager Interface | Passport Manager Administration Utility