Methods

Methods


This section contains the methods exposed by monikers, URLs, security zones, and pluggable protocols.
IAuthenticate::Authenticate
IBindHost::CreateMoniker
IBindHost::MonikerBindToObject
IBindHost::MonikerBindToStorage
IBindHost::RemoteMonikerBindToObject
IBindHost::RemoteMonikerBindToStorage
IBinding::Abort
IBinding::GetBindResult
IBinding::GetPriority
IBinding::RemoteGetBindResult
IBinding::Resume
IBinding::SetPriority
IBinding::Suspend
IBindStatusCallback::GetBindInfo
IBindStatusCallback::GetPriority
IBindStatusCallback::OnDataAvailable
IBindStatusCallback::OnLowResource
IBindStatusCallback::OnObjectAvailable
IBindStatusCallback::OnProgress
IBindStatusCallback::OnStartBinding
IBindStatusCallback::OnStopBinding
IHttpNegotiate::BeginningTransaction
IHttpNegotiate::OnResponse
IHttpSecurity::OnSecurityProblem
IInternetBindInfo::GetBindInfo
IInternetBindInfo::GetBindString
IInternetHostSecurityManager::GetSecurityId
IInternetHostSecurityManager::ProcessUrlAction
IInternetHostSecurityManager::QueryCustomPolicy
IInternetProtocol::LockRequest
IInternetProtocol::Read
IInternetProtocol::Seek
IInternetProtocol::UnlockRequest
IInternetProtocolInfo::CombineUrl
IInternetProtocolInfo::CompareUrl
IInternetProtocolInfo::ParseUrl
IInternetProtocolInfo::QueryInfo
IInternetProtocolRoot::Abort
IInternetProtocolRoot::Continue
IInternetProtocolRoot::Resume
IInternetProtocolRoot::Start
IInternetProtocolRoot::Suspend
IInternetProtocolRoot::Terminate
IInternetProtocolSink::ReportData
IInternetProtocolSink::ReportProgress
IInternetProtocolSink::ReportResult
IInternetProtocolSink::Switch
IInternetSecurityManager::GetSecurityId
IInternetSecurityManager::GetSecuritySite
IInternetSecurityManager::GetZoneMappings
IInternetSecurityManager::MapUrlToZone
IInternetSecurityManager::ProcessUrlAction
IInternetSecurityManager::QueryCustomPolicy
IInternetSecurityManager::SetSecuritySite
IInternetSecurityManager::SetZoneMapping
IInternetSecurityMgrSite::EnableModeless
IInternetSecurityMgrSite::GetWindow
IInternetSession::CreateBinding
IInternetSession::GetCache
IInternetSession::GetSessionOption
IInternetSession::RegisterMimeFilter
IInternetSession::RegisterNameSpace
IInternetSession::SetCache
IInternetSession::SetSessionOption
IInternetSession::UnregisterMimeFilter
IInternetSession::UnregisterNameSpace
IInternetZoneManager::CreateZoneEnumerator
IInternetZoneManager::DestroyZoneEnumerator
IInternetZoneManager::GetZoneActionPolicy
IInternetZoneManager::GetZoneAt
IInternetZoneManager::GetZoneAttributes
IInternetZoneManager::GetZoneCustomPolicy
IInternetZoneManager::LogAction
IInternetZoneManager::PromptAction
IInternetZoneManager::SetZoneActionPolicy
IInternetZoneManager::SetZoneAttributes
IInternetZoneManager::SetZoneCustomPolicy
IPersistMoniker::GetCurMoniker
IPersistMoniker::IsDirty
IPersistMoniker::Load
IPersistMoniker::Save
IPersistMoniker::SaveCompleted
IWindowForBindingUI::GetWindow
IWinInetHttpInfo::QueryInfo
IWinInetHttpInfo::RemoteQueryInfo
IWinInetInfo::QueryOption
IWinInetInfo::RemoteQueryOption

IAuthenticate::Authenticate

