
This section contains the methods exposed by monikers, URLs, security zones, and pluggable protocols.
HRESULT Authenticate(
[out] HWND *phwnd,
[out] LPWSTR *pszUserName,
[out] LPWSTR *pszPassword
);
Supplies authentication support to a URL moniker from a client application.
| S_OK | Authentication was successful. |
| E_ACCESSDENIED | Authentication failed. |
| E_INVALIDARG | One or more of the parameters are invalid. |
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.
HRESULT CreateMoniker (
[in] LPOLESTR szName,
[in] IBindCtx *pBC,
[out] IMoniker **ppmk,
[in] DWORD dwReserved
);
Creates a moniker to bind to a URL.
HRESULT MonikerBindToObject (
[in] IMoniker *pMk,
[in] IBindCtx *pBC,
[in] IBindStatusCallback *pBSC,
[in] REFIID riid,
[out] void **ppvObj
);
Binds a moniker to an object.
HRESULT MonikerBindToStorage (
[in] IMoniker *pMk,
[in] IBindCtx *pBC,
[in] IBindStatusCallback *pBSC,
[in] REFIID riid,
[out] void **ppvObj
);
Binds a moniker to storage.
HRESULT RemoteMonikerBindToObject (
[in] IMoniker *pMk,
[in] IBindCtx *pBC,
[in] IBindStatusCallback *pBSC,
[in] REFIID riid,
[out] IUnknown **ppvObj
);
Remotely binds a moniker to an object.
HRESULT RemoteMonikerBindToStorage (
[in] IMoniker *pMk,
[in] IBindCtx *pBC,
[in] IBindStatusCallback *pBSC,
[in] REFIID riid,
[out] IUnknown **ppvObj
);
Remotely binds a moniker to storage.
HRESULT Abort(void);
Permanently ends the bind operation.
| S_OK | Success. |
| E_FAIL | The bind operation could not be aborted. |
| S_FALSE | The bind operation was already aborted. |
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
HRESULT GetBindResult(
[out] CLSID *pclsidProtocol,
[out] DWORD *pdwBindResult,
[out] LPWSTR *pszBindResult,
[in] DWORD dwReserved
);
Queries the protocol-specific outcome of a bind operation.
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
HRESULT GetPriority(
[out] LONG *pnPriority
);
Not currently implemented.
HRESULT GetBindResult(
[out] CLSID *pclsidProtocol,
[out] DWORD *pdwResult,
[out] LPOLESTR *pszResult,
[in] DWORD dwReserved
);
Remotely queries the protocol-specific outcome of a bind operation.
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
HRESULT Resume(void);
Not currently implemented.
HRESULT SetPriority(
[in] LONG nPriority
);
Not currently implemented.
HRESULT Suspend(void);
Suspends the bind operation.
HRESULT GetBindInfo(
[out] DWORD *pgrfBINDF,
[in, out] BINDINFO *pbindinfo
);
Obtains the bind information for the bind operation when called by an asynchronous moniker.
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
HRESULT GetPriority(
[out] LONG *pnPriority
);
Obtains the priority for the bind operation when called by an asynchronous moniker.
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.
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.
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
HRESULT OnLowResource(
[in] DWORD dwReserved
);
Not currently implemented.
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.
This method is never called for IMoniker::BindToStorage operations.
See also IBindStatusCallback::OnDataAvailable
HRESULT OnProgress(
[in] ULONG ulProgress,
[in] ULONG ulProgressMax,
[in] ULONG ulStatusCode,
[in] LPCWSTR szStatusText
);
Indicates the current progress of the bind operation.
| 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. |
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
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.
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
HRESULT OnStopBinding(
[in] HRESULT hrStatus,
[in] LPCWSTR szStatusText
);
Indicates the end of the bind operation.
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.