HlinkNavigateString
Reference

HlinkNavigateString


HRESULT HlinkNavigateString(
    IUnknown * pUnk,    //IUnknown pointer to the initiating document or object
    LPCWSTR szTarget    //Moniker of the hyperlink target
   );

Executes a hyperlink jump to a new document or object (specified in szTarget).

pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application.
szTarget
[in] String that helps identify the hyperlink target. This string is resolved into a moniker for underlying binding operations through MkParseDisplayNameEx. If NULL, the navigation is within a document.

HlinkNavigateString is implemented as a simple macro that calls the HlinkSimpleNavigateToString function, passing it NULL for most parameters.

The HlinkNavigateString helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateMoniker, HlinkNavigateToStringReference, HlinkSimpleNavigateToString, IHlink::Navigate

HlinkNavigateToStringReference

HRESULT HlinkNavigateToStringReference(
    LPCWSTR pwzTarget,        //String helping to identify the hyperlink target
    LPCWSTR pwzLocation,      //Location within the hyperlink target of new hyperlink
    IHlinkSite * pihlsite,    //Site object interface for the new hyperlink object
    DWORD dwSiteData,         //Additional site data for the new hyperlink object
    IHlinkFrame * pihlframe,  //Frame object interface for the new hyperlink object
    DWORD grfHLNF,    //Navigation flags
    LPBC pibc,        //Bind context object 
    IBindStatusCallback * pibsc,    //Bind status callback object
    IHlinkBrowseContext * pihlbc    //Browse context object
   );

Creates a hyperlink site from strings representing the hyperlink target, the location within the target, and a friendly name, and then navigates to that site.

pwzTarget
[in] Address of the string that helps identify the hyperlink target. This string is resolved into a moniker for underlying binding operations through MkParseDisplayNameEx. Must not be NULL.
pwzLocation
[in] Address of the location within the hyperlink target of the new hyperlink object.
pihlsite
[in] Address of the IHlinkSite interface on the site object for the new hyperlink object. This is optional, in which case szTarget must be an absolute reference.
dwSiteData
[in] Additional site data for the new hyperlink object.
pihlframe
[in] Address of the IHlinkFrame interface for the hyperlink frame object of the hyperlink container object. Can be NULL if the hyperlink container does not have a hyperlink frame.
grfHLNF
[in] Value taken from the HLNF enumeration.
pibc
[in] Address of the IBindCtx interface on the bind context object to use for any moniker binding performed during the navigation. Must not be NULL.
pibsc
[in] Address of the IBindStatusCallback interface on the bind-status-callback object to use for any asynchronous moniker binding performed during the navigation. Can be NULL, in which case the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
pihlbc
[in] IHlinkBrowseContext interface pointer to the browse context object to use for this navigation. The browse context includes history information in which this navigation is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).

This helper function is identical to calling the following:

// create hyperlink site, IBindStatusCallback,
    // gather bind context, and browse context 
HlinkCreateFromString(pwzTarget, pwzLocation,
    pwzFriendlyName, &hlSite, dwSiteData, NULL,
    IID_IHlink, (void**)&phl);
HlinkNavigate(pihl, pihlframe, grfHLNF, pbc, pibsc, pihlbc);
phl->Release();

See also HLNF, HlinkNavigate, HlinkCreateFromString, HlinkSimpleNavigateToString

HlinkOnNavigate

HRESULT HlinkOnNavigate(
    IHlinkFrame * pihlframe,    //Frame object interface for the new hyperlink
    IHlinkBrowseContext * pihlbc,    //Browse context object to use for this navigation
    DWORD grfHLNF,      //Navigation flags
    IMoniker * pimkTarget,      //Moniker interface pointer of the hyperlink target
    LPCWSTR pwzLocation,        //Location within the hyperlink target of new hyperlink
    LPCWSTR pwzFriendlyName,    //Friendly name of the hyperlink
    ULONG * puHLID      // Pointer to hyperlink identifier
   );

Notifies a hyperlink browse context and hyperlink frame, if it exists, that a hyperlink target has been navigated to.

