IHttpNegotiate::BeginningTransaction
Methods

IHttpNegotiate::BeginningTransaction


HRESULT BeginningTransaction(
    [in] LPCWSTR  szURL,
    [in] DWORD  dwReserved,
    [in] LPCWSTR  szHeaders,
    [out] LPWSTR * pszAdditionalHeaders
);		

Notifies the client of the URL being bound to at the beginning of an HTTP transaction.

szURL
URL for the HTTP transaction.
dwReserved
Reserved for future use.
szHeaders
Current request headers.
pszAdditionalHeaders
Optional additional headers to append to the HTTP request. If these conflict with existing values in szHeaders, the new request headers take precedence. If pszAdditionalHeaders is set to NULL, no headers are added to the HTTP request.

The URL moniker calls this method before sending an HTTP request. It notifies the client of the URL being bound to at the beginning of the HTTP transaction. It also allows the client to add additional headers, such as Accept-Language, to the request.

See also IHttpNegotiate::OnResponse

IHttpNegotiate::OnResponse

HRESULT OnResponse(
    [in] DWORD  dwResponseCode,
    [in] LPCWSTR  szResponseHeaders,
    [in] LPCWSTR  szRequestHeaders,
    [out] LPWSTR * pszAdditionalRequestHeaders
);

Allows the client of a bind operation to examine the response headers, optionally terminate the bind operation, and add HTTP headers to a request before resending the request.

dwResponseCode
HTTP response code returned in response to a previous HTTP request. For information about these codes, see the HTTP specification.
szResponseHeaders
Response headers from the HTTP server. For more information, see the HTTP specification.
szRequestHeaders
If dwResponseCode indicates an error, contains HTTP request headers that will be used when the request is sent again.
pszAdditionalRequestHeaders
If dwResponseCode indicates an error, contains optional, additional headers to add before the request is sent again. If the specified header value conflicts with existing values in szRequestHeaders, the new headers take precedence. If pszAdditionalRequestHeaders is set to NULL, no headers are added to the HTTP request.

The URL moniker calls this method when it receives a response to an HTTP request. If dwResponseCode indicates a success, the client can examine the response headers and can optionally abort the bind operation. If dwResponseCode indicates a failure, the client can add HTTP headers to the request before it is sent again.

Note that if multiple clients have registered on the bind context for a given bind operation, more than one of these clients can provide an IHttpNegotiate callback interface. Every client providing this callback receives notifications. Each one is given a chance to add HTTP headers or to abort the HTTP transaction. In such cases, the last client to receive callback notification is the client driving the download operation, and it will dictate the final decision.

See also IHttpNegotiate::BeginningTransaction

IHttpSecurity::OnSecurityProblem

HRESULT OnSecurityProblem (
    [in] DWORD dwProblem
);

Notifies the client application about an authentication problem. This interface should be implemented by applications that want to handle any authentication problems themselves, instead of using the default user interface.

dwProblem
Double-word value that contains the authentication problem encountered. Can be one of the following values:
ERROR_INTERNET_SEC_CERT_DATE_INVALID
ERROR_INTERNET_SEC_CERT_CN_INVALID
ERROR_INTERNET_HTTP_TO_HTTPS_ON_REDIR
ERROR_INTERNET_HTTPS_TO_HTTP_ON_REDIR
ERROR_HTTP_REDIRECT_NEEDS_CONFIRMATION
ERROR_INTERNET_INVALID_CA
ERROR_INTERNET_CLIENT_AUTH_CERT_NEEDED

IInternetBindInfo::GetBindInfo

HRESULT GetBindInfo(
    [out] DWORD *grfBINDF,
    [in, out, unique] BINDINFO * pbindinfo
);

Gets the BINDINFO structure associated with the binding operation.

grfBINDF
Address of a value taken from the BINDF enumeration indicating whether the bind should proceed synchronously or asynchronously.
pbindinfo
Address of the BINDINFO structure, which describes how the client wants the binding to occur.

The size of the BINDINFO structure has changed with the release of Microsoft Internet Explorer 4.0. Developers must write code that checks the size of the BINDINFO structure that is passed into their implementation of this method before writing to members of the structure. See Handling BINDINFO Structures section in the Monikers, URLs, Security Zones, and Pluggable Protocols Overview for more information.

IInternetBindInfo::GetBindString

HRESULT GetBindString(
    [in] ULONG ulStringType,
    [in, out] LPOLESTR *ppwzStr,
    [in] ULONG cEl,
    [in, out] ULONG *pcElFetched
);

Gets the strings needed by the protocol for its operation.

