Hyperlinks Reference

This section describes Microsoft ActiveX Hyperlinking and the interfaces involved in adding hyperlink navigation to your document or application.

Objects

Hyperlink

Hyperlink Browse Context

Hyperlink Target

Interfaces

IEnumHLItem (not supported)

IExtensionServices (not supported)

IHLink

IHLinkBrowseContext

IHLinkFrame

IHLinkSite

IHLinkTarget

Functions

HlinkClone

HlinkCreateBrowseContext

HlinkCreateExtensionServices

HlinkCreateFromData

HlinkCreateFromMoniker

HlinkCreateFromString

HlinkCreateShortcut

HlinkCreateShortcutFromMoniker

HlinkCreateShortcutFromString

HlinkGetSpecialReference

HlinkGetValueFromParams

HlinkGoBack

HlinkGoForward

HlinkIsShortcut

HlinkNavigate

HlinkNavigateMoniker

HlinkNavigateString

HlinkNavigateToStringReference

HlinkOnNavigate

HlinkOnRenameDocument

HlinkParseDisplayName

HlinkPreprocessMoniker

HlinkQueryCreateFromData

HlinkResolveShortcut

HlinkResolveShortcutToMoniker

HlinkResolveShortcutToString

HlinkResolveStringForData

HlinkSetSpecialReference

HlinkSimpleNavigateToMoniker

HlinkSimpleNavigateToString

HlinkTranslateUrl

HlinkUpdateStackItem

OleSaveToStreamEx

Structures

HLBWINFO

Contains parameters that provide information about locations and sizes of frame-level and document-level windows within a browse context.

TYPE HLBWINFO
  cbSize AS DWORD
  grfHLBWIF AS DWORD
  rcFramePos AS RECT
  rcDocPos AS RECT
  hltbinfo AS HLTBINFO
END TYPE
 

Members

cbSize

Value of type ULONG that specifies the size of this structure, in bytes.

grfHLBWIF

Unsigned long integer value that specifies a value from the HLBWIF enumeration.

rcFramePos

RECT structure that contains a rectangle, in screen coordinates. If grfHLBWIF is set to HLBWIF_HASFRAMEWNDINFO, the rectangle contains the coordinates of the current frame-level windows within the browse context. When grfHLBWIF is set to HLBWIF_FRAMEWNDMAXIMIZED, frame-level windows are currently displayed maximized. In this case, rcFramePos is the "normal" size of frame-level windows—that is, the rectangle to use for any frame-level window when it is not maximized.

rcDocPos

RECT structure that contains a rectangle, in screen coordinates. If grfHLBWIF is set to HLBWIF_HASDOCWNDINFO, rcDocPos contains the rectangle of current document-level windows within the browse context. When grfHLBWIF is set to HLBWIF_DOCWNDMAXIMIZED, document-level windows are currently being displayed maximized. In this case, rcDocPos is the "normal" size of document-level windows—that is, the rectangle to use for any document-level window when it is not maximized.

hltbinfo

HLTBINFO structure that provides information about the position of the Web toolbar. This enables the target application to display its toolbar in the same location.

Remarks

The HLBWINFO structure is retrieved from the browse context using IHlinkBrowseContext::GetBrowseWindowInfo and put into the browse context using IHlinkBrowseContext::SetBrowseWindowInfo. Hyperlink targets retrieve the HLBWINFO structure during IHlinkTarget::Navigate to reposition their user interface properly and ensure as seamless a transition as possible to the new document or object.

HLITEM

Indicates the data structure used by the system browse context to track hyperlinks.

TYPE HLITEM
  uHLID AS DWORD
  pwzFriendlyName AS DWORD
END TYPE
 

Members

uHLID

Value of type ULONG that contains the hyperlink identifier. Standard enumerators always return an identifier rather than one of the logical HLID constants in this member.

pwzFriendlyName

Pointer to the hyperlink's display name.

HLTBINFO

Not currently supported.
 

TYPE HLTBINFO
  uDockType AS DWORD
  rcTbPos AS RECT
END TYPE
 

Enumerations

HLBWIF

Contains values relating to the locations and sizes of frame-level and document-level windows within a browse context.

Syntax

%HLBWIF_HASFRAMEWNDINFO = &H01
%HLBWIF_HASDOCWNDINFO = &H02
%HLBWIF_FRAMEWNDMAXIMIZED = &H04
%HLBWIF_DOCWNDMAXIMIZED = &H08
%HLBWIF_HASWEBTOOLBARINFO = &H10
%HLBWIF_WEBTOOLBARHIDDEN = &H20

