Asynchronous and URL Monikers OverviewAsynchronous and URL Monikers Overview*
*Contents  *Index  *Topic Contents
*Previous Topic: Asynchronous and URL Monikers
*Next Topic: Appendix A: MIME Type Detection in Internet Explorer 4.0

Asynchronous and URL Monikers Overview

Monikers bind objects or Uniform Resource Locators (URLs). This section covers the moniker functionality exported by the Urlmon.dll dynamic-link library (DLL).

arrowy.gifIntroduction

arrowy.gifAbout URLs and Name Spaces

arrowy.gifAbout Monikers

arrowy.gifCreating a URL Moniker

arrowy.gifHandling BINDINFO Structures

arrowy.gifUsing the URL Functions

arrowy.gifAppendix A: MIME Type Detection in Internet Explorer 4.0

Introduction

If you want to compile programs that use the functionality provided in Urlmon.dll, 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.

This documentation assumes that you have an understanding of Microsoft® Win32® programming. Also, for asynchronous monikers, asynchronous pluggable protocols, and URL monikers you should have 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 http://ds.internic.net/rfc/rfc1738.txt.External Link

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 portion 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 monikers, URL monikers, and the URL functions come in.

Asynchronous Monikers

The functionality provided in Urlmon.dll allows a client program to create monikers that can instantiate a named object and return a pointer to one of the object's interfaces asynchronously.

Interfaces related to asynchronous monikers

Functions related to asynchronous monikers

URL Monikers

A URL moniker is a specific implementation of asynchronous monikers that allows a client program to create a moniker whose data is referenced by a URL.

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:

  1. Optional, but recommended. Implement the IBindStatusCallback interface.
  2. Optional, but recommended. Create an instance of your IBindStatusCallback interface.
  3. Call CreateURLMoniker with the URL and get the IMoniker interface.
  4. Call CreateAsyncBindCtx and get the IBindCtx interface.
  5. If IBindStatusCallback has been implemented, call RegisterBindStatusCallback with the IBindCtx and IBindStatusCallback interfaces.
  6. 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 may 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.
  7. 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.

  8. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStartBinding method will be called.
  9. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnProgress method will be called.
  10. If IBindStatusCallback has been implemented, either IBindStatusCallback::OnDataAvailable (if IMoniker::BindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IMoniker::BindToObject was used) will be called.
  11. If IBindStatusCallback has been implemented, steps 9 and 10 are repeated until the binding is completed.
  12. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStopBinding method will be called.

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

  1. Optional, but recommended. Implement the IBindStatusCallback interface.
  2. Optional, but recommended. Create an instance of the IBindStatusCallback interface.
  3. Call CreateAsyncBindCtx and get the IBindCtx interface.
  4. Call IBindHost::CreateMoniker with the IBindCtx interface and get the IMoniker interface.
  5. Call one of the IBindHost binding methods (either IBindHost::MonikerBindToStorage or IBindHost::MonikerBindToObject) with the IBindCtx, IMoniker, and IBindStatusCallback (if implemented) interfaces.
  6. 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.

  7. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnStartBinding method will be called.
  8. If IBindStatusCallback has been implemented, the IBindStatusCallback::OnProgress method will be called.
  9. If IBindStatusCallback has been implemented, either IBindStatusCallback::OnDataAvailable (if IBindHost::MonikerBindToStorage was used) or IBindStatusCallback::OnObjectAvailable (if IBindHost::MonikerBindToObject was used) will be called.
  10. If IBindStatusCallback has been implemented, steps 8 and 9 are repeated until the binding is completed.
  11. 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:

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();

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.