Contents Index Topic Contents
	Previous Topic: Pluggable Protocols Next Topic: Appendix A: Registering an Application to a URL Protocol

Pluggable Protocols Overview

Pluggable protocols provide capability create custom URL protocols. This section covers the pluggable protocol functionality exported by the Urlmon.dll dynamic-link library (DLL).

Introduction

About URLs and Name Spaces

About Pluggable Protocols

Creating an Asynchronous Pluggable Protocol Handler

Appendix A: Registering an Application to a URL Protocol

Appendix B: Debugging Tips

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.

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 Pluggable Protocols

Microsoft Internet Explorer uses two mechanisms for registering new URL protocol handlers. The first method is to register a URL protocol and its associated application so that all attempts to navigate to a URL using that protocol launch the application (for example, registering applications to handle mailto: or news: URLs). The second method uses the Asynchronous Pluggable Protocols API, which allows you to define new protocols by mapping the protocol scheme to a class.

For information on how to register an application for a particular URL protocol, see Appendix B: Registering an Application to a URL Protocol.

Asynchronous pluggable protocols offer three ways to map a protocol scheme to a class:

• Permanently registering an asynchronous pluggable protocol handler in the registry. The handler is used for any URLs with the specified scheme (such as http, ftp, and so on).
• Permanently or temporarily registering a pluggable name space handler. The handler is used for any URLs with the specified pattern in the scheme-specific portion of the URL for a particular protocol scheme.
• Permanently or temporarily registering a MIME filter. The handler manipulates the data stream it receives and returns a data stream for any resources of the specified MIME type.

Note All asynchronous pluggable protocols must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

Interfaces related to asynchronous pluggable protocols

• IBindProtocol
• IInternet
• IInternetBindInfo
• IInternetProtocol
• IInternetProtocolInfo
• IInternetProtocolRoot
• IInternetProtocolSink
• IInternetSession

Functions related to asynchronous pluggable protocols

• CoInternetGetSession

About Asynchronous Pluggable Protocols

An asynchronous pluggable protocol handler is an apartment-threaded Component Object Model (COM) object that handles any calls made to the protocol scheme that it is registered for. When a client application makes a request, Urlmon looks up the protocol scheme in the registry and creates an instance of the protocol handler registered for that protocol scheme. If the protocol scheme was successfully mapped to the class identifier (CLSID) of a protocol handler, CoCreateInstance is called with that class asking for an IClassFactory interface. An instance of the protocol handler is obtained with IClassFactory::CreateInstance.

To register a custom URL protocol, add a key for the protocol scheme of the custom URL protocol to the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler\protocol_scheme. Under that key, the string value, CLSID, must be set to the CLSID of the protocol handler.

To register the custom protocol scheme example, you would have to add a key named example to the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler. Under the new key, HKEY_CLASSES_ROOT\PROTOCOLS\Handler\example, the string value, CLSID, must be assigned the CLSID of the protocol handler. Any URLs with the protocol scheme example: would be handled by the protocol handler associated with the CLSID value.

The protocol handler cannot use any Windows® messaging to switch back to the thread it was instantiated on, since the protocol handler must work on non-GUI threads.

Note All asynchronous pluggable protocols must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

About Pluggable Name Space Handlers

A pluggable name space handler is an asynchronous pluggable protocol handler that you can set up to handle various protocol schemes and patterns. If a pluggable name space handler understands a particular URL, the handler will start successfully. Otherwise, the pluggable name space handler indicates that the default protocol handler for that protocol scheme should be used. A pluggable name space handler can be installed permanently or temporarily and can include specific patterns to indicate when it should be used.

Multiple pluggable name space handlers can be registered either temporarily or permanently. Temporarily registered pluggable name space handlers are called first and in the reverse order in which they were registered. This means the temporary pluggable name space handler that was registered last will be called first. Permanent name space handlers are not called in a specific order, so there is no way to ensure which handler will be called first.

Note All asynchronous pluggable name space handlers must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

Permanent pluggable name space handlers

To set up a permanent pluggable name space handler, you must register it in the registry with the key HKEY_CLASSES_ROOT\PROTOCOLS\Name-Space Handler\protocol_scheme\handler_name. Under this key, you must set the values for a CLSID and any pattern string that you include. If no pattern strings are set, the handler is called for all requests for the specified protocol scheme.

If there are multiple permanent pluggable name space handlers registered, the order in which they are called is random, so handlers should specify only name spaces that they have control over to avoid handling name spaces specified by another handler.

In the following example, the pluggable name space handler Ohserv-Handler is to be called for all HTTP requests with the URL http://ohserv/.

HKEY_CLASSES_ROOT\PROTOCOLS\Name-Space Handler\http\Ohserv-Handler
    CLSID = {..}
    Pattern1 = "ohserv"

Pattern1 is a pattern string that is used to determine if this handler should be used on a particular URL. If a handler has multiple pattern strings (Pattern1, Pattern2, Pattern3, and so on), the browser checks the pattern strings listed to see if any of them match the URL the browser is trying to access. If there is a match, the handler is used; if there isn't, the handler is not used.

