
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.
| S_OK | Success, and any additional headers specified are appended. |
| E_ABORT | The HTTP transaction has been terminated. |
| E_INVALIDARG | A parameter is invalid. |
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
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.
| S_OK | The operation completed successfully. If dwResponseCode indicates an error, any szAdditionalRequestHeaders are appended and the request is sent again. |
| E_ABORT | Terminate the HTTP transaction. |
| E_INVALIDARG | The parameter is invalid. |
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
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.
HRESULT GetBindInfo(
[out] DWORD *grfBINDF,
[in, out, unique] BINDINFO * pbindinfo
);
Gets the BINDINFO structure associated with the binding operation.
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.
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.
This method is used if the protocol requires any additional information, such as a username or password, needed to access a URL.
HRESULT GetSecurityId(
[out] BYTE *pbSecurityId,
[in, out] DWORD *pcbSecurityId,
[in] DWORD dwReserved
);
Retrieves the security identification of the host.
| E_INVALIDARG | The buffer is set to NULL or the string passed in to pwszUrl is not a valid URL. |
| S_OK | Successful. |
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.
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.
| E_OUTOFMEMORY | Not enough memory to complete the operation. |
| S_OK | Successful and the URL policy is URLPOLICY_ALLOW. |
| S_FALSE | Found a valid URL policy that is not URLPOLICY_ALLOW. |
The method may also return an HRESULT derrived from the Win32 error code, ERROR_NOT_FOUND, if the URL action could not be read from the registry.
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.
| E_OUTOFMEMORY | Not enough memory to complete the operation. |
| S_OK | Successful. |
This method can also return the HRESULT derrived from the Win32 error code, ERROR_NOT_FOUND, if the action could not be read from the registry.
HRESULT LockRequest(
[in] DWORD dwOptions
);
Locks the requested resource so that IInternetProtocolRoot::Terminate can be called and the remaining data can be read.
For asynchronous pluggable protocols that do not need to lock a request, the method should just return S_OK.
HRESULT Read(
[out] LPVOID pv,
[in] ULONG cb,
[out] ULONG *pcbRead
);
Reads data retrieved by the pluggable protocol handler.
| INET_E_DATA_NOT_AVAILABLE | There is no more data available from the server, but more data was expected. |
| INET_E_DOWNLOAD_FAILURE | The read failed. |
| E_PENDING | The read operation is pending. |
| S_OK | The read was successful, but there is still additional data available. |
| S_FALSE | All of the data has been completely downloaded. |
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.
HRESULT Seek(
[in] LARGE_INTEGER dlibMove,
[in] DWORD dwOrigin,
[out] ULARGE_INTEGER *plibNewPosition
);
Moves the current seek offset.
HRESULT UnlockRequest();
Frees any resources associated with a lock.
This method is called only if IInternetProtocol::LockRequest was called.
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.
| S_OK | Success. |
| S_FALSE | The buffer was too small to contain the resulting URL. |
| INET_E_DEFAULT_ACTION |
| ICU_BROWSER_MODE |
| ICU_ENCODE_SPACES_ONLY |
| ICU_DECODE |
| ICU_NO_ENCODE |
| ICU_NO_META |
For more information on the dwCombineFlags values, see the InternetCombineUrl function in the Win32 Internet Functions Reference.
HRESULT CompareUrl(
[in] LPCWSTR pwzUrl1,
[in] LPCWSTR pwzUrl2,
[in] DWORD dwCompareFlags
);
Compares two URLs and determines if they are equal.
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.
| S_OK | Success. |
| S_FALSE | The buffer was too small to contain the resulting URL. |
| INET_E_DEFAULT_ACTION |
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.
| S_OK | The information requested was retrieved successfully. |
| S_FALSE | The buffer was too small to store the information. |
| INET_E_QUERYOPTION_UNKNOWN | The option requested is unknown. |
HRESULT Abort(
[in] HRESULT hrReason,
[in] DWORD dwOptions
);
Aborts an operation that is in progress.
| S_OK | Success. |
| E_PENDING | The operation started and will complete asynchronously. |
| INET_E_xxx | Internet-specific errors. |
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.
| S_OK | Success. |
| E_PENDING | The next state will complete asynchronously. |
| INET_E_xxx | Internet-specific errors. |
Not currently implemented.
HRESULT Start(
[in] LPCWSTR szUrl,
[in] IInternetProtocolSink *pOIProtSink,
[in] IInternetBindInfo *pOIBindInfo,
[in] DWORD grfPI,
[in] DWORD dwReserved
);
Starts the operation.
| S_OK | Success. |
| E_PENDING | The operation started and will complete asynchronously. |
| INET_E_USE_DEFAULT_PROTOCOLHANDLER | The handler cannot handle this URL, so the default handler should be used. |
| INET_E_xxx | Internet-specific errors. |
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.
Not currently implemented.
HRESULT Terminate(
[in] DWORD dwOptions
);
Releases the resources used by the pluggable protocol handler.
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.
HRESULT ReportData(
[in] DWORD grfBSCF,
[in] ULONG ulProgress,
[in] ULONG ulProgressMax
);
Reports the amount of data that is available on the thread.
HRESULT ReportProgress(
[in] ULONG ulStatusCode,
[in] LPCWSTR szStatusText
);
Reports progress made during a 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.
HRESULT ReportResult(
[in] HRESULT hrResult,
[in] DWORD dwError,
[in] LPCWSTR szResult
);
Reports the result of the operation when called on any thread.
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.
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.
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.
HRESULT GetSecurityId(
[in] LPCWSTR pwszUrl,
[out] BYTE *pbSecurityId,
[in, out] DWORD *pcbSecurityId,
[in] DWORD dwReserved
);
Retrieves the security identification of the given URL.
| E_INVALIDARG | The buffer is set to NULL or the string passed in to pwszUrl is not a valid URL. |
| S_OK | Successful. |
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.
HRESULT GetSecuritySite(
[out] IInternetSecurityMgrSite **ppSite
Retrieves the security site manager.
HRESULT GetZoneMappings(
[in] DWORD dwZone,
[out] IEnumString **ppenumString,
[in] DWORD dwFlags
);
Retrieves the complete set of patterns mapped to a zone.
| E_OUTOFMEMORY | Not enough memory to complete the operation. |
| S_OK | Successful. |
HRESULT MapUrlToZone(
[in] LPCWSTR pwszUrl,
[out] DWORD *pdwZone,
[in] DWORD dwFlags
);
Retrieves the zone index for the given URL.
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.
| E_OUTOFMEMORY | Not enough memory to complete the operation. |
| S_OK | Successful and the URL policy is URLPOLICY_ALLOW. |
| S_FALSE | Found a valid URL policy that is not URLPOLICY_ALLOW. |
The method may also return an HRESULT derrived from the Win32 error code, ERROR_NOT_FOUND, if the URL action could not be read from the registry.
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.
| E_OUTOFMEMORY | Not enough memory to complete the operation. |
| S_OK | Successful. |
This method can also return the HRESULT derrived from the Win32 error code, ERROR_NOT_FOUND, if the action could not be read from the registry.
HRESULT SetSecuritySite (
[in, unique] IInternetSecurityMgrSite *pSite
Sets the security site manager.
HRESULT SetZoneMapping(
[in] DWORD dwZone,
[in] LPCWSTR lpszPattern,
[in] DWORD dwFlags
);
Maps a pattern into the specified zone.
| S_OK | Success. |
| E_ACCESSDENIED | Attempting to enter a non-SSL site into a zone which requires server verification. |
| URL_E_INVALID_SCHEME | Either an improper scheme or no scheme specified in the URL. |
| E_FAIL | Mapping already exists. |
The method can also return the HRESULT derrived from the Win32 error code, ERROR_FILE_EXISTS, if the URL already exists in another zone.
HRESULT EnableModeless(
[in] BOOL fEnable
);
Enables the use of modeless pop-up windows.
HRESULT GetWindow(
[out] HWND *phwnd
);
Retrieves the parent window handle.
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.
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.