Constants

HLBWIF_HASFRAMEWNDINFO

This browse context has available frame-level window positioning information.

HLBWIF_HASDOCWNDINFO

This browse context has available document-level window positioning information.

HLBWIF_FRAMEWNDMAXIMIZED

This indicates that frame-level windows of the browse context should appear maximized. It is only useful in combination with HLBWIF_HASFRAMEWNDINFO.

HLBWIF_DOCWNDMAXIMIZED

This indicates that document-level windows of the browse context should appear maximized. It is only useful in combination with HLBWIF_HASDOCWNDINFO.

HLBWIF_HASWEBTOOLBARINFO

This browse context has available Web toolbar positioning information.

HLBWIF_WEBTOOLBARHIDDEN

The browse window currently has its Web toolbar hidden.

Remarks

The HLBWINFO structure is retrieved from the browse context using IHlinkBrowseContext::GetBrowseWindowInfo and put into the browse context using IHlinkBrowseContext::SetBrowseWindowInfo.

HLFNAMEF

Specifies which friendly name a client is requesting. The flags are used by the IHlink::GetFriendlyName interface.

Syntax

%HLFNAMEF_DEFAULT = 0
%HLFNAMEF_TRYCACHE = 1
%HLFNAMEF_TRYPRETTYTARGET = 2
%HLFNAMEF_TRYFULLTARGET = 4
%HLFNAMEF_TRYWIN95SHORTCUT = 8

Constants

HLFNAMEF_DEFAULT

Cached friendly name, or else the simplified display name.

HLFNAMEF_TRYCACHE

Friendly name that is cached in the hyperlink object.

HLFNAMEF_TRYPRETTYTARGET

Cleaned up version of the display name of the hyperlink target.

HLFNAMEF_TRYFULLTARGET

Full display name of the hyperlink target.

HLFNAMEF_TRYWIN95SHORTCUT

Simplified version of the full display name of the hyperlink target.

HLID

Identifies the logical positions of a hyperlink identifier in the hyperlink navigation stack. The constants are used in the IHlinkBrowseContext interface.

Syntax

%HLID_PREVIOUS = &HFFFFFFFF
%HLID_NEXT = &HFFFFFFFE
%HLID_CURRENT = &HFFFFFFFD
%HLID_STACKBOTTOM = &HFFFFFFFC
%HLID_STACKTOP = &HFFFFFFFB

Constants

HLID_PREVIOUS

Hyperlink prior to the current one. If the current hyperlink is the first or only hyperlink in the navigation stack, or if there are no hyperlinks in the navigation stack, there is no previous hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.

HLID_NEXT

Hyperlink after the current one. If the current hyperlink is the last or only hyperlink in the navigation stack, or if there are no hyperlinks in the navigation stack, there is no next hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.

HLID_CURRENT

Current hyperlink. A browsing tool might offer a command to reload the current page, or to recenter the user interface around the beginning portion of the current hyperlink destination, or to restart animation, sound, or other activity by renavigating to the current hyperlink.

HLID_STACKBOTTOM

First hyperlink in the navigation stack. If there are no hyperlinks in the navigation stack, there is no stack-bottom hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.

HLID_STACKTOP

Last hyperlink in the navigation stack. If there are no hyperlinks in the navigation stack, there is no stack-top hyperlink, and methods such as IHlinkBrowseContext::GetHlink will return NULL and E_FAIL when passed this value.

Remarks

For convenience and performance, individual hyperlink objects are often identified in a navigation stack like a browse context or a history/favorites list using a ULONG hyperlink identifier or HLID rather than an IHlink interface pointer. This prevents unnecessary passing of interface pointers across process boundaries in common user-interface scenarios, such as building a drop-down menu or scrollable list of the history, or when testing the current location in the navigation stack to go back and forward.

HLINKGETREF

Specifies whether the client is requesting the absolute, relative, or default reference for the hyperlink target. The constants are used in the IHlink::GetMonikerReference and IHlink::GetStringReference methods.

Syntax

%HLINKGETREF_DEFAULT = 0
%HLINKGETREF_ABSOLUTE = 1
%HLINKGETREF_RELATIVE = 2

Constants

HLINKGETREF_DEFAULT

Used to specify that the client of the hyperlink wants to retrieve the default reference for the hyperlink target. This depends on whether the hyperlink was initialized as a relative or an absolute reference.

HLINKGETREF_ABSOLUTE

