Creating an Asynchronous Pluggable Protocol Handler

Creating an Asynchronous Pluggable Protocol Handler


The following steps are needed 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.

    Calling the asynchronous pluggable protocol

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

    Calling the asynchronous pluggable protocol

    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 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 Microsoft Internet Explorer's subscription mechanism.

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

    Calling the asynchronous pluggable protocol

  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.

    Calling the asynchronous pluggable protocol

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

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

    Notifying the transaction handler that data is available

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

    Reading the data

  8. Your pluggable protocol handler may 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 filters to be called (if there is a MIME filter registered for the MIME type reported).

    Reporting progress

  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.

    Reporting results

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

    Locking request

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

    Terminate the pluggable protocol

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

    Reading the remaining data

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

    Unlocking the request

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. The Urlmon.dll will use the MIME filter's implementation of IInternetProtocolSink to notifiy 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 it handles.

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

    Reading the Data

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

    Reading the Data

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

    Reading the Data

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

    Reading the Data

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

    Reading the Data

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

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