IHlink

IHlink

The IHlink interface enables a COM object known as a hyperlink to completely encapsulate the behavior of navigating to its target location.

Hyperlinks are managed by COM hyperlink container objects, which support the IHlinkSite interface for hyperlinks within the container and the IHlinkTarget interface for hyperlinks referring to documents or document objects within it.

IHlink provides methods for a hyperlink object to navigate to its target, access a friendly name for display purposes, and identify itself to its container and frame.

When to Implement

Typically, you do not need to implement this interface. A standard implementation of a hyperlink component is provided as part of the system, and it is not advisable to implement another version. A document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the capability of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks. The standard hyperlink object implements IHlink, IPersistStream, and IDataObject interfaces.

When to Use

IHlink interfaces are typically called by an applicationÆs hyperlink container as part of a user interface for creating new hyperlinks. Standard hyperlink objects are created via the HlinkCreateFromData, HlinkCreateFromMoniker, HlinkCreateFromString, and OleLoadFromStream APIs.

While the hyperlink object provides many useful functions that are needed for general purpose uses, often applications are only interested in navigating to a hyperlink target. For simple navigation needs, there are a number of "helper" APIs such as HlinkSimpleNavigateToString, HlinkSimpleNavigateToMoniker, and HlinkNavigateToStringReference that allow simple hyperlink navigation without any knowledge of other hyperlink interfaces or objects.

Hyperlink navigation involves transitioning from one document/object/application, known as the hyperlink container, to another document/object/application, known as the hyperlink target. Usually, both remain running, but the hyperlink target visually replaces the hyperlink container (from which the navigation originated). There are three ôflavorsö of hyperlink containers and targets.

1. Top-level documents.

2. OLE Document objects in a browser.

3. OLE Document objects in an Office Binder-like application that does not support OLE in-place/DocObj server functionality, and hence cannot be shown in-place in a browser.

The following are possible forms of navigation:

1. From one top-level document to another top-level document (for example, between Office documents in the absence of a browser).

2. From a top-level document to an OLE Document in a browser (for example, from a stand-alone application to an HTML document).

3. From one OLE document object in a browser to another OLE document object in the same browser (for example, one HTML document to another).

4. From one OLE document object in a browser to an OLE document object in a Binder-type application (for example, if the hyperlink target is embedded as an OLE Document Object in an Office Binder document; in this scenario, the end user model gets complicated and confusing if the embedded OLE Document Object is shown in the browserÆs window, instead of letting it appear in its own containerÆs window).

5. From one location in an object/document to another location in the same object/document (applicable to all three flavors of hyperlink containers/hyperlink targets).

Methods in Vtable Order

IUnknown Methods            Description

QueryInterface

Returns pointers to supported interfaces.

AddRef                      Increments reference count.

Release                     Decrements reference count.

IHlink Methods              Description

SetHlinkSite

Saves the interface pointer on the site object.

GetHlinkSite                Retrieves the interface pointer on the site object.

GetMonikerReference         Retrieves the moniker and location portions of the   
                            target.

GetStringReference          Retrieves the name and location portions of the      
                            target.

GetFriendlyName             Retrieves the friendly name of the target.

SetFriendlyName             Sets the friendly name of the target.

GetTargetFrameName          Retrieves the name of the target frame.

SetTargetFrameName          Sets the name of the target frame.

GetAdditionalParams         Retrieves additional hyperlink parameters.

SetAdditionalParams         Sets additional hyperlink parameters.

Navigate                    Navigates to the given target.

GetMiscStatus               Queries if hyperlink is absolute or relative.