Creating a URL Moniker
A version of this page is also available for
4/8/2010
A moniker is a COM object that identifies an object and provides services to allow for other components to obtain a pointer to that object. There are two ways of viewing monikers: as a moniker client, which is a component that uses a moniker to get a pointer to another object, and as a moniker provider. This is a component that supplies monikers identifying its objects to moniker clients.
Procedures
To create a URL moniker for an application
Implement the IBindStatusCallback interface and create an instance of your IBindStatusCallback interface.
Call CreateURLMoniker with the URL and get the IMoniker interface.
Call CreateAsyncBindCtx and get the IBindCtx interface.
Call RegisterBindStatusCallback with the IBindCtx and IBindStatusCallback interfaces.
Call one of the IMoniker binding methods (IMoniker::BindToStorage or IMoniker::BindToObject) with the IBindCtx interface. In the asynchronous case, where IBindStatusCallback is implemented, the client application can get a pointer to the IStream or IStorage interface. The client application should call the IUnknown::Release method on the interface and use the interface returned in the IBindStatusCallback::OnDataAvailable call.
The IMoniker binding method calls IBindStatusCallback::GetBindInfo method to get the bind information.
The IBindStatusCallback::OnStartBinding method will be called.
The IBindStatusCallback::OnProgress method will be called.
If IMoniker::BindToStorage was used, IBindStatusCallback::OnDataAvailable method will be called. If IMoniker::BindToObject was used, IBindStatusCallback::OnObjectAvailable will be called.
Steps 8 and 9 are repeated until the binding is completed. When binding is complete, the IBindStatusCallback::OnStopBinding method will be called.
To create a URL moniker for a control
Implement the IBindStatusCallback interface and create an instance of the IBindStatusCallback interface.
Call CreateAsyncBindCtx and get a pointer to the IBindCtx interface.
Call IBindHost::CreateMoniker with the IBindCtx interface and get a pointer to the IMoniker interface.
Call one of the IBindHost binding methods (IBindHost::MonikerBindToStorage or IBindHost::MonikerBindToObject) with the IBindCtx, IMoniker, and IBindStatusCallback interfaces.
The IMoniker binding method calls the IBindStatusCallback::GetBindInfo method to get the bind information.
The IBindStatusCallback::OnStartBinding method will be called.
The IBindStatusCallback::OnProgress method will be called.
Either IBindStatusCallback::OnDataAvailable (if IBindHost::MonikerBindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IBindHost::MonikerBindToObject was used) will be called.
If IBindStatusCallback is implemented, steps 8 and 9 are repeated until the binding is completed. When binding is completed the IBindStatusCallback::OnStopBinding method will be called.
Note
MSHTML does not support the IBindStatusCallback interface. Applications that are hosting MSHTML and want to get callbacks on the progress of the bind operation should implement the IPropertyNotifySink interface.
Handling BINDINFO Structures
The BINDINFO structure is used by methods, such as IBindStatusCallback::GetBindInfo, to pass information that specifies how a bind operation should be handled. To correctly write information to this structure, the client application should clear the BINDINFO structure and check the size of the BINDINFO structure to determine what version was passed.
Clearing the BINDINFO structure, before writing information into it, prevents members that are not being used from containing incorrect data.
The following code example shows how to clear the structure.
// pbindinfo is a pointer to a BINDINFO structure.
DWORD cbSize = pbindinfo->cbSize;
memset(pbindinfo,0,cbSize);
pbindinfo->cbSize = cbSize;
Because the size of the BINDINFO structure increased effective with Microsoft Internet Explorer 4.0, client applications should check the size of the structure that is passed into their implementation of any methods that use this structure.
The following code example shows how to check the size of the structure for accessing members of the BINDINFO structure beyond cbstgmedData.
if (pbindinfo->cbSize >= offsetof(BINDINFO, dwReserved))
{
// Write to additional fields.
}
else
{
// Added functionality is not available, so make any adjustments necessary.
}