Share via

IPassportManager::OnStartPageECB

  • Article

IPassportManager::OnStartPageECB

Enables retrieving cookies from Passport Manager. Requires a pointer to the EXTENSION_CONTROL_BLOCK structure obtained through an HTTP extension's entry functions.

Important  Either IPassportManager::OnStartPageECB or IPassportManager::OnStartPageManual must be called to initialize the Passport Manager object when writing a C++ ISAPI extension 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 extension and not on an Active Server Pages (ASP) page.

Syntax

HRESULT OnStartPageECB(
    LPBYTE pvECB,
    DWORD* bufSize,
    LPSTR pCookieHeader
);

Parameters

  • pvECB
    [in] A pointer to the EXTENSION_CONTROL_BLOCK data structure given as LPBYTE datatype. Note  You should explicitly cast the lpECB pointer from ISAPI HttpExtensionProc 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 kilobytes).
  • 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 extension 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 extension to emulate certain Passport Manager functions and use EXTENSION_CONTROL_BLOCK data exchange between ISAPI extension code, IIS, and Passport Manager. The pCookieHeader buffer will typically contain any modified Ticket or Profile information that must be passed via the extension 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 extension code to actually write cookies using the buffer. The Passport Manager built-in methods for cookie handling rely on the presence of the Request and Response objects, and thus only work in an ASP environment.

Cookie headers will be written to include the path and domain specified in the registry for the Passport Manager object. The path and domain for cookies 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.

You should note what happens when OnStartPageECB 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 the 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.

This method does not return E_INVALIDARG if the buffer is NULL or the buffer size passed in is too small. Instead, the following behavior occurs:

If pszBuffer=NULL, dwBufferSize contains the size of the cookie headers string being returned.

If pszBuffer!=NULL && dwBufferSize is less than or equal to the size of the cookie-headers string, pszBuffer contains the cookie headers string.

If pszBuffer!=NULL && dwBufferSize is less than the size of the cookie-headers string, pszBuffer is set to NULL and dwBufferSize contains the size of the cookie headers string being returned.

See Also

IPassportManager Interface | Passport Manager Administration Utility