ulStringType
Unsigned long integer value that indicates the type of string or strings that should be returned. Can be one of the BINDSTRING values.
ppwzStr
Address of an array of strings.
cEl
Unsigned long integer value that indicates the number of elements in the array provided.
pcElFetched
Address of an unsigned long integer that indicates the number of elements filled in the array.

This method is used if the protocol requires any additional information, such as a username or password, needed to access a URL.

IInternetHostSecurityManager::GetSecurityId

HRESULT GetSecurityId(
    [out] BYTE *pbSecurityId,
    [in, out] DWORD *pcbSecurityId,
    [in] DWORD dwReserved
);

Retrieves the security identification of the host.

pbSecurityId
Address of a buffer containing the scheme, domain name, and zone of the host.
pcbSecurityId
Address of a double-word value containing the size of the buffer being passed in.
dwReserved
Reserved. Must be set to zero.

If successful, pbSecurityId contans the scheme, domain, and zone information in the following format:

<scheme>:<domain>+<zone>

and pcbSecurityID will contain the actual size of the data stored in the buffer.

IInternetHostSecurityManager::ProcessUrlAction

HRESULT ProcessUrlAction(
    [in] DWORD dwAction,
    [out] BYTE *pPolicy,
    [in] DWORD cbPolicy,
    [in] BYTE *pContext,
    [in] DWORD cbContext,
    [in] DWORD dwFlags,
    [in] DWORD dwReserved
);

Retrieves the policy associated with the URL action in the given context.

dwAction
Double-word value that contains the action to process. Can be one of the URL Action Flags values.
pPolicy
Address of the output buffer to store the policy. Since all the URLPOLICY_* values are double-word values, the buffer should be greater than or equal to the size of a DWORD. Can contain one of the URL Policy Flags values.
cbPolicy
Double-word value that contains the size of the output buffer.
pContext
Address of a buffer that contains the context information used by the delegation routines.
cbContext
Double-word value that contains the size of the context information buffer.
dwFlags
Double-word value that contains the flags controlling this method. Can be one of the PUAF values.
dwReserved
Reserved. Must be set to zero.

IInternetHostSecurityManager::QueryCustomPolicy

HRESULT QueryCustomPolicy(
    [in] REFGUID guidKey,
    [out] BYTE **ppPolicy,
    [out] DWORD *pcbPolicy,
    [in] BYTE *pContext,
    [in] DWORD cbContext,
    [in] DWORD dwReserved
);

Retrieves the custom policy associated with the specified key in the given context.

guidKey
Globally unique identifier associated with the custom policy.
ppPolicy
Address of a pointer to the buffer to store the policy information.
pcbPolicy
Address of a double-word value that contains the policy buffer size.
pContext
Address of a buffer that contains the context information.
cbContext
Unsigned long integer value that contains the size of the context buffer.
dwReserved
Reserved. Must be set to zero.

IInternetProtocol::LockRequest

HRESULT LockRequest(
    [in] DWORD dwOptions
);

Locks the requested resource so that IInternetProtocolRoot::Terminate can be called and the remaining data can be read.

dwOptions

For asynchronous pluggable protocols that do not need to lock a request, the method should just return S_OK.

IInternetProtocol::Read

HRESULT Read(
    [out] LPVOID pv,
    [in] ULONG cb,
    [out] ULONG *pcbRead
);

Reads data retrieved by the pluggable protocol handler.

pv
Address of the buffer where the information will be stored.
cb
ULONG value that indicates the size of the buffer.
pcbRead
Address of a ULONG value that indicates the amount of data stored in the buffer.

Developers that are implementing an asynchronous pluggable protocol must be prepared to have their implementation of IInternetProtocol::Read to continue to be called a few extra times after it has returned S_FALSE.

IInternetProtocol::Seek

HRESULT Seek(
    [in] LARGE_INTEGER dlibMove,
    [in] DWORD dwOrigin,
    [out] ULARGE_INTEGER *plibNewPosition
);

Moves the current seek offset.

dlibMove
Large integer value that indicates how far to move the offset.
dwOrigin
DWORD value that indicates where the move should begin.
plibNewPosition
Address of an unsigned long integer value that indicates the new offset.

IInternetProtocol::UnlockRequest

HRESULT UnlockRequest();

Frees any resources associated with a lock.

This method is called only if IInternetProtocol::LockRequest was called.

IInternetProtocolInfo::CombineUrl

HRESULT CombineUrl(
    [in] LPCWSTR pwzBaseUrl,
    [in] LPCWSTR pwzRelativeUrl,
    [in] DWORD dwCombineFlags,
    [out] LPWSTR pwzResult,
    [in] DWORD cchResult,
    [out] DWORD *pcchResult,
    [in] DWORD dwReserved
);

