About Pluggable Protocols

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:

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

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 insure 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 that they are called in is random, so handlers should only specify 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 only handle 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.

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