Asynchronous pluggable protocols:

  Asynchronous Pluggable Protocols

Asynchronous pluggable protocols enable developers to create pluggable protocol handlers, MIME filters, and namespace handlers that work with Internet Explorer version 4.0 and later and URL monikers.

The samples on these pages demonstrates how to use these powerful tools in Delphi. 

There is not much documentation available on the MS-site and only a stupid sample called etcprot. "More information will be provided in future versions of this documentation", MS promise.

These samples are very much inspired by the work done by Christopher Coppola, who initiated the APP project under the delphi-webbrowser newsgroup. His code also demonstrates how to implement IInternetProtocolInfo and IInternetSecurityManager.

The samples on this page are also uploaded to the APP-project. Please contribute, so we can keep this project alive:

http://www.egroups.com/docvault/delphi-webbrowser/

Use the delphi-webbrowser newsgroups for discussion about APP and other delphi-webbrowser topics:

http://www.egroups.com/group/delphi-webbrowser/info.html

You can find the MS-documentation about pluggable protocols on the following URLs:

http://msdn.microsoft.com/workshop/networking/pluggable/overview/overview.asp

ftp://ftp.microsoft.com/Softlib/MSLFILES/ETCPROT.EXE


Here is a nice article by by Vino Rodrigues borland:
Pluggable Protocols

Browsers and Protocols

Although HTTP is the most well-known and widely used protocol on the Internet, browsers generally support a variety of different protocols. This list just scratches the surface:

Protocol	Description
Http:	HTTP is a stateless and transaction-oriented client/server protocol used to access data on the Web. It relies on TCP/IP for low-level connections.
ftp:	The protocol used for copying files to and from remote computer systems on a network using TCP/IP. This protocol also allows users to use FTP commands to work with files, such as listing files and directories on the remote system.
Mailto:	Used to write and drop an email message through a related program.
Gopher:	A client/server application that allows the user to browse large amounts of information. It presents the information to the user in a menu format.
File:	Allows you to access and browse the local file system as if it were a network resource.
Nntp:	The name stands for Network News Transfer Protocol and is an application protocol used in TCP/IP networks. Enables clients to read and post information to USENET newsgroups.
About:	Intended to let you output text directly on the page with the aim of providing information about what happened.

HTTP, FTP, and Gopher are probably the three most common protocols implemented by Web servers. In addition to Internet Explorer, all the protocols listed in Figure 9-1 are also supported by Netscape Communicator and most other vendors' browsers.

It's important to always remember that a browser is in no way tied only to HTTP. A browser is simply a piece of software that performs some actions by following a given protocol. Ultimately, a protocol is implemented by a piece of software, resident on the client machine, that is invoked when a browser encounters the prefix used as the protocol identifier. In this way, when the browser finds an address that begins with 'http:', it relies on the functions exposed by the module that handles HTTP. When the browser encounters an 'ftp:' link, it calls the module that handles FTP protocol conversations.

Once the interface of such a module is formalized, you have a generic layer of code that acts as a conduit to transfer data between the browser and the server. In this case, the server can be anything that can provide the requested information. It could be a Web server for 'http:', an email program for 'mailto:', or the local file system if the protocol is 'file:'. Interestingly, the server will be a file if the protocol is 'res:', as I hinted above.

By generalizing the structure of this protocol-handling layer and implementing it via a component object model like COM, the browser now has a far more modular architecture. At the same time, it is more extensible, since it's not dependent upon a fixed number of protocols.

The 'about:' Protocol

Have you ever wondered about the about:NavigationCanceled URL that appears when you try to access unavailable resources with Internet Explorer? Well, 'about:' is an IE pluggable protocol. Its role is to display either raw text or predefined pages using a short moniker. In one sense, 'about:' is the Web equivalent of MessageBox. It is meant to help you display messages in an HTML page.

The syntax for this protocol is:

about:{some text}

The text portion can be raw HTML text or a kind of pointer to an HTML page. The browser first tries to find a matching page for the specified text. If it fails, it next considers the text portion to be plain text to display. The 'about:' protocol is implemented in shdocvw.dll. Under the hood, the protocol's implementation ends up writing text in the document body. If you type the following in the Internet Explorer 4.0 (or above) address bar:

about:Hello, MIND

the string "Hello, MIND" will appear on a blank page as if you'd loaded a page with this source code:

<HTML>Hello, MIND</HTML>

You can also enter more complex text such as:

about:Hello, <a href="c:">MY DRIVE</a>

The result is shown here:

The 'about:' protocol is also supported by Netscape Communicator 4.05, but it doesn't support any conversion tables in its implementation, and it's limited to outputting text in the document's body.

Monikers

What's cool with 'about:' is that you can define monikers to address specific HTML pages instead of plain text. For example, the content displayed by about:NavigationCanceled actually comes from an HTML resource, res://shdocvw.dll/navcancl.htm, that's stored in shdocvw.dll, as shown in Figure 9-4.

But how does the browser know how to associate the NavigationCanceled moniker with the resource navcancl.htm? It's all stored in a table within the system registry, under this easy-to-remember key:

HKEY_LOCAL_MACHINE
  Software
    Microsoft 
      Internet Explorer
        AboutURLs
                            