Note Valid pattern strings cannot have a leading wildcard character, such as *.com, and should handle only a specific group of known name spaces (for example, URLs for your company's Web sites). Pattern strings that could include numerous Web sites might conflict with other name space handlers that are provided for that specific site.

Temporary pluggable name space handlers

You can register and unregister a temporary pluggable name space handler by using the IInternetSession interface.

About Pluggable MIME Filters

A pluggable MIME filter is an asynchronous pluggable protocol that receives data through a stream, does some operation on the data, and returns a data stream. The output data might be in a different format from the original stream.

Multiple pluggable MIME filters can be registered either temporarily or permanently. Temporarily registered pluggable MIME filters are called first and in the reverse order in which they were registered. That means the pluggable MIME filters registered last will be called first.

For information on how Internet Explorer 4.0 determines MIME types, see Appendix A: MIME Type Detection in Internet Explorer 4.0.

Note All asynchronous pluggable MIME filters must support the BINDF_NO_UI and BINDF_SILENTOPERATION flags.

Permanent pluggable MIME filters

You must register a permanent pluggable MIME filter in the registry with the key HKEY_CLASSES_ROOT\PROTOCOLS\Filter\\<mime_filter> and with a value for a MIME filter. This value must be a CLSID.

Temporary pluggable MIME filters

You can register and unregister a temporary pluggable MIME filter by using the IInternetSession interface.

Creating an Asynchronous Pluggable Protocol Handler

Use the following steps to create an asynchronous pluggable protocol handler:

1. Implement the IInternetProtocol interface.
2. Implement the IInternetProtocolRoot interface.
3. Implement the IClassFactory interface.
4. Optional. Implement IInternetProtocolInfo. Support for the HTTP protocol is provided by the transaction handler.
5. If IInternetProtocolInfo is implemented, provide support for PARSE_SECURITY_URL and PARSE_SECURITY_DOMAIN, so the URL security zone manager can handle the security properly.
6. Write the code for your protocol handler.
7. Provide support for BINDF_NO_UI and BINDF_SILENTOPERATION.
8. Add a subkey for your protocol handler in the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler.
9. Create a string value, CLSID, under the subkey and set the string to the CLSID of your protocol handler.

After the protocol handler is created and added to the registry, it can be used by any application using the functionality provided by Urlmon.dll. The following list contains the general order of the calls made between Urlmon.dll and your protocol handler when a URL with the protocol scheme you registered your handler for is called:

1. Urlmon.dll calls IUnknown::QueryInterface on your protocol handler for the IInternetProtocolInfo interface.

   

2. If IInternetProtocolInfo is implemented, Urlmon.dll calls your pluggable protocol handler's IInternetProtocolInfo::ParseUrl interface.

   

   If the protocol handler is being called for an update of a subscription by Microsoft Internet Explorer 4.0, the pluggable protocol handler's IInternetProtocolInfo::QueryInfo method will also be called with the QUERYOPTION value set to QUERY_USES_CACHE. Only pluggable protocol handlers that use the Internet cache and return TRUE for the QUERY_USES_CACHE flag will be supported by the Internet Explorer subscription mechanism.

3. Urlmon.dll calls IUnknown::QueryInterface on your pluggable protocol handler for its IInternetProtocol interface.

   

4. Urlmon.dll calls your pluggable protocol handler's IInternetProtocolRoot::Start method with the URL and passes the address of the Urlmon.dll's IInternetProtocolSink and IInternetBindInfo interfaces.

   

5. Your pluggable protocol handler should access the requested data. First it will request the data from the Internet.

   

6. After your pluggable protocol handler begins downloading data, your pluggable protocol handler should call the Urlmon.dll's IInternetProtocolSink::ReportData method.

   

7. Urlmon.dll calls your protocol handler's IInternetProtocol::Read method.

   

8. Your pluggable protocol handler might call Urlmon.dll's IInternetProtocolSink::ReportProgress method. The pluggable protocol handler must report the MIME type, using the BINDSTATUS_MIMETYPEAVAILABLE status code, to allow a pluggable MIME filter to be called (if there is a MIME filter registered for the MIME type reported).

   

9. Steps 6 through 8 are repeated until your protocol handler is finished downloading the requested data.
10. Your pluggable protocol handler must call the Urlmon.dll's IInternetProtocolSink::ReportResult method.

    

11. Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::LockRequest method.

    

12. Urlmon.dll calls your pluggable protocol handler's IInternetProtocolRoot::Terminate method.

    

13. Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::Read method until all the data is retrieved.

    

14. Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::UnlockRequest method.

    

Note Your pluggable protocol handler's IInternetProtocol::Read method might continue to get called even after your IInternetProtocol::Read method has indicated that all the data has been read. All asynchronous pluggable protocol handlers must be prepared for this possibility.

Creating a Pluggable MIME Filter

A pluggable MIME filter is essentially an asynchronous pluggable protocol handler that implements an IInternetProtocolSink interface. Urlmon.dll will use the MIME filter's implementation of IInternetProtocolSink to notify the pluggable MIME filter that it has data ready to be filtered.

Also, filters that handle multiple MIME types must register a separate CLSID for each MIME type they handle:

1. The transaction handler calls the pluggable MIME filter's IInternetProtocolRoot::Start method.

   

2. The transaction handler calls the pluggable MIME filter's IInternetProtocolSink::ReportProgress and IInternetProtocolSink::ReportData methods.

   

3. The pluggable MIME filter calls the transaction handler's IInternetProtocol::Read method.

   

4. The pluggable MIME filter calls the transaction handler's IInternetProtocolSink::ReportData method.

   

5. The transaction handler calls the pluggable MIME filter's IInternetProtocol::Read method.

   

More details will be provided in future versions of this documentation.

---

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