HRESULT Authenticate(
    [out] HWND *phwnd,
    [out] LPWSTR *pszUserName,
    [out] LPWSTR *pszPassword
);

Supplies authentication support to a URL moniker from a client application.

phwnd
Address of a client-provided HWND of the parent window for a default user interface. If no user interface is desired, the client must provide a username and password in the other parameters, and this handle is set to zero.
pszUserName
String that contains the username to use for authentication. If the client returns a value here, it should also set phwnd to zero.
pszPassword
String that contains the password to use for authentication. If the client returns a value here, it should also set phwnd to zero.

The default user interface is able to handle any authentication schemes recognized by the Win32 Internet API. Currently, the username and password options only handle the Basic authentication scheme.

This method is related to the InternetErrorDlg function in the Win32 Internet API. For more information about the Win32 Internet API, see Win32 Internet Functions Overview.

IBindHost::CreateMoniker

HRESULT CreateMoniker (
    [in] LPOLESTR szName,
    [in] IBindCtx *pBC,
    [out] IMoniker **ppmk,
    [in] DWORD dwReserved
);

Creates a moniker to bind to a URL.

szName
URL to bind to.
pBC
Address of the IBindCtx interface.
ppmk
Address of the pointer to the moniker that is created.
dwReserved
Reserved. Must be set to zero.

IBindHost::MonikerBindToObject

HRESULT MonikerBindToObject (
    [in] IMoniker *pMk,
    [in] IBindCtx *pBC,
    [in] IBindStatusCallback *pBSC,
    [in] REFIID riid,
    [out] void **ppvObj
);

Binds a moniker to an object.

pMk
Address of the IMoniker interface.
pBC
Address of the IBindCtx interface.
pBSC
Address of the IBindStatusCallback interface.
riid
IID of the interface that the client application wants to use to communicate with the object.
ppvObj
Address of the interface identified by riid. If ppvObj is non-NULL, the application must call the IUnknown::AddRef method on the interface and call IUnknown::Release when it is finished using the interface.

IBindHost::MonikerBindToStorage

HRESULT MonikerBindToStorage (
    [in] IMoniker *pMk,
    [in] IBindCtx *pBC,
    [in] IBindStatusCallback *pBSC,
    [in] REFIID riid,
    [out] void **ppvObj
);

Binds a moniker to storage.

pMk
Address of the IMoniker interface.
pBC
Address of the IBindCtx interface.
pBSC
Address of the IBindStatusCallback interface.
riid
IID of the storage interface requested.
ppvObj
Address of the storage interface. If ppvObj is non-NULL, the application must call the IUnknown::AddRef method on the interface and call IUnknown::Release when it is finished using the interface.

IBindHost::RemoteMonikerBindToObject

HRESULT RemoteMonikerBindToObject (
    [in] IMoniker *pMk,
    [in] IBindCtx *pBC,
    [in] IBindStatusCallback *pBSC,
    [in] REFIID riid,
    [out] IUnknown **ppvObj
);

Remotely binds a moniker to an object.

pMk
Address of the IMoniker interface.
pBC
Address of the IBindCtx interface.
pBSC
Address of the IBindStatusCallback interface.
riid
IID of the interface that the client application wants to use to communicate with the object.
ppvObj
Address of the interface identified by riid. If ppvObj is non-NULL, the application must call the IUnknown::AddRef method on the interface and call IUnknown::Release when it is finished using the interface.

IBindHost::RemoteMonikerBindToStorage

HRESULT RemoteMonikerBindToStorage (
    [in] IMoniker *pMk,
    [in] IBindCtx *pBC,
    [in] IBindStatusCallback *pBSC,
    [in] REFIID riid,
    [out] IUnknown **ppvObj
);

Remotely binds a moniker to storage.

pMk
Address of the IMoniker interface.
pBC
Address of the IBindCtx interface.
pBSC
Address of the IBindStatusCallback interface.
riid
IID of the storage interface requested.
ppvObj
Address of the storage interface. If ppvObj is non-NULL, the application must call the IUnknown::AddRef method on the interface and call IUnknown::Release when it is finished using the interface.