pihlframe
[in] Address of the IHlinkFrame interface of the hyperlink container. Can be NULL if the hyperlink container does not have a hyperlink frame.
pihlbc
[in] Address of the IHlinkBrowseContext interface for the browse context object to use for this navigation. The browse context includes history information in which this navigation is logged, if !(grfHLNF & HLNF_CREATENOHISTORY).
grfHLNF
[in] Value taken from the HLNF enumeration.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in] Address of the location within the hyperlink target of the new hyperlink object.
pwzFriendlyName
[in] Address of the friendly name of the hyperlink.
puHLID
[out] Address of the hyperlink identifier to set in the current browse context's navigation stack.

HlinkOnNavigate is a helper function typically called during IHlinkTarget::Navigate, which encapsulates the following calls:

phlbc->OnNavigateHlink(grfHLNF, pimkTarget, pwzLocation, pwzFriendlyName);
if (phlFrame)
    phlFrame->OnNavigate(grfHLNF);

See also IHlinkBrowseContext::OnNavigateHlink, IHlinkFrame::OnNavigate, IHlinkSite::OnNavigationComplete

HlinkQueryCreateFromData

HRESULT HlinkQueryCreateFromData(
    IDataObject* piDataObj    //Data object to query
   );

Determines if a new hyperlink can be created from an IDataObject interface.

piDataObj
[in] Address of the IDataObject interface supplying the hyperlink formats.

The application must call the HlinkQueryCreateFromData function to find out whether the hyperlink can be created from the data object obtained from the clipboard, from a drag-and-drop operation, or from any other means.

A hyperlink can be created if the IDataObject interface supports one of the following formats: cfHyperlink, cfUniformResourceLocator, CF_HDROP, or cfFileName.

See also HlinkCreateFromData

HlinkSetSpecialReference

HRESULT HlinkSetSpecialReference(
    ULONG uReference,       //Special reference flags
    LPCWSTR pwzReference    //The special reference string
   );

For a given value from the HLSR enumeration, sets the current user's default global home, search, or history page for browsing as a string.

uReference
[in] A value taken from the HLSR enumeration.
pwzReference
[in] Address of the special reference string.

See also HlinkGetSpecialReference, HLSR

HlinkSimpleNavigateToMoniker

HRESULT HlinkSimpleNavigateToMoniker(
    IMoniker * pmkTarget,    //Moniker of the hyperlink target
    LPCWSTR szLocation,      //Optional string representing location within target
    LPCWSTR szTargetFrameName,    //Optional string naming the target frame
    IUnknown * pUnk,         //IUnknown pointer to the initiating document or object
    IBindCtx * pbc,          //Bind context object
    IBindStatusCallback * pbsc,    //Bind status callback 
    DWORD grfHLNF,           //Navigation flags
    DWORD dwReserved         //Reserved for future use
   );

Executes a hyperlink jump to a new document or object (specified in pmkTarget).

pmkTarget
[in] Address of the moniker that identifies the hyperlink target. If NULL, the navigation is within a document.
szLocation
[in] Optional string representing the location within the hyperlink target for the new hyperlink.
szTargetFrameName
[in] Optional string naming the target frame for the hyperlink navigation. This argument only affects navigation within a document container that understands frame sets.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application. Note that if the caller of this function is an ActiveX Control or Document Object, you must pass a valid value for this parameter in order for navigation to work correctly.
pbc
[in] Address of the IBindCtx interface on the bind context to use for any moniker binding performed during the navigation. Must not be NULL.
pbsc
[in] Address of the IBindStatusCallback interface on the bind-status-callback to use for any asynchronous moniker binding performed during the navigation. The bind-status-callback will only return the standard IUnknown methods: AddRef and QueryInterface. When navigating in a new window, the only BindStatusCallback method that gets called is GetBindInfo. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
grfHLNF
[in] Value taken from the HLNF enumeration.
dwReserved
[in] Reserved for future use; must be set to NULL.

The HlinkSimpleNavigateToMoniker helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateToStringReference, HlinkSimpleNavigateToString, IHlink::Navigate

HlinkSimpleNavigateToString