Used to specify that the client of the hyperlink wants to retrieve the absolute reference for the hyperlink target.

HLINKGETREF_RELATIVE

Used to specify that the client of the hyperlink wants to retrieve the relative reference for the hyperlink target.

HLINKMISC

Specifies whether the hyperlink object is a relative hyperlink to its target. The constants are used in the IHlink::GetMiscStatus method.

Syntax

%HLINKMISC_RELATIVE = 1

Constants

HLINKMISC_RELATIVE

The given hyperlink object contains a relative reference to the hyperlink target.

HLINKSETF

Specifies the operation of IHlink::SetMonikerReference. It allows a caller of this function to specify which IHlink parameter to set.

Syntax

%HLINKSETF_TARGET = 1
%HLINKSETF_LOCATION = 2

Constants

HLINKSETF_TARGET

Used to specify the setting of the pmkTarget parameter of the IHlink object.

HLINKSETF_LOCATION

Used to specify the setting of the szLocation parameter of the IHlink object.

HLINKWHICHMK

Specifies whether a moniker being requested is the moniker for the container document or a base moniker specific to a hyperlink site. The constants are used in the IHlinkSite::GetMoniker method.

Syntax

%HLINKWHICHMK_CONTAINER = 1
%HLINKWHICHMK_BASE = 2

Constants

HLINKWHICHMK_CONTAINER

Used to specify that the hyperlink wants to retrieve the moniker for the hyperlink container corresponding to a particular hyperlink site.

HLINKWHICHMK_BASE

Used to specify that the hyperlink wants to request the base moniker corresponding to the particular hyperlink site. (The monikers might be different—for example, if a base tag is used in HTML.)

HLNF

Indicates how hyperlink navigation is to proceed. The enumeration is also used by the objects participating in the navigation protocol to convey to each other contextual information about the navigation.

Syntax

%HLNF_INTERNALJUMP = &H1
%HLNF_OPENINNEWWINDOW = &H2
%HLNF_NAVIGATINGBACK = &H4
%HLNF_NAVIGATINGFORWARD = &H8
%HLNF_NAVIGATINGTOSTACKITEM = &H10
%HLNF_CREATENOHISTORY = &H20

Constants

HLNF_INTERNALJUMP

The navigation is an internal jump within the current hyperlink target.

HLNF_OPENINNEWWINDOW

This option is a combination of two commonly coincident options: HLNF_USEBROWSECONTEXTCLONE and HLNF_OFFSETWINDOWORG.

HLNF_NAVIGATINGBACK

The navigation is to the previous destination in the browse context.

HLNF_NAVIGATINGFORWARD

The navigation is to the next destination in the browse context.

HLNF_NAVIGATINGTOSTACKITEM

The navigation is to a destination that is already in the browse context.

HLNF_CREATENOHISTORY

The destination of the current navigation should not be placed into the browse context.

HLQF

Specifies query flags used by IHlinkBrowseContext::QueryHlink to determine the state of a particular hyperlink.

Syntax

%HLQF_ISVALID = 1
%HLQF_ISCURRENT = 2

Constants

HLQF_ISVALID

Used to test the validity of a particular hyperlink. The uHLID parameter can specify either a specific hyperlink within the navigation stack or a relative hyperlink, such as HLID_NEXT or HLID_PREVIOUS.

HLQF_ISCURRENT

Used to test if the specific hyperlink (identified by the uHLID parameter) is the user's current position within the navigation stack.

HLSHORTCUTF

Not currently supported.
 

%HLSHORTCUTF_DEFAULT = 0
%HLSHORTCUTF_DONTACTUALLYCREATE = &H1
%HLSHORTCUTF_USEFILENAMEFROMFRIENDLYNAME = &H2
%HLSHORTCUTF_USEUNIQUEFILENAME = &H4
%HLSHORTCUTF_MAYUSEEXISTINGSHORTCUT = &H8
 

HLSR

Specifies which of the special hyperlink references to choose. The constants are used by the HlinkGetSpecialReference and HlinkSetSpecialReference functions.

Syntax

%HLSR_HOME = 0
%HLSR_SEARCHPAGE = 1
%HLSR_HISTORYFOLDER = 2

Constants

HLSR_HOME

Used to specify the hyperlink reference to the global user home page.

HLSR_SEARCHPAGE

Used to specify the hyperlink reference to the global user search page.

HLSR_HISTORYFOLDER

Used to specify the hyperlink reference to the global user history folder page.

HLTB

Not currently supported.
 

HLTRANSLATE

Not currently supported.