IBinding::Abort

HRESULT Abort(void);

Permanently ends the bind operation.

IBinding::Abort cannot be called from within an implementation of the IBindStatusCallback::OnStartBinding method.

After aborting the bind operation, the client must still release any pointers obtained during the binding. No other IBindStatusCallback notifications will be called except IBindStatusCallback::OnStopBinding.

Releasing the last IBinding interface does not terminate the bind operation.

See also IBindStatusCallback::OnStopBinding

IBinding::GetBindResult

HRESULT GetBindResult(
    [out] CLSID *pclsidProtocol,
    [out] DWORD *pdwBindResult,
    [out] LPWSTR *pszBindResult,
    [in] DWORD dwReserved
);

Queries the protocol-specific outcome of a bind operation.

pclsidProtocol
Address of the CLSID variable for the protocol used.
pdwBindResult
Address of the DWORD variable containing the protocol-specific bind result string.
pszBindResult
Address of the LPWSTR variable containing the protocol-specific bind result.
dwReserved
Reserved for future use; must be NULL.

This method is typically called by the client of an asynchronous moniker when the client's IBindStatusCallback::OnStopBinding method is called.

See also IBindStatusCallback::OnStopBinding

IBinding::GetPriority

HRESULT GetPriority(
    [out] LONG *pnPriority
);

Not currently implemented.

IBinding::RemoteGetBindResult

HRESULT GetBindResult(
    [out] CLSID *pclsidProtocol,
    [out] DWORD *pdwResult,
    [out] LPOLESTR *pszResult,
    [in] DWORD dwReserved
);

Remotely queries the protocol-specific outcome of a bind operation.

pclsidProtocol
Address of the CLSID variable for the protocol used.
pdwResult
Address of the DWORD variable containing the protocol-specific bind result string.
pszResult
Address of the LPWSTR variable containing the protocol-specific bind result.
dwReserved
Reserved. Must be set to zero.

This method is typically called by the client of an asynchronous moniker when the client's IBindStatusCallback::OnStopBinding method is called.

See also IBindStatusCallback::OnStopBinding

IBinding::Resume

HRESULT Resume(void);

Not currently implemented.

IBinding::SetPriority

HRESULT SetPriority(
    [in] LONG nPriority
);

Not currently implemented.

IBinding::Suspend

HRESULT Suspend(void);

Suspends the bind operation.

IBindStatusCallback::GetBindInfo

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

Obtains the bind information for the bind operation when called by an asynchronous moniker.

pgrfBINDF
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 moniker calls this method in its implementations of the IMoniker::BindToObject and IMoniker::BindToStorage methods to obtain information about the specific bind operation.

Asynchronous moniker clients should be aware that a moniker might call this method more than once during a bind operation. A proper implementation of IBindStatusCallback::GetBindInfo should prepare for this possibility. If returning data in the pbindinfo parameter, the implementation should allocate the appropriate data (szExtraInfo and/or stgmedData) at the time of each call. In this way, if the callback is never called, data is never allocated; if the callback is called more than once, it will work correctly. The first time this callback is received by the asynchronous moniker client is before the call to IMoniker::BindToStorage or IMoniker::BindToObject.

Even when the value of pgrfBINDF is BINDF_ASYNCHRONOUS, it is possible that the original call to IMoniker::BindToStorage or IMoniker::BindToObject might return synchronously rather than returning the MK_S_ASYNCHRONOUS flag. Clients of asynchronous monikers should always prepare for this possibility. Specifically, to avoid memory leaks, it is important to make sure to release the pointer returned by a call to either method.

One way to deal with this case is to call your own implementation of IBindStatusCallback::OnDataAvailable or IBindStatusCallback::OnObjectAvailable in order to use the same code path (regardless of whether you bind synchronously or asynchronously).

If BINDF_PULLDATA value is not in the pgrfBINDF parameter, the Urlmon.dll sets the BINDF_NEEDFILE value. If BINDF_NEEDFILE is set, binding of resources that cannot be cached (like an https resource) will fail.

