FILE: HLINKAXD Demonstrates a Hyperlinking Active Document

• Microsoft ActiveX SDK, version 1.0
• Internet Client SDK, versions 4.0, 4.01

SUMMARY

HlinkAxDoc (HLINKAXD) is a sample demonstration of the hyperlinking interfaces. HlinkAxDoc is an MFC Active Document server that contains hyperlinks. In addition to being a container, it is also a hyperlinking target and can be the recipient of hyperlinks from other hyperlinking containers.

HlinkAxDoc implements IHlinkTarget and IHlinkSite. It uses the IHlink, IHlinkBrowseContext, and IHlinkFrame interfaces when jumping to hyperlinks as well as being activated as the target of a hyperlink. Last, HlinkAxDoc also supports the IPersistMoniker interface and demonstrates a basic implementation of the Load method.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

 ~ Hlinkaxd.exe (size: 81412 bytes) 

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services

What Is It?

HlinkAxDoc is a basic hyperlinking Active Document server. All it does is store a list of hyperlink objects that can be used to jump to other hyperlink targets such as Web pages via URLs or Office documents. HlinkAxDoc can persist this list of hyperlinks, meaning it can save its own file format and load it back again, re-creating hyperlinks from the original data. Also, HlinkAxDoc can read Internet Shortcuts as well as Hyperlink objects from the Clipboard and from drag&drop operation. This allows you to drag a hyperlink from an HTML page in Internet Explorer into HlinkAxDoc and store the hyperlink for later use. A whole collection of hyperlinks, with their URLs visible, could be stored and saved in this manner.

To build this sample, you will need Visual C++ 5.0 with the Internet Client SDK (InetSDK) installed. The sample will probably need to use the Hlink.lib and Uuid.lib from the InetSDK, so you should set your Inernet SDK include and lib directories to the top of the VC search path using Tools->Options ->Directories.

Major Players - Objects and Interfaces

There are basically six major characters in the drama of the hyperlinking architecture. First and foremost is the hyperlink object itself. A hyperlink is a COM object implemented by "the system" (Hlink.dll, technically) that encapsulates all the data necessary to locate an acceptable hyperlink target application and point it to a specific document or file. Hyperlinks are usually stored in a hyperlink container, which can optionally implement one or more hyperlink site objects to manage a set of contained hyperlinks. Hyperlink containers typically display hyperlinks in the UI in some visible way and provide a method for creating new hyperlinks. Fourth, applications that can be the recipient of hyperlink navigation are known as hyperlink targets.

Confusingly, most hyperlink targets can also be hyperlink containers. Take Word for example. If you create a hyperlink inside one word document that links to another word document and then activate it, the second word document is the target of the hyperlink stored in the first document, the container. Upon reaching the second word document, this hyperlink target could easily have yet another hyperlink inside it which would go to another word document, a URL, or whatever. That is, a Word document can be both a hyperlink container and target.

Hyperlink targets are typically Active Document servers as well as standalone applications. That is, these servers can open documents inside another application that supports the necessary architecture to be an Active Document container. (Do not confuse an Active Document container with a Hyperlink container.) Of course, the ultimate Active Document container of all Active Document containers, the uber-container, is Internet Explorer (IE). Internet Explorer also serves as the fifth object in our discussion, the hyperlink frame. As a hyperlink frame, Internet Explorer has the capability of hosting one or more hyperlink targets that work as Active Document containers. Internet Explorer owns the frame and Internet toolbar and provides for the most Web-like hyperlinking atmosphere. When hyperlinks are made between standalone applications, some trickery occurs to make the navigation appear smoother. However, the navigation still happens between two separate frame windows. When hyperlinks are made inside a hyperlink frame, there is one frame window through the entire hyperlinking experience, provided all hyperlink targets are active documents.

Note that very rarely will an application other than Internet Explorer act as a hyperlink frame. So in a sense, this can also be thought of as a "system" implemented object.

The sixth and last major character is the hyperlink browse context. The hyperlink browse context is another object implemented for you by "the system" that encapsulates the functionality of a navigation stack. The browse context stores references to all the hyperlinks that have been made in a particular hyperlinking session. It also stores information about registered hyperlink targets and holds references to targets during a particular session to keep them open and speed back/forward navigation. Using the hyperlink browse context that gets passed from hyperlink target to hyperlink target, targets and hyperlink frames can make intelligent decisions about whether to activate forward or back buttons.

Given that browse context, frame, and hyperlink itself are implemented by the system, that means developers interested in hyperlinking will typically have to implement only the target and container functionality for their applications. This corresponds to supporting the IHlinkTarget interface for hyperlink targets. Containers do not have a specific requirement, all they have to do is work with the system-provided IHlink, IHlinkBrowseContext, and IHlinkFrame interfaces. However, they can optionally support IHlinkSite to help with hyperlink management.

HlinkAxDoc implements IHlinkSite and IHlinkTarget and works with all the other interfaces. It is both a hyperlinking container as well as a hyperlinking target. HlinkAxDoc also works as an Active Document and can be hosted in hyperlink frames.

The Internet Client SDK and Platform SDKs have good documentation on the various objects and interfaces used in typical hyperlinking scenarios. Please refer to these for more information.

Keywords          : AXSDKHyperlink
Technology        : kbInetDev internet kbole
Version           : WINDOWS:1.0,4.0,4.01
Platform          : WINDOWS
Issue type        : kbhowto