Combines a base and relative URL into a full URL.

pwzBaseUrl
String value containing the base URL.
pwzRelativeUrl
String value containing the relative URL.
dwCombineFlags
Double-word value that controls the combining process. Can be one of the following values:
ICU_BROWSER_MODE
ICU_ENCODE_SPACES_ONLY
ICU_DECODE
ICU_NO_ENCODE
ICU_NO_META
pwzResult
String variable where the full URL will be stored.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value to store the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.

For more information on the dwCombineFlags values, see the InternetCombineUrl function in the Win32 Internet Functions Reference.

IInternetProtocolInfo::CompareUrl

HRESULT CompareUrl(
    [in] LPCWSTR pwzUrl1,
    [in] LPCWSTR pwzUrl2,
    [in] DWORD dwCompareFlags
);

Compares two URLs and determines if they are equal.

pwzUrl1
String value that contains the first URL.
pwzUrl2
String value that contains the second URL.
dwCompareFlags
Double-word value that controls the comparison. Set to TRUE to ignore slashes, FALSE otherwise.

IInternetProtocolInfo::ParseUrl

HRESULT ParseUrl(
    [in] LPCWSTR pwzUrl,
    [in] PARSEACTION ParseAction,
    [in] DWORD dwParseFlags,
    [out] LPWSTR pwzResult,
    [in] DWORD cchResult,
    [out] DWORD *pcchResult,
    [in] DWORD dwReserved
);

Parses a URL.

pwzUrl
String value containing the URL to parse.
ParseAction
PARSEACTION value that determines the information to be parsed from the URL.
dwParseFlags
Reserved. Must be set to zero.
pwzResult
String value that contains the information parsed from the URL.
cchResult
Double-word value that contains the size of the buffer.
pcchResult
Address of a double-word value that contains the size of the information stored in the buffer.
dwReserved
Reserved. Must be set to zero.

IInternetProtocolInfo::QueryInfo

HRESULT QueryInfo(
    [in] LPCWSTR pwzUrl,
    [in] QUERYOPTION QueryOption,
    [in] DWORD dwQueryFlags,
    [in, out] LPVOID pBuffer,
    [in] DWORD cbBuffer,
    [in, out] DWORD *pcbBuf,
    [in] DWORD dwReserved
);

Retrieves information related to the specified URL.

pwzUrl
String value containing the URL.
QueryOption
QUERYOPTION value that indicates what option to query.
dwQueryFlags
Reserved. Must be set to zero.
pBuffer
Address of the buffer where the information will be stored.
cbBuffer
Double-word value containing the size of the buffer.
pcbBuf
Address of a double-word variable where the size of the requested information will be stored.
dwReserved
Reserved. Must be set to zero.

IInternetProtocolRoot::Abort

HRESULT Abort(
    [in] HRESULT hrReason,
    [in] DWORD dwOptions
);

Aborts an operation that is in progress.

hrReason
HRESULT value that contains the reason for the abort.
dwOptions
DWORD value that determines if the abort happens synchronously or asynchronously. The default is asynchronously.

IInternetProtocolRoot::Continue

HRESULT Continue(
    [in] PROTOCOLDATA *pPROTOCOLDATA
);

Allows the pluggable protocol handler to continue processing data on the apartment thread. This method is called in response to a call to IInternetProtocolSink::Switch.

pPROTOCOLDATA
Holder for the PROTOCOLDATA structure data passed to IInternetProtocolSink::Switch.

IInternetProtocolRoot::Resume

Not currently implemented.

IInternetProtocolRoot::Start

HRESULT Start(
    [in] LPCWSTR szUrl,
    [in] IInternetProtocolSink *pOIProtSink,
    [in] IInternetBindInfo *pOIBindInfo,
    [in] DWORD grfPI,
    [in] DWORD dwReserved
);

Starts the operation.

szUrl
String value containing the URL. For a pluggable MIME filter, this parameter contains the MIME type.
pOIProtSink
Address of the protocol sink provided by the client.
pOIBindInfo
Address of the IInternetBindInfo interface from which the protocol gets download-specific information.
grfPI
DWORD value containing the flags that determine if the method only parses or if it parses and downloads the URL. Can be one of the PI_FLAGS values.
dwReserved
For pluggable MIME filters, it contains the address of a PROTOCOLFILTERDATA structure. Otherwise, it is reserved and must be set to zero.

INET_E_USE_DEFAULT_PROTOCOLHANDLER can only be returned by a pluggable name-space handler or MIME filter. Only a single permanently registered asynchronous pluggable protocol handler can be assigned to a particular scheme (like FTP), so there are no other handlers to default to.