HRESULT HlinkSimpleNavigateToString(
    LPCWSTR szTarget,    //String to be resolved into target's moniker
    LPCWSTR szLocation,    //Optional string representing location within target
    LPCWSTR szTargetFrameName,    //Optional string naming the target frame
    IUnknown * pUnk,     //IUnknown pointer to the initiating document or object
    IBindCtx * pbc,      //Bind context object
    IBindStatusCallback * pbsc,   //Bind status callback 
    DWORD grfHLNF,       //Navigation flags
    DWORD dwReserved     //Reserved for future use
   );

Executes a hyperlink jump to a new document or object (specified in szTarget).

szTarget
[in] String that helps identify the hyperlink target. This string is resolved into a moniker for underlying binding operations through MkParseDisplayNameEx. If NULL, the navigation is within a document. This parameter is required.
szLocation
[in] Optional string representing the location within the hyperlink target for the new hyperlink.
szTargetFrameName
[in] Optional string naming the target frame for the hyperlink navigation. This argument only affects navigation within a document container that understands frame sets.
pUnk
[in] Address of the IUnknown interface on the document or object that is initiating the hyperlink. If NULL, it is assumed the hyperlink originates from an ActiveX-unaware application. Note that if the caller of this function is an ActiveX Control or Document Object, you must pass a valid value for this parameter in order for navigation to work correctly.
pbc
[in] Address of the IBindCtx interface on the bind context to use for any moniker binding performed during the navigation. Must not be NULL.
pbsc
[in] Address of the IBindStatusCallback interface on the bind-status-callback to use for any asynchronous moniker binding performed during the navigation. The bind-status-callback will only return the standard IUnknown methods: AddRef and QueryInterface. When navigating in a new window, the only BindStatusCallback method that gets called is GetBindInfo. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information.
grfHLNF
[in] Value taken from the HLNF enumeration.
dwReserved
[in] Reserved for future use; must be set to NULL.

The HlinkSimpleNavigateToString helper function should be used by all applications, documents, and objects that have simple navigation needs. This single function call will "do the right thing" depending on whether the navigation is originating from within a hyperlink frame or within a hyperlink-unaware application.

See also HLNF, HlinkNavigateToStringReference, HlinkSimpleNavigateToMoniker, IHlink::Navigate

Enumerations

This section describes the following enumerations:

HLBWIF

typedef enum tagHLBWIF 
{ 
    HLBWIF_HASFRAMEWNDINFO,    =  1, 
    HLBWIF_HASDOCWNDINFO,      =  2, 
    HLBWIF_FRAMEWNDMAXIMIZED,  =  4, 
    HLBWIF_DOCWNDMAXIMIZED,    =  8, 
} HLBWIF; 

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

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
Only useful in combination with HLBWIF_HASFRAMEWNDINFO. Indicates that frame-level windows of the browse context should appear maximized.
HLBWIF_DOCWNDMAXIMIZED
Only useful in combination with HLBWIF_HASDOCWNDINFO. Indicates that document-level windows of the browse context should appear maximized.

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 in order to reposition their user interface properly and ensure as seamless a transition as possible to the new document or object.

See also HLBWINFO, IHlinkBrowseContext::GetBrowseWindowInfo, IHlinkBrowseContext::SetBrowseWindowInfo

HLFNAMEF

typedef enum tagHLFNAMEF 
{ 
    HLFNAMEF_DEFAULT,          =  0, 
    HLFNAMEF_TRYCACHE,         =  1, 
    HLFNAMEF_TRYPRETTYTARGET,  =  2, 
    HLFNAMEF_TRYFULLTARGET,    =  4, 
    HLFNAMEF_TRYWIN95SHORTCUT  =  8, 
} HLFNAMEF ;

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

HLFNAMEF_DEFAULT
The cached friendly name, or else the simplified display name.
HLFNAMEF_TRYCACHE
The friendly name that is cached in the hyperlink object.
HLFNAMEF_TRYPRETTYTARGET
A beautified version of the display name of the hyperlink target.
HLFNAMEF_TRYFULLTARGET
The full display name of the hyperlink target.
HLFNAMEF_TRYWIN95SHORTCUT
A simplified version of the full display name of the hyperlink target.

See also IHlink::GetFriendlyName

HLID

typedef enum tagHLID 
{ 
    HLID_PREVIOUS,
    HLID_NEXT,
    HLID_CURRENT,
    HLID_STACKBOTTOM,
    HLID_STACKTOP
} HLID;

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