Warning 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.

See also BINDF, BINDINFO, RegisterBindStatusCallback

IBindStatusCallback::GetPriority

HRESULT GetPriority(
    [out] LONG *pnPriority
);

Obtains the priority for the bind operation when called by an asynchronous moniker.

pnPriority
Address of a LONG value indicating the priority of this bind operation. Priorities can be any of the constants defined for prioritizing threads. For details, see the Win32 documentation for SetThreadPriority and GetThreadPriority.

The moniker calls this method, typically prior to initiating the bind operation, to obtain the priority for the bind operation. This method can be called at any time during the bind operation if the moniker needs to make new priority decisions.

The moniker can use pnPriority to set the priority of a thread associated with a bind operation, but more commonly it will interpret the priority to perform its own scheduling among multiple bind operations. Note that the policy for determining priority for URL monikers is not yet determined. The moniker must not change the priority of the thread used for calling IMoniker::BindToStorage or IMoniker::BindToObject.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.

IBindStatusCallback::OnDataAvailable

HRESULT OnDataAvailable(
    [in] DWORD  grfBSCF,
    [in] DWORD  dwSize,
    [in] FORMATETC *pfmtetc,
    [in] STGMEDIUM *pstgmed
);

Provides data to the client as it becomes available during asynchronous bind operations.

grfBSCF
DWORD value taken from the BSCF enumeration indicating the kind of data available.
dwSize
Size, in bytes, of total data available from the current bind operation.
pfmtetc
Address of the FORMATETC structure that indicates the format of the available data. This parameter is used when the bind operation is a result of the IMoniker::BindToStorage method. If there is no format associated with the available data, pfmtetc might contain CF_NULL. Each different call to IBindStatusCallback::OnDataAvailable can pass in a new value for this parameter, although they all should always point to the same data.
pstgmed
Address of the STGMEDIUM structure that contains the pointers to the interfaces (like IStream and IStorage) that can be used to access the data. In the asynchronous case, client applications may have received a second pointer to the IStream or IStorage interface from the IMoniker::BindToStorage method, which the client application must call IUnknown::Release method on to avoid memory leaks.

During asynchronous IMoniker::BindToStorage bind operations, an asynchronous moniker calls this method to provide data to the client as it becomes available.

Note that the behavior of the storage returned in pstgmed depends on the BINDF flags returned in the IBindStatusCallback::GetBindInfo method. This storage can be asynchronous or blocking, and the bind operation can follow a data pull model or a data push model. Furthermore, it is important to note that for BINDF_PULLDATA bind operations, it is not possible to seek backward into data streams provided in IBindStatusCallback::OnDataAvailable. On the other hand, for data push model bind operations, it is commonly possible to seek back into a data stream and read any data that has been downloaded for an ongoing IMoniker::BindToStorage operation.

See also BINDF, BSCF, IBindStatusCallback::GetBindInfo

IBindStatusCallback::OnLowResource

HRESULT OnLowResource(
    [in] DWORD  dwReserved 	
);		

Not currently implemented.

IBindStatusCallback::OnObjectAvailable

HRESULT OnObjectAvailable(
    [in] REFIID  riid,
    [in] IUnknown *punk
);

Passes the requested object interface pointer to the client. This method is called in response to an IMoniker::BindToObject operation.

riid
Interface identifier of the requested interface.
punk
Address of the IUnknown interface on the object requested in the call to IMoniker::BindToObject. The client should call AddRef on this pointer to maintain a reference to the object.

This method is never called for IMoniker::BindToStorage operations.

See also IBindStatusCallback::OnDataAvailable

IBindStatusCallback::OnProgress

HRESULT OnProgress(
    [in] ULONG  ulProgress,
    [in] ULONG  ulProgressMax,
    [in] ULONG  ulStatusCode,
    [in] LPCWSTR  szStatusText
);

Indicates the current progress of the bind operation.

