URL Monikers Overview

A URL moniker is a system-provided moniker class that supports asynchronous binding to a Uniform Resource Locator (URL). This section covers the moniker functionality exported by the Urlmon.dll dynamic-link library (DLL).

Prerequisites and Requirements

This documentation assumes that you have an understanding of Microsoft® Win32® programming and an understanding of OLE and COM programming. For the Internet-related interfaces, methods, and functions, an understanding of the format and syntax of URLs is also required. For more information, see RFC 1738, Uniform Resource Locators (URL). You can find this document at ftp://ftp.isi.edu/in-notes/rfc1738.txt.

To compile programs that use the URL monikers, you must make sure the Urlmon.h header file is in the include directory, and the Urlmon.lib library file is in the library directory, of the C/C++ compiler you use.

About URLs and Name Spaces

A Uniform Resource Locator (URL) follows the syntax described in RFC 1738, which specifies a protocol scheme followed by a scheme-specific portion (<scheme>:<scheme-specific portion>). For example, in the URL http://www.microsoft.com/, "http" is the scheme and "//www.microsoft.com/" is the scheme-specific portion.

The beginning part of the scheme-specific portion of the URL contains the server name. This portion of the URL is often referred to as the URL name space.

About Monikers

Monikers are used as the basis for linking in OLE. After a moniker is bound to an object, the moniker's IMoniker interface can be used to locate, activate, and access the bound object without having any other specific information on where the actual object is located. For standard monikers, this binding process occurs synchronously, which does not impact performance dramatically because the moniker and object are usually on a local system. Examples of objects that can be bound to a moniker include files, items, and pointers.

Binding a moniker to a URL synchronously impacts performance because the process has to wait for responses from the network before completing the binding process. That is where asynchronous URL monikers and the URL functions come in.

Interfaces related to URL monikers

Functions related to URL monikers

URL Functions

The URL functions combine the capabilities of asynchronous monikers and URL monikers into easy-to-use functions.

URL functions

Creating a URL Moniker

Follow these steps to create a URL moniker for an application:

Optional, but recommended. Implement the IBindStatusCallback interface.
Optional, but recommended. Create an instance of your IBindStatusCallback interface.
Call CreateURLMoniker with the URL and get the IMoniker interface.
Call CreateAsyncBindCtx and get the IBindCtx interface.
If IBindStatusCallback has been implemented, call RegisterBindStatusCallback with the IBindCtx and IBindStatusCallback interfaces.
Call one of the IMoniker binding methods (either IMoniker::BindToStorage or IMoniker::BindToObject) with the IBindCtx interface. In the asynchronous case (where IBindStatusCallback has been 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.
If IBindStatusCallback has been implemented, the IBindStatusCallback::GetBindInfo method is called by the IMoniker binding method to get the bind information.
Warning The size of the BINDINFO structure used by IBindStatusCallback::GetBindInfo 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 the IBindStatusCallback::GetBindInfo method before writing to members of the structure. For more information, see the Handling BINDINFO Structures section.
If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStartBinding method will be called.
If IBindStatusCallback has been implemented, the IBindStatusCallback::OnProgress method will be called.
If IBindStatusCallback has been implemented, either IBindStatusCallback::OnDataAvailable (if IMoniker::BindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IMoniker::BindToObject was used) will be called.
If IBindStatusCallback has been implemented, steps 9 and 10 are repeated until the binding is completed.
If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStopBinding method will be called.

Follow these steps to create a URL moniker for a control:

Optional, but recommended. Implement the IBindStatusCallback interface.
Optional, but recommended. Create an instance of the IBindStatusCallback interface.
Call CreateAsyncBindCtx and get the IBindCtx interface.
Call IBindHost::CreateMoniker with the IBindCtx interface and get the IMoniker interface.
Call one of the IBindHost binding methods (either IBindHost::MonikerBindToStorage or IBindHost::MonikerBindToObject) with the IBindCtx, IMoniker, and IBindStatusCallback (if implemented) interfaces.
If IBindStatusCallback has been implemented, the IBindStatusCallback::GetBindInfo method is called by the IMoniker binding method to get the bind information.
Warning The size of the BINDINFO structure used by IBindStatusCallback::GetBindInfo 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 the IBindStatusCallback::GetBindInfo method before writing to members of the structure. For more information, see the Handling BINDINFO Structures section.
If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStartBinding method will be called.
If IBindStatusCallback has been implemented, the IBindStatusCallback::OnProgress method will be called.
If IBindStatusCallback has been implemented, either IBindStatusCallback::OnDataAvailable (if IBindHost::MonikerBindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IBindHost::MonikerBindToObject was used) will be called.
If IBindStatusCallback has been implemented, steps 8 and 9 are repeated until the binding is completed.
If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStopBinding method will be called.

Note IE4/MSHTML does not support the IBindStatusCallback interface. Applications that are hosting IE4/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 properly write information to this structure, the client application should:

Clear the BINDINFO structure.
Check the size of the BINDINFO structure to determine what version has been passed.

Clearing the BINDINFO structure, before writing information into it, prevents members that are not being used from containing incorrect data. The following code fragment demonstrates how to clear the structure.

// pbindinfo is a pointer to a BINDINFO structure.
DWORD cbSize = pbindinfo->cbSize;        
memset(pbindinfo,0,cbSize);
pbindinfo->cbSize = cbSize;

Since the size of the BINDINFO structure has increased in 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 sample demonstrates 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.
}

Using the URL Functions

The URLDownloadToCacheFile, URLDownloadToFile, URLOpenBlockingStream, URLOpenPullStream, and URLOpenStream functions combine the capabilities of asynchronous monikers and URL monikers into easy-to-use functions.

The following sample demonstrates how to use the URLOpenBlockingStream function.

IStream* pStream;
char buffer[0x100];
DWORD dwGot;
HRESULT hr = NOERROR;

// Open a blocking type stream to the Web site stored in the string szWebSite.
URLOpenBlockingStream( 0, szWebSite, &pStream, 0, 0);

do {
    hr = pStream->Read( buffer, sizeof(buffer), &dwGot );
    // Do something with contents of buffer. 
} while( SUCCEEDED(hr) && hr != S_FALSE);

return TRUE;

pStream->Release();