HLID_PREVIOUS
The 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
The 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
The 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
The very 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
The very 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.

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 enable Go Back and Go Forward.

See also HLQF, IHlinkBrowseContext::GetHlink, IHlinkBrowseContext::QueryHlink, IHlinkBrowseContext::SetCurrentHlink

HLINKGETREF

typedef enum tagHLINKGETREF 
{ 
    HLINKGETREF_DEFAULT,   =  0, 
    HLINKGETREF_ABSOLUTE,  =  1, 
    HLINKGETREF_RELATIVE   =  2, 
} 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.

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.

See also IHlink::GetMonikerReference, IHlink::GetStringReference

HLINKMISC

typedef enum tagHLINKMISC 
{ 
    HLINKMISC_RELATIVE,  =  1, 
} HLINKMISC ;

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

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

See also IHlink::GetMiscStatus

HLINKSETF

typedef enum tagHLINKSETF 
{ 
    HLINKSETF_TARGET,     1, 
    HLINKSETF_LOCATION,   2, 
} HLINKSETF ;

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

HLINKSETF_TARGET
Used to specify the setting of the pmkTarget parameter of the Hlink object.
HLINKSETF_LOCATION
Used to specify the setting of the szLocation parameter of the Hlink object.

See also IHlink::SetMonikerReference

HLINKWHICHMK

typedef enum tagHLINKWHICHMK 
{ 
    HLINKWHICHMK_CONTAINER,  =  1, 
    HLINKWHICHMK_BASE,       =  2, 
} 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.

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. (These might be different, for example, if a BASE tag is used in HTML.)

See also IHlinkSite::GetMoniker

HLNF

typedef enum tagHLNF 
{ 
    HLNF_INTERNALJUMP
    HLNF_OPENINNEWWINDOW
} 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.

HLNF_INTERNALJUMP
The navigation is an internal jump within the current hyperlink target.
HLNF_OPENINNEWWINDOW
An abbreviation for two commonly coincident options: HLNF_USEBROWSECONTEXTCLONE and HLNF_OFFSETWINDOWORG.

See also HlinkSimpleNavigateToMoniker, HlinkSimpleNavigateToString

HLQF

typedef enum tagHLQF 
{ 
    HLQF_ISVALID,    =  1, 
    HLQF_ISCURRENT,  =  2  
} HLQF;

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

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.

See also HLID, IHlinkBrowseContext::QueryHlink

HLSR

typedef enum tagHLSR 
{ 
    HLSR_HOME,         =  0, 
    HLSR_SEARCHPAGE,   =  1, 
    HLSR_HISTORYFOLDER =  2, 
} HLSR ;

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

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.

See also HlinkGetSpecialReference, HlinkSetSpecialReference

Structures

This section describes the following structures:

HLBWINFO

typedef struct tagHLBWINFO 
{ 
    ULONG cbSize; 
    DWORD grfHLBWIF; 
    RECT rcFramePos; 
    RECT rcDocPos; 
    HLTBINFO hltbinfo; 
} HLBWINFO; 

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

cbSize
Total size of this structure, in bytes.
grfHLBWIF
Values taken from the HLBWIF enumeration.
rcFramePos
If grfHLBWIF & HLBWIF_HASFRAMEWNDINFO, contains the rectangle in screen coordinates of current frame-level windows within the browse context. When grfHLBWIF & HLBWIF_FRAMEWNDMAXIMIZED, frame-level windows are currently being 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 nonmaximized.
rcDocPos
If grfHLBWIF & HLBWIF_HASDOCWNDINFO, contains the rectangle in screen coordinates of current document-level windows within the browse context. When grfHLBWIF & 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 nonmaximized.
hltbinfo
Provides information on the position of the Web toolbar. This enables the target application to display its toolbar in the same location.

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 in order to reposition their user interface properly and ensure as seamless a transition as possible to the new document or object.

See also HLBWIF, IHlinkBrowseContext::GetBrowseWindowInfo, IHlinkBrowseContext::SetBrowseWindowInfo, IHlinkTarget::Navigate

HLITEM

typedef struct tagHLITEM 
{ 
    ULONG uHLID; 
    LPWSTR pwzFriendlyName; 
} HLITEM; 

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

