Asynchronous Pluggable Protocols Overview

---

Asynchronous pluggable protocols enable developers to create pluggable protocol handlers, MIME filters, and namespace handlers that work with Microsoft® Internet Explorer version 4.0 and later and a URL moniker. This section covers the pluggable protocol functionality exported by the Urlmon.dll dynamic-link library (DLL). For information about the other APIs exported by the Urlmon.dll, see the Asynchronous and URL Monikers and URL Security Zones articles.

• Benefits
• Scenarios
• Prerequisites and Dependencies
• About URLs and Namespaces
• About Pluggable Protocols
• Creating an Asynchronous Pluggable Protocol Handler
• Appendix A: Registering an Application to a URL Protocol
• Appendix B: Debugging Tips

Benefits

Applications can use pluggable protocol handlers to handle a custom Uniform Resource Locator (URL) protocol scheme or filter data for a designated MIME type.

The ability to handle a custom URL protocol scheme using a pluggable protocol handler allows developers to implement new or custom protocol schemes for Internet Explorer 4.0 (and later) and for applications that use URL monikers. The default pluggable protocol handler included with Internet Explorer handles existing protocol schemes, such as HTTP and FTP.

Pluggable MIME filters can be used to filter data for a particular MIME type. Unlike standard pluggable protocol handlers and pluggable namespace handlers, which only provide data, pluggable MIME filters both read and provide data. The pluggable MIME filter's implementation of the IInternetProtocolSink interface reads the data downloaded by the pluggable protocol handler. After the data has been processed, the pluggable MIME filter's implementation of IInternetProtocol allows the system to retrieve the processed data.

Scenarios

Let's say that a new protocol scheme has been introduced and your company wants to provide support for users of Internet Explorer 4.0 and later. Pluggable protocols allow you to provide a new protocol handler that will be called for any requests that use the new protocol scheme.

Or, say your company wants to design products that will help parents keep their children from reading profanity on the Internet. You could design a pluggable MIME filter, register it to handle the text/* MIME types, and have it replace all profanity with <BEEP> or something similar. Any content that has a matching MIME type, such as a Web page (whose MIME type is usually text/html), will call the pluggable MIME filter and pass the filtered data to the user.

Prerequisites and Dependencies

This documentation assumes that you have an understanding of Microsoft® Win32® programming. Also, you should have an understanding of OLE and COM programming and of the format and syntax of a URL. 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 functionality provided in Urlmon.dll, 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 Namespaces

A 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 section of the scheme-specific portion of the URL contains the server name. This portion of the URL is often referred to as the URL namespace.

About Pluggable Protocols

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 about how to register an application for a particular URL protocol, see Appendix A: 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).
• Temporarily registering a pluggable namespace handler. The handler is used for any URLs with 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

• IInternet
• IInternetBindInfo
• IInternetPriority
• 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 for which it is registered. 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 Microsoft® 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 Namespace Handlers

Temporary pluggable namespace handlers are used for all URLs that use the protocol scheme the temporary pluggable namespace handler was registered for on a particular process. You can register and unregister a temporary pluggable namespace 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, performs 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, in the reverse order in which they were registered. So pluggable MIME filters registered last will be called first.

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

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

Also, pluggable MIME filters are only invoked by Internet Explorer for the resource specified by the URL. The MIME filter will not be invoked for other resources (such as images on an HTML page) that are associated with the resource specified by the URL.

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 set to the CLSID of the pluggable MIME filter.

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

Follow these 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 the IInternetProtocolInfo interface. 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, the handler can be used by any application that uses the functionality provided by Urlmon.dll. The following steps provide 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.

   

   When updating a subscription, Internet Explorer calls the pluggable protocol handler's IInternetProtocolInfo::QueryInfo method with the QUERYOPTION value set to QUERY_USES_CACHE. The Internet Explorer subscription mechanism will support only pluggable pluggable protocol handlers that use the Internet cache and return TRUE for the QUERY_USES_CACHE flag.

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 will need to access the requested data. First it will request the data from the Internet.

   

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

   

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

   

8. Your pluggable protocol handler can 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 be called by the Urlmon.dll even after the method has indicated that all the data has been read. All asynchronous pluggable protocol handlers must be prepared to handle 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 uses the pluggable MIME filter's implementation of IInternetProtocolSink to notify the filter that Urlmon.dll 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 information will be provided in future versions of this documentation.