IInternetProtocolRoot::Suspend

Not currently implemented.

IInternetProtocolRoot::Terminate

HRESULT Terminate(
    [in] DWORD dwOptions
);

Releases the resources used by the pluggable protocol handler.

dwOptions
Reserved. Must be set to zero.

Notes to Implementers:

The Urlmon.dll will not call this method until your asynchronous pluggable protocol handler calls Urlmon.dll's IInternetProtocolSink::ReportResult method. When your IInternetProtocolRoot::Terminate method is called, your asynchronous pluggable protocol handler should free all of the resources it has allocated.

Notes to Callers:

This method should be called after receiving a call to your IInternetProtocolSink::ReportResult method and after the protocol handler's IInternetProtocol::LockRequest method has been called.

IInternetProtocolSink::ReportData

HRESULT ReportData(
    [in] DWORD grfBSCF,
    [in] ULONG ulProgress,
    [in] ULONG ulProgressMax
);

Reports the amount of data that is available on the thread.

grfBSCF
DWORD value that evaluates to a BSCF value that indicates the type of data available. BSCF_LASTDATANOTIFICATION indicates that all available data has been reported.
ulProgress
Unsigned long integer value that indicates the progress made so far.
ulProgressMax
Unsigned long integer value that indicates the total amount of work to be done.

IInternetProtocolSink::ReportProgress

HRESULT ReportProgress(
    [in] ULONG ulStatusCode,
    [in] LPCWSTR szStatusText
);

Reports progress made during a state operation.

ulStatusCode
BINDSTATUS value that indicates the status of the state operation.
szStatusText
String value that describes the status of the state operation.

Asynchronous pluggable protocol handlers should not generate the BINDSTATUS_BEGINDOWNLOADDATA, BINDSTATUS_ENDDOWNLOADDATA, and BINDSTATUS_DOWNLOADINGDATA reports, since they are generated internally when the data arrives.

IInternetProtocolSink::ReportResult

HRESULT ReportResult(
    [in] HRESULT hrResult,
    [in] DWORD dwError,
    [in] LPCWSTR szResult
);

Reports the result of the operation when called on any thread.

hrResult
HRESULT value that indicates the result returned by the operation.
dwError
Unsigned long integer value that is a protocol-specific code.
szResult
Protocol-specific result string that should be NULL if the operation succeeded.

Notes to Implmenters:

After your IInternetProtocolSink::ReportResult is called, your application should call the protocol handler's IInternetProtocol::LockRequest method to lock the resource you are reading from the protocol handler. Then your application should call the protocol handler's IInternetProtocolRoot::Terminate.

Note to Callers:

The call to IInternetProtocolSink::ReportResult is the last call that your pluggable protocol handler must make to the client application's IInternetProtocolSink interface.

IInternetProtocolSink::Switch

HRESULT Switch(
    [in] PROTOCOLDATA *pPROTOCOLDATA
);

Passes data from an asynchronous pluggable protocol's worker thread intended for the same asynchronous pluggable protocol's apartment thread. The IInternetProtocolSink should pass this data, without modification, back to the asynchronous pluggable protocol by calling its IInternetProtocolRoot::Continue method.

pPROTOCOLDATA
Address of a PROTOCOLDATA structure containing the data to be passed back to the apartment thread.

Asynchronous pluggable protocol handlers may operate asynchronously in a separate worker thread. This method allows the protocol handler to pass data back to the apartment (or user interface) thread it was created on.

IInternetSecurityManager::GetSecurityId

HRESULT GetSecurityId(
    [in] LPCWSTR pwszUrl,
    [out] BYTE *pbSecurityId,
    [in, out] DWORD *pcbSecurityId,
    [in] DWORD dwReserved
);

Retrieves the security identification of the given URL.

pwszUrl
String value that contains the URL.
pbSecurityId
Address of a buffer that contains the scheme, domain name, and zone associated with the URL.
pcbSecurityId
Address of a double-word value containing the size of the buffer being passed in.
dwReserved
Unsigned that indicates the domain to use. If set to zero, the full domain name is used. Otherwise, a string value containing a suffix to the domain name may be specified. This larger domain name, the full domain name combined with the suffix, will be used as the security ID.

If successful, pbSecurityId contans the scheme, domain, and zone information in the following format:

<scheme>:<domain>+<zone>

and pcbSecurityID will contain the actual size of the data stored in the buffer.

IInternetSecurityManager::GetSecuritySite