Adding a new moniker is as easy as writing a new entry in the registry. If you have resprot.dll installed in your system directory and add this association to the table, then about:mind will be a command that'll be recognized by Internet Explorer 4.0 or above.

Complex Text

You can also use the 'about:' protocol for complex strings - like the entire Content of a TPageProducer. Try it...

The 'res:' Protocol

The 'res:' protocol lets you extract a resource from a compiled module like an EXE or DLL. While this protocol has been introduced to work with HTML pages, you can use it to work with other type of resources as well, including custom resources. A URL based on this protocol looks like this:

res://resource_file.ext[/resource_type]/{res_id}

where resource_file.ext is the name of the executable module. If the file is in the search path (for instance, in the Windows directory), it may be specified by file name alone.

The second chunk of information, resource_type, is optional. The 'res:' protocol supports numbers for each of its predefined resource types, and allows you to use literal strings to identify custom resources. The complete list of the resource types is declared in windows.pas.

Here is a list of the entries most commonly used via the 'res:' protocol.

Resource	windows.pas const	ID
Cursor	RT_CURSOR	1
Bitmap	RT_BITMAP	2
Icon	RT_ICON	3
String	RT_STRING	6
Animated Cursor	RT_ANICURSOR	21
Animated Icon	RT_ANIICON	22
HTML	{not defined!}	23

Those are the same IDs required by some API functions like FindResource. If you don't provide a resource type, it defaults to HTML (type 23). This means that:

res://ie4tour.dll/23/welcome.htm

and

res://ie4tour.dll/welcome.htm

are equivalent and will access the same page in the specified executable. If you want to refer a custom resource, namely one whose type is not defined in windows.pas, then you have to use the name of the type. For example, if you have a file called resProt.dll with this line in its .rc file:

MindLogo  GIF  "mind.gif"

then

res://resProt.dll/gif/MindLogo

is the correct way to reference the image.

The final piece of information in the URL is the resource id (res_id) or name. A resource name can be a number or a string. You can use any string to identify a resource, but if it evaluates to an external file name that's been embedded in the executable file, using the file name as an identifier makes sense. For example, if you have the following line in your .rc file:

mind.gif  GIF  "mind.gif"

you can invoke it within an HTML page like this:

<img src="res://resProt.dll/gif/mind.gif">

Note: Neither BRCC32.EXE (Borland Resource Compiler Command Line) nor the Delphi IDE resource compiler support a '.' (dot) in the resource identifier. If you wish to bind a resource with filename-like resource identifiers you will need to use Microsoft's RC.EXE - which ships with most Microsoft development tools, like Microsoft Visual C++, or Visual Studio.

The 'res:' protocol allows you to compile HTML pages within your application so that there's just one file to distribute: the EXE. Notice that all the internal references are based on the 'res:' protocol. This lets you embed an entire HTML-based application within a compiled module.

The 'res:' protocol isn't the only possible solution for embedding HTML resources into an application. A lower-level approach might be to embed your resources as shown above, then extract and recreate them as separate files at startup using FindResource and other related APIs. This solution might be worth consideration if your target browser isn't Internet Explorer. The 'res:' protocol is the most elegant solution, but browsers other than Internet Explorer 4.0 and above don't support it.

Creating a HTML resource

To add the HTML as a resource, you include a file that contains nothing but the actual HTML in your application's resource script. This file is included as an HTML type resource.

Microsoft's RC.EXE compiler

The following example shows how to include a file called mind.htm and a image, themind.gif, as an HTML resource into a .rc file called mymind.rc:

mind.htm  HTML  "mind.htm"

themind.gif  HTML  "themind.gif"

In this example, mind.htm is the identifier of the resource, and it can be either a string or a numerical identifier. HTML is the resource type. Microsoft's RC.EXE will interpret this as the numeric value 23 and will substitute 23 for HTML when the resource file is opened for editing.

mind.htm is the file that contains the HTML source that will be added. The resource compiler adds this file as is and will not attempt to interpret the contents of the file.

Run the resource compiler with the following command line:

RC MYMIND.RC

A compiled resource file, mymind.res, will be generated and this file can be included into your program or library:

{$R 'MYMIND.RES'}

You would then call this page up within you application using the TWebBrower's 'Navigate' procedure:

WebBrowser1.Navigate('res://' + Application.ExeName + '/mind.htm');

Delphi's IDE resource compiler

The following example shows how to include the same files, this time in a file called mymind2.rc:

mind  23  "mind2.htm"

themind  23  "themind.gif"

Note: Borland's RC compilers do not understand the '.' (dot) in the resoure identifiers, so we need to strip that. Also remember that the <IMG> tags in the HTML must also strip the '.gif' from their SRC's.

Note: Also, Borland's RC compilers do not understand the 'HTML' type, so we need to use that type's numerical value.

You don't need to compile the .rc file just add it to your project with the "Add file to project" short-cut. This will place the following line to your project source:

{$R 'mymind2.res' 'mymind2.rc'}

Note: This is some Borland magic - the file will be listed as a project file and the IDE will auto-magically compile it when you change it!

You would then call this page up within you application using the TWebBrower's 'Navigate' procedure:

WebBrowser1.Navigate('res://' + Application.ExeName + '/mind');

*