About Asynchronous Pluggable Protocols

Artykuł
07/13/2016

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

Benefits
Scenarios
Prerequisites and Dependencies
About URIs and Namespaces
About Pluggable Protocols
- About Asynchronous Pluggable Protocols
- About Pluggable Namespace Handlers
- About Pluggable MIME Filters
Creating an Asynchronous Pluggable Protocol Handler
- Creating a Pluggable MIME Filter
Related topics

Benefits

Note Third-party protocol implementations won't load in Windows apps using JavaScript, or in the Internet Explorer in the new Windows UI.

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

The ability to handle a custom URI 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 URI monikers. The default pluggable protocol handler included with Windows Internet Explorer handles existing URI 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 URI 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 pluggable protocol handler that will be called for any requests that use the new URI 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 Component Object Model (COM) programming and of the format and syntax of a URI. For more information, see RFC3986: Uniform Resource Identifier (URI): Generic Syntax.

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 URIs and Namespaces

A URI follows the syntax described in RFC 3986, which specifies a URI scheme name followed by a scheme-specific portion (<scheme>:<scheme-specific portion>). For example, in the URI https://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 http URI contains the server name.

About Pluggable Protocols

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

For information about how to register an application for a particular URL scheme, see Registering an Application to a URI Scheme.

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

Permanently registering an asynchronous pluggable protocol handler in the registry. The handler is used for any URIs 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

Functions related to asynchronous pluggable protocols

CoInternetGetSession

About Asynchronous Pluggable Protocols

An asynchronous pluggable protocol handler is an apartment-threaded 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 IClassFactory3 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 Namespace Handlers

Temporary pluggable namespace handlers are used for all URLs that use the protocol scheme for which the temporary pluggable namespace handler was registered 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.

For information about how Internet Explorer 4.0 determines MIME types, see 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 URI. 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 URI.

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:

Implement the IInternetProtocol interface.
Implement the IInternetProtocolRoot interface.
Implement the IClassFactory3 interface.
Optional. Implement the IInternetProtocolInfo interface. Support for the HTTP protocol is provided by the transaction handler.
If IInternetProtocolInfo is implemented, provide support for PARSE_SECURITY_URL and PARSE_SECURITY_DOMAIN so the URI security zone manager can handle the security properly.
Write the code for your pluggable protocol handler.
Provide support for BINDF_NO_UI and BINDF_SILENTOPERATION.
Add a subkey for your pluggable protocol handler in the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler.
Create a string value, CLSID, under the subkey and set the string to the CLSID of your pluggable protocol handler.

After the pluggable 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 pluggable protocol handler when a URI with the scheme for which you registered your handler is called:

Urlmon.dll calls QueryInterface on your pluggable protocol handler for the IInternetProtocolInfo interface.
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 protocol handlers that use the Internet cache and return TRUE for the QUERY_USES_CACHE flag.
Urlmon.dll calls QueryInterface on your pluggable protocol handler for its IInternetProtocol interface.
Urlmon.dll calls your pluggable protocol handler's IInternetProtocolRoot::Start method with the URI and passes the address of the Urlmon.dll's IInternetProtocolSink and IInternetBindInfo interfaces.
Your pluggable protocol handler will need to access the requested data. First it will request the data from the local machine, intranet, or Internet.
After your pluggable protocol handler begins downloading data, it is recommended that the handler call the Urlmon.dll's IInternetProtocolSink::ReportData method.
Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::Read method.
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).
Steps 6 through 8 are repeated until your pluggable protocol handler is finished downloading the requested data.
Your pluggable protocol handler must call the Urlmon.dll's IInternetProtocolSink::ReportResult method.
Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::LockRequest method.
Urlmon.dll calls your pluggable protocol handler's IInternetProtocolRoot::Terminate method.
Urlmon.dll calls your pluggable protocol handler's IInternetProtocol::Read method until all the data is retrieved.
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:

The transaction handler calls the pluggable MIME filter's IInternetProtocolRoot::Start method.
The transaction handler calls the pluggable MIME filter's IInternetProtocolSink::ReportProgress and IInternetProtocolSink::ReportData methods.
The pluggable MIME filter calls the transaction handler's IInternetProtocol::Read method.
The pluggable MIME filter calls the transaction handler's IInternetProtocolSink::ReportData method.
The transaction handler calls the pluggable MIME filter's IInternetProtocol::Read method.