HRESULT GetSecuritySite(
    [out] IInternetSecurityMgrSite **ppSite

Retrieves the security site manager.

ppSite
Address of a pointer to the current IInternetSecurityMgrSite interface.

IInternetSecurityManager::GetZoneMappings

HRESULT GetZoneMappings(
    [in] DWORD dwZone,
    [out] IEnumString **ppenumString,
    [in] DWORD dwFlags
);

Retrieves the complete set of patterns mapped to a zone.

dwZone
DWORD value that contains the zone index.
ppenumString
Address of a pointer to the IEnumString interface that will enumerate the strings for the security zone mappings.
dwFlags
Reserved. Must be set to zero.

IInternetSecurityManager::MapUrlToZone

HRESULT MapUrlToZone(
    [in] LPCWSTR pwszUrl,
    [out] DWORD *pdwZone,
    [in] DWORD dwFlags
);

Retrieves the zone index for the given URL.

pwszUrl
String value that contains the URL.
pdwZone
Address of a double-word variable that contains the zone index.
dwFlags
Double-word value that contains flags that control this method. If the value is set to ISECMGR_PREPEND_FILE, IInternetSecurityManager::MapUrlToZone adds the "file:" to the beginning of the URL stored in pwszUrl.

IInternetSecurityManager::ProcessUrlAction

HRESULT ProcessUrlAction(
    [in] LPCWSTR pwszUrl,
    [in] DWORD dwAction,
    [out] BYTE *pPolicy 
    [in] DWORD cbPolicy,
    [in] DWORD dwReserved
);

Determines the policy for the specified action and displays a user interface if the policy indicates that the user should be queried.

pwszUrl
String value that contains the URL.
dwAction
Double-word value that contains the action to be performed. Can be one of the URL Action Flags values.
pPolicy
Address of the buffer where the policy for the given URL and action will be stored. Can contain one of the URL Policy Flags values.
cbPolicy
Double-word value that contains the size of the buffer.
dwReserved
Reserved. Must be set to zero.

IInternetSecurityManager::QueryCustomPolicy

HRESULT QueryCustomPolicy(
    [in] LPCWSTR pwszUrl,
    [in] REFGUID guidKey,
    [out] BYTE **ppPolicy,
    [out] DWORD *pcbPolicy,
    [in] BYTE *pContext
    [in] DWORD cbContext,
    [in] DWORD dwReserved
);

Retrieves the custom policy associated with the URL and specified key in the given context.

pwszUrl
String value containing the URL.
guidKey
Globally unique identifier associated with the custom policy.
ppPolicy
Address of a pointer to the buffer to store the policy information.
pcbPolicy
Address of a double-word value that contains the policy buffer size.
pContext
Address of a buffer that contains the context information.
cbContext
Unsigned long integer value that contains the size of the context buffer.
dwReserved
Reserved. Must be set to zero.

IInternetSecurityManager::SetSecuritySite

HRESULT SetSecuritySite (
    [in, unique] IInternetSecurityMgrSite *pSite

Sets the security site manager.

pSite
Address of the IInternetSecurityMgrSite interface to set.

IInternetSecurityManager::SetZoneMapping

HRESULT SetZoneMapping(
    [in] DWORD dwZone,
    [in] LPCWSTR lpszPattern,
    [in] DWORD dwFlags
);

Maps a pattern into the specified zone.

dwZone
Double-word value that contains the zone index.
lpszPattern
String value that contains the URL pattern with a limited number of wildcards.
dwFlags
Double-word value that indicates whether the mappings should be added or deleted. Can be one of the SZM_FLAGS values.

IInternetSecurityMgrSite::EnableModeless

HRESULT EnableModeless(
    [in] BOOL fEnable
);

Enables the use of modeless pop-up windows.

fEnable
Boolean value that sets whether modeless pop-up windows are used. TRUE enables modeless pop-up windows; FALSE disables them.

IInternetSecurityMgrSite::GetWindow

HRESULT GetWindow(
    [out] HWND *phwnd
);

Retrieves the parent window handle.

phwnd
Address of the parent window handle.

IInternetSession::CreateBinding

HRESULT CreateBinding(
    [in] LPBC pBC,
    [in] LPCWSTR szUrl,
    [in] IUnknown *pUnkOuter,
    [out, unique] IUnknown **ppUnk,
    [out, unique] IInternetProtocol **ppOInetProt,
    [in] DWORD dwOption
);

Not currently implemented.

IInternetSession::GetCache

HRESULT GetCache(
    [out, unique] IInternetCache **ppOInetCache,
    [in] DWORD dwOption
);

Not currently implemented. Must return E_NOTIMPL.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.