uHLID
Used to identify the hyperlink. Standard enumerators never return one of the logical HLID constants in this member, always an identifier.
pwzFriendlyName
Address of the hyperlink's friendly name. Appropriate for display in the user interface.

The HLITEM structure is returned by the IEnumHLITEM enumerator, which is returned from IHlinkBrowseContext::EnumNavigationStack.

See also HLID, IEnumHLITEM, IHlinkBrowseContext::EnumNavigationStack

Objects

This section describes the following object:

Hyperlink Object

A hyperlink object is a reference to another location within either a new or existing document. It encapsulates four pieces of reference information:

A hyperlink object also supports the ability to save and load itself by using IPersistStream, and the ability to be transferred through the clipboard or through a drag-and-drop operation by using IDataObject.

It is notable that a document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the work of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks.

Implementation

A standard hyperlink implementation is provided with the operating system, and you should be able to use it for your applications. Custom implementations should be used only with the greatest caution.

Creation/Access API Functions
HlinkCreateFromData Creates a hyperlink object from an object that supports the IDataObject interface (a data object).
HlinkCreateFromMoniker Creates a new hyperlink from a moniker, a location within the target, and a friendly name string (used for displaying the hyperlink).
HlinkCreateFromString Creates a new hyperlink object from strings representing the hyperlink target, the location within the target, and a friendly name.
OleLoadFromStream Allows the hyperlink object to be loaded from persistent data.

Interfaces
IDataObject Enables data transfer.
IHlink Enables a hyperlink (a COM object) to encapsulate the behavior of navigating to its target location.
IHlinkSite Indicates the implemented document/object that contains the hyperlink object. A hyperobject implementation uses this interface (if it's available) for resolving the relative monikers and also to notify before and after the target document/object is displayed.
IPersistStream Provides methods for saving and loading objects that use a simple serial stream for their storage needs.

Hyperlink Browse Context Object

The hyperlink browse context maintains the navigation stack that is passed around during navigation from one document or application to another.

In addition to maintaining the navigation stack, the browse context knows whether the Go Forward and Go Back commands should be enabled. It is also used to pass around window-position information so that hyperlinking from one top-level window to another can happen while giving the illusion of window reuse (by positioning the windows on top of each other).

Implementation

Like the hyperlink object, the browse context is a standard object provided by the operating system.

Creation/Access API Functions
HlinkCreateBrowseContext Creates an empty default instance of the system browse context object.

Interfaces
IHlinkBrowseContext Enables a COM object to define and manage the browsing context for an OLE hyperlink application.

Hyperlink Target Object

A hyperlink target is a destination of hyperlink navigation. This can be a persisted OLE object that exposes IHlinkTarget, a persisted OLE object that exposes IOleObject, or any file that is viewed when its viewer application is launched by using ShellExecute.

A hyperlink target can be a top-level container document, an embedded object of arbitrary nesting, or generally any object that can be referenced by using a moniker.

Implementation

If an object (document) wants to be targeted by hyperlinks, it can integrate tightly with OLE hyperlinks by implementing the IHlinkTarget interface. If the object does not support IHlinkTarget, it can still act as a hyperlink target, but it won't be able to support internal navigation, and it will not have access to the common browse context that holds the navigation stack.

An existing OLE document application that supports OLE linking need only implement the IHlinkTarget interface on the same object that implements IPersistFile and IOleItemContainer. The application can also implement IPersistMoniker to support incremental rendering or asynchronous download as a persistence mechanism, rather than IPersistFile. Supporting IHlinkTarget from an OLE document object is the recommended way to make sure your document is viewable by browsers and participates in hyperlinking smoothly.

Creation/Access API Functions

In a document, hyperlink objects implement the IHlink interface. When a user clicks a hyperlink, the application calls IHlink::Navigate, using a helper API function if preferred. The IHlink::Navigate implementation calls BindMoniker to get the pointer of the target object, requests the IHlinkTarget interface, and calls IHlinkTarget::Navigate.

Interfaces
IHlinkTarget Provides for navigation to locations within the target's objects. A hyperlink target object implements this interface for this reason.
IOleObject Allows an embedded object to communicate with and provide basic functionality to its container.

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