ulProgress
Current progress of the bind operation relative to the expected maximum indicated in the ulProgressMax parameter.
ulProgressMax
Expected maximum value of the ulProgress parameter for the duration of calls to IBindStatusCallback::OnProgress for this bind operation. Note that this value might change across calls to this method. A value of zero means that the maximum value of ulProgress is unknown (for example, in the IMoniker::BindToStorage method when the data download size is unknown).
ulStatusCode
Additional information regarding the progress of the bind operation. Valid values are taken from the BINDSTATUS enumeration and include:
BINDSTATUS_BEGINDOWNLOADCOMPONENTS The download operation has begun downloading code for COM components that will be installed before the object can be instantiated. The szStatusText parameter accompanying IBindStatusCallback::OnProgress provides the display name of the component being downloaded.
BINDSTATUS_INSTALLINGCOMPONENTS The download operation has downloaded code and is installing it. The szStatusText parameter accompanying IBindStatusCallback::OnProgress provides the display name of the component being installed.
BINDSTATUS_ENDDOWNLOADCOMPONENTS The download operation has finished downloading and installing all the necessary code. The szStatusText parameter accompanying IBindStatusCallback::OnProgress provides the display name of the newly installed component.
szStatusText
Textual information indicating the current progress of the bind operation. The text reflects the BINDSTATUS value of the ulStatusCode parameter and is appropriate for display in the user interface of the client.

The moniker calls this method repeatedly to indicate the current progress of the bind operation, typically at reasonable intervals during a lengthy operation.

The client can use the progress notification to provide progress information to the user from the ulProgress, ulProgressMax, and szStatusText parameters, or to make programmatic decisions based on the ulStatusCode parameter.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.

See also BINDSTATUS

IBindStatusCallback::OnStartBinding

HRESULT OnStartBinding(
    [in] DWORD  dwReserved,
    [in] IBinding *pbinding
);

Notifies the client about the callback methods it is registered to receive. This notification is a response to the flags the client requested in the RegisterBindStatusCallback function.

dwReserved
Reserved for future use. Must be zero.
pbinding
Address of the IBinding interface of the current bind operation. Cannot be NULL. The client should call AddRef on this pointer to keep a reference to the binding object.

Asynchronous monikers typically call this method before the call to the IMoniker::BindToStorage or IMoniker::BindToObject method has returned.

In the call to this method, the moniker also provides the client with a pointer to the IBinding interface for the binding object associated with the current bind operation. The client can use the IBinding interface to control the progress of the bind operation.

To keep a reference to the binding object, the client must store the pointer to the IBinding interface and call AddRef on it. When the client no longer needs the reference, it must call Release on it. Note that calling Release does not cancel the bind operation; it simply frees the reference to the IBinding interface sent in the callback.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.

Also, IBinding::Abort method will not work properly within an implementation of IBindStatusCallback::OnStartBinding.

See also IBinding, IBindStatusCallback::OnStopBinding, RegisterBindStatusCallback

IBindStatusCallback::OnStopBinding

HRESULT OnStopBinding(
    [in] HRESULT  hrStatus,
    [in] LPCWSTR  szStatusText
);

Indicates the end of the bind operation.

hrStatus
Status code returned from the bind operation.
szStatusText
Status text. In case of error, this text describes the error. In the current implementation of URL monikers, this string is empty.

This method is always called, whether the bind operation succeeded, failed, or was aborted by a client. At this point the moniker client can use IBinding::GetBindResult to query for protocol-specific information about the outcome of the bind operation. Once this method has completed, the moniker client must call IUnknown::Release on the IBinding pointer it received in IBindStatusCallback::OnStartBinding.

Since URL monikers work asynchronously, the status code returned by IBindStatusCallback::OnStopBinding and the status code returned by the binding methods (like IMoniker::BindToStorage and IMoniker::BindToObject) may differ.

Notes to implementers

A client can return E_UNIMPL or S_OK if it is not interested in receiving this notification.

See also IBinding, IBindStatusCallback::OnStartBinding

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