
This ActiveX Hyperlinks reference contains the following sections:
This section describes the following interfaces:
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.
Typically, you don't 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.
The support for IPersistStream means that hyperlink objects can be saved to or loaded from a stream, and the support for IDataObject means that hyperlink objects can be cut and pasted.
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 through the HlinkCreateFromData, HlinkCreateFromMoniker, HlinkCreateFromString, and OleLoadFromStream functions.
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" functions, 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/applicationa hyperlink containerto another document/object/applicationa 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:
The following are possible forms of navigation:
| IHlink methods | Description |
| SetHlinkSite | Saves the interface pointer on the site object. |
| GetHlinkSite | Retrieves the interface pointer on the site object. |
| SetMonikerReference | Sets the moniker reference of the target. |
| GetMonikerReference | Retrieves the moniker and location portions of the target. |
| SetStringReference | Sets the name and location portions of the target. |
| GetStringReference | Retrieves the name and location portions of the target. |
| SetFriendlyName | Sets the friendly name of the target. |
| GetFriendlyName | Retrieves the friendly name of the target. |
| SetTargetFrameName | Sets the name of the target frame. |
| GetTargetFrameName | Retrieves the name of the target frame. |
| GetMiscStatus | Queries if hyperlink is absolute or relative. |
| Navigate | Navigates to the given target. |
| SetAdditionalParams | Sets additional hyperlink parameters. |
| GetAdditionalParams | Retrieves additional hyperlink parameters. |
HRESULT GetAdditionalParams(
LPWSTR * ppwzAdditionalParams //Extensible parameter string
);
Retrieves additional parameters or properties for the hyperlink.
<ID1 = "value1"> <ID2 = "value2"> ... <IDn = "valuen">
The parameters retrieved in this string are primarily interpreted by the hyperlink frame.
See also IHlink::SetAdditionalParams
HRESULT GetFriendlyName(
DWORD grfHLFNAMEF, //Flag specifying the friendly name to return.
LPWSTR * ppwzFriendlyName //Buffer to receive the friendly name.
);
Retrieves the friendly name of the target. The container normally uses this name to determine how to represent the hyperlink in its user interface.
See also IHlink::SetFriendlyName, IHlinkTarget::GetFriendlyName
HRESULT GetHlinkSite(
IHlinkSite * ppihlSite, //Receives the hyperlink site interface
DWORD *pdwSiteData //Receives additional site data
);
Retrieves the hyperlink site and associated site data from a hyperlink object.
See also IHlink::SetHlinkSite
HRESULT GetMiscStatus(
DWORD * pdwStatus //Receives absolute/relative status of hyperlink
);
Queries whether the hyperlink is an absolute or a relative link.
See also HLINKMISC
HRESULT GetMonikerReference(
DWORD dwWhichRef, /Absolute or relative reference
IMoniker * ppimkTarget, //Receives a pointer to the moniker of the hyperlink target
LPWSTR * ppwzLocation //Receives the location portion of the hyperlink target
);
Retrieves the moniker and location portions of the hyperlink reference.
See also HLINKGETREF, IHlinkSite::GetMoniker, IHlinkTarget::GetMoniker
HRESULT GetStringReference(
DWORD dwWhichRef, //Absolute or relative reference
LPWSTR * ppwzTarget, //Receives the string that helps identify the hyperlink target
LPWSTR * ppwzLocation //Receives the location portion of the hyperlink target
);
Retrieves strings that identify the hyperlink target and the location within the hyperlink target.
See also IHlink::GetMonikerReference, HLINKGETREF, HlinkNavigateToStringReference, HlinkSimpleNavigateToString
HRESULT GetTargetFrameName(
LPWSTR * ppwzTargetFrameName //Receives the target frame name for the hyperlink
);
Retrieves the name of the target frame for the hyperlink.
See also IHlink::SetTargetFrameName
HRESULT Navigate(
DWORD grfHLNF, //Navigation flags
LPBC pibc, //Bind context interface pointer
IBindStatusCallback * pibsc, //Bind-status-context interface pointer
IHlinkBrowseContext * pihlbc //Browse context interface pointer
);
Navigates to the hyperlink reference. IHlink::Navigate is the heart of the navigation process that implements the action of resolving a hyperlink target.
See also HlinkNavigate, HLNF, IHlinkFrame::Navigate, IHlinkTarget::Navigate
HRESULT SetAdditionalParams(
LPCWSTR pwzAdditionalParams //Extensible parameter string
);
Sets the additional parameters or properties for the hyperlink.
<ID1 = "value1"> <ID2 = "value2"> ... <IDn = "valuen">
The parameters saved in this string are primarily interpreted by the hyperlink frame.
See also IHlink::GetAdditionalParams
HRESULT SetFriendlyName(
LPCWSTR pwzFriendlyName //Friendly name of the hyperlink
);
Sets the friendly name for the hyperlink. The friendly name is used by hyperlink containers to represent the hyperlink within their user interface.
See also IHlink::GetFriendlyName
HRESULT SetHlinkSite(
IHlinkSite * pihlSite, //Interface pointer to the new hyperlink site
DWORD dwSiteData //Additional site data
);
Sets the hyperlink site and associated site data on a hyperlink object.
See also IHlink::GetHlinkSite
HRESULT SetMonikerReference(
DWORD grfHLSETF, //Specifies whether to set the hyperlink target, the location
// within the target, or both.
IMoniker * pimkTarget, //Moniker interface pointer of the hyperlink target
LPCWSTR pwzLocation //Location within the hyperlink target of new hyperlink
);
Sets the target moniker or location string values for a hyperlink object.
See also HLINKSETF
HRESULT SetStringReference(
DWORD grfHLSETF, //Specifies whether to set the hyperlink target, the location within the target,
// or both.
LPCWSTR pwzTarget, //Target name for the hyperlink
LPCWSTR pwzLocation //Location within the hyperlink target of new hyperlink
);
Sets the target string or location string values for a hyperlink object.
See also HLINKSETF
HRESULT SetTargetFrameName(
LPCWSTR pwzTargetFrameName //Target frame name for the hyperlink
);
Sets the target frame name for the hyperlink.
See also IHlink::GetTargetFrameName
The IHlinkBrowseContext interface enables a COM object to define and manage the browsing context for an ActiveX hyperlink application.
A hyperlink browse context keeps track of the order in which the object/documents (perhaps belonging to different processes) have been visited and chains them together into a navigation stack. The context also keeps track of enabling or disabling buttons such as Go Forward or Go Back for each entry in the navigation stack. In addition, the context maintains window positioning information for hyperlink targets so that a hyperlink application can provide a seamless user interface.
Browse context objects are not required for hyperlink navigation. HlinkSimpleNavigateToString and HlinkSimpleNavigateToMoniker provide examples of navigation between hyperlink containers and hyperlink targets that do not use a browsing context.
IHlinkBrowseContext provides methods that maintain the hyperlink navigation stack and keep track of window position information.
The system provides a default implementation.
| IHlinkBrowseContext methods | Description |
| Register | Registers an object with the browse context. |
| GetObject | Retrieves an object previously registered in the browse context under the given name. |
| Revoke | Revokes an object previously registered with this browse context. |
| SetBrowseWindowInfo | Establishes the browse window information structure of this browse context. |
| GetBrowseWindowInfo | Retrieves the browse window information structure associated with this browse context. |
| EnumNavigationStack | Retrieves an enumerator that can be used to enumerate the current contents of the navigation stack. |
| QueryHlink | Tests the validity of a hyperlink ID value. |
| GetHlink | Retrieves a hyperlink from this browse context. |
| SetCurrentHlink | Sets the current hyperlink in this browse context's navigation stack. |
| OnNavigateHlink | Notifies a browse context that a hyperlink has been navigated. |
| Clone | Duplicates a browse context. |
| Close | Closes the hyperlink browse context. |
HRESULT Clone(
IUnknown* piunkOuter, //Controlling IUnknown interface for new browse context
REFIID riid, //Interface ID to return on the new browse context
IUnknown** ppiunkObj //Indirect pointer to the clone of the browse context object
);
Duplicates a browse context.
HRESULT Close(
DWORD dwReserved //Reserved for future use
);
Closes the hyperlink browse context. Releases all hyperlink targets that have been registered with the browse context.
See also IHlinkBrowseContext::Register
HRESULT EnumNavigationStack(
DWORD dwReserved, //Reserved for future use
DWORD grfHLFNAMEF, //Specifies what kind of friendly names to enumerate for the Hlink objects in the navigation stack.
IEnumHLITEM ** ppienumhlitem //Location to receive the enumeration interface pointer
);
Retrieves an enumerator that can be used to enumerate the current contents of the navigation stack.
See also HLID, HLITEM, IEnumHLITEM
HRESULT GetBrowseWindowInfo(
HLBWINFO * phlbwi //Location to receive the HLBWINFO structure
);
Retrieves the HLBWINFO structure currently associated with this browse context.
See also HLBWINFO, IHlinkBrowseContext::SetBrowseWindowInfo
HRESULT GetHlink(
ULONG uHLID, //Hyperlink to retrieve
IHlink * ppihl //Buffer to return the IHlink interface of the hyperlink
);
Retrieves a hyperlink from this browse context.
See also HLID, IHlink, IHlinkBrowseContext::SetCurrentHlink
HRESULT GetObject(
IMoniker * pimk, //Moniker interface pointer of the object being retrieved
BOOL fBindIfRootRegistered, //Determines binding to the moniker and retrieval of the object
IUnknown ** ppiunk //Location to receive the unknown interface pointer of requested object
);
Retrieves an object previously registered in the browse context.
If the object referred to by pimk is not registered in the browse context, this method binds to the full moniker and retrieves the object if the following conditions are met:
See also IHlinkBrowseContext::Register
HRESULT OnNavigateHlink(
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 browse context that a hyperlink has been navigated.
See also HlinkOnNavigate, HLNF, IHlinkFrame::OnNavigate, IHlinkSite::OnNavigationComplete
HRESULT QueryHlink(
DWORD grfHLQF, //Value from the HLQF enumeration
ULONG uHLID //Hyperlink identifier to query
);
Tests the validity of a uHLID value.
| S_OK | If grfHLQF is HLQF_ISVALID, uHLID identifies a valid hyperlink within the browse context. If grfHLQF is HLQF_ISCURRENT, uHLID identifies the current hyperlink of the browse context. |
| S_FALSE | If grfHLQF is HLQF_ISVALID, uHLID does not identify a valid hyperlink within the browse context. If grfHLQF is HLQF_ISCURRENT, uHLID does not identify the current hyperlink of the browse context. |
HRESULT Register(
DWORD dwReserved, //Reserved for future use
IUnknown piunk, //Object being registered
IMoniker * pimk, //Moniker interface pointer of the object being registered
DWORD * pdwRegister //Receives the registration value
);
Registers an object with the browse context.
| S_OK | The object has been registered. |
| MK_S_MONIKERALREADYREGISTERED | The object was successfully registered, but another object (possibly the same object) has already been registered with the same moniker in this browse context. |
| E_OUTOFMEMORY | There was insufficient memory to register the object with the browse context. |
See also HlinkCreateBrowseContext, IHlinkBrowseContext::Close, IHlinkBrowseContext::Revoke
HRESULT Revoke(
DWORD dwRegister //Object to revoke
);
Revokes an object previously registered with this browse context.
See also IHlinkBrowseContext::Register
HRESULT SetBrowseWindowInfo(
HLBWINFO * phlbwi //Pointer to the new HLBWINFO structure for this browse context
);
Establishes the HLBWINFO structure of this browse context.
See also HLBWINFO, IHlinkBrowseContext::GetBrowseWindowInfo
HRESULT SetCurrentHlink(
ULONG uHLID //Hyperlink ID to set in the navigation stack
);
Sets the current hyperlink in this browse context's navigation stack.
See also HLID, IHlinkBrowseContext::GetHlink
The IHlinkFrame interface provides methods that allow a hyperlink frame to interpose itself in the navigation process to allow an application to provide a seamless user interface when navigating from one document/object/application to another when resolving a hyperlink.
This interface is typically implemented by a document container object, such as Microsoft Internet Explorer or Microsoft Office Binder. A document container implementing the IHlinkFrame interface can host documents that support in-frame navigation from one to another.
You do not normally call the IHlinkFrame methods directly. They are referenced by the IHlink::Navigate routines when a hyperlink frame is detected.
| IHlinkFrame methods | Description |
| GetBrowseContext | Retrieves the browse context of the hyperlink frame. |
| Navigate | Navigates to the target hyperlink. |
| OnNavigate | Notifies the hyperlink frame of a hyperlink navigation. |
| SetBrowseContext | Sets the browse context of the hyperlink frame. |
| UpdateHlink | Updates the hyperlink frame. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.