
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).
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
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.
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
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.
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
HRESULT HlinkQueryCreateFromData(
IDataObject* piDataObj //Data object to query
);
Determines if a new hyperlink can be created from an IDataObject interface.
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
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.
See also HlinkGetSpecialReference, HLSR
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).
This function can also return any value returned by IHlink::Navigate.
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
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).
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
This section describes the following enumerations:
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.
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
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.
See also IHlink::GetFriendlyName
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.
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
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.
See also IHlink::GetMonikerReference, IHlink::GetStringReference
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.
See also IHlink::GetMiscStatus
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.
See also IHlink::SetMonikerReference
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.
See also IHlinkSite::GetMoniker
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.
See also HlinkSimpleNavigateToMoniker, HlinkSimpleNavigateToString
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.
See also HLID, IHlinkBrowseContext::QueryHlink
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.
See also HlinkGetSpecialReference, HlinkSetSpecialReference
This section describes the following structures:
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.
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
typedef struct tagHLITEM
{
ULONG uHLID;
LPWSTR pwzFriendlyName;
} HLITEM;
Indicates the data structure used by the system browse context to track hyperlinks.
The HLITEM structure is returned by the IEnumHLITEM enumerator, which is returned from IHlinkBrowseContext::EnumNavigationStack.
See also HLID, IEnumHLITEM, IHlinkBrowseContext::EnumNavigationStack
This section describes the following 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. |
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. |
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.