Creating and Using URL Monikers

  • Article

There are two ways of viewing the use of monikers: as a moniker client and as a moniker provider. A moniker client is a component that uses a moniker to get a pointer to another object. A moniker provider is a component that supplies monikers that identify its objects to moniker clients.

  • Prerequisites and Requirements
  • Creating a URL Moniker
  • Handling BINDINFO Structures
  • URL Moniker Functions
  • Using the Functions

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

To compile programs that use the URL monikers, 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.

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

  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 in Microsoft Internet Explorer 4.0 and later. 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 in Internet Explorer 4.0 and later. 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  MSHTML does not support the IBindStatusCallback interface. Applications that are hosting MSHTMLand 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;

Because the size of the BINDINFO structure has increased in Internet Explorer 4.0 and later, 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.
}

URL Moniker Functions

The URL functions combine the capabilities of asynchronous monikers and URL monikers into easy-to-use functions. The following list contains the URL functions that are currently supported.

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