Reference

Reference


This ActiveX Hyperlinks reference contains the following sections:

Interfaces

This section describes the following interfaces:

Hlink

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.

Implementing IHlink

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.

Using IHlink

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/application—a hyperlink container—to another document/object/application—a 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. Active Document objects in a browser.
  3. Active Document objects in an Office Binder-like application that does not support OLE in-place/DocObj server functionality, and, therefore, can't be shown in-place in a browser.

The following are possible forms of navigation:

IHlink Methods in Vtable Order

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.

IHlink::GetAdditionalParams

HRESULT GetAdditionalParams(
    LPWSTR * ppwzAdditionalParams    //Extensible parameter string
   );

Retrieves additional parameters or properties for the hyperlink.

ppwzAdditionalParams
[out] On return, points to the location to return the string containing a list of parameters or properties for the hyperlink in the following format:
<ID1 = "value1"> <ID2 = "value2"> ... <IDn = "valuen">

The parameters retrieved in this string are primarily interpreted by the hyperlink frame.

See also IHlink::SetAdditionalParams

IHlink::GetFriendlyName

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.

grfHLFNAMEF
[in] Flag specifying the friendly name to return.
ppwzFriendlyName
[out] Address of the buffer to return the friendly name. This string must be allocated using CoTaskMemAlloc. It is the caller's responsibility to free this string using CoTaskMemFree.

See also IHlink::SetFriendlyName, IHlinkTarget::GetFriendlyName

IHlink::GetHlinkSite

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.

ppihlSite
[out] On return, points to the IHlinkSite interface pointer on the hyperlink object. This cannot be a NULL pointer on input.
pdwSiteData
[out] On return, points to the site data of the hyperlink target. This must not be a NULL pointer on input.

See also IHlink::SetHlinkSite

IHlink::GetMiscStatus

HRESULT GetMiscStatus(
    DWORD * pdwStatus    //Receives absolute/relative status of hyperlink
   );

Queries whether the hyperlink is an absolute or a relative link.

pdwStatus
[out] On return, points to a value from the HLINKMISC enumeration. Must not be NULL.

See also HLINKMISC

IHlink::GetMonikerReference

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.

dwWhichRef
[in] Value from the HLINKGETREF enumeration specifying whether to get the absolute or relative reference to the hyperlink target.
ppimkTarget
[out] On return, points to the IMoniker pointer of the target's moniker object, if any. Can be NULL, in which case the caller is not interested in the moniker to the hyperlink reference.
ppwzLocation
[out] On return, points to the string location portion of the target, if any. If NULL, the caller is not interested in the location portion of the hyperlink reference.

See also HLINKGETREF, IHlinkSite::GetMoniker, IHlinkTarget::GetMoniker

IHlink::GetStringReference

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.

dwWhichRef
[in] Value from the HLINKGETREF enumeration specifying whether to get the absolute or relative reference to the hyperlink target.
ppwzTarget
[out] On return, points to a string that helps identify the hyperlink target of the hyperlink reference. If NULL, the caller is not interested in the target string of the hyperlink reference.
ppwzLocation
[out] On return, points to the location portion of the hyperlink reference. If NULL, the caller is not interested in the location portion of the hyperlink reference.

See also IHlink::GetMonikerReference, HLINKGETREF, HlinkNavigateToStringReference, HlinkSimpleNavigateToString

IHlink::GetTargetFrameName

HRESULT GetTargetFrameName(
    LPWSTR * ppwzTargetFrameName    //Receives the target frame name for the hyperlink
   );

Retrieves the name of the target frame for the hyperlink.

ppwzTargetFrameName
[out] On return, points to the target frame name for the hyperlink. Must not be NULL.

See also IHlink::SetTargetFrameName

IHlink::Navigate

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.

grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pibc
[in, unique] IBindCtx interface pointer to the bind context to be used for any moniker binding during this operation. Cannot be NULL.
pibsc
[in, unique] IBindStatusCallback interface pointer to the bind status context to use for any asynchronous moniker binding performed during the navigation. If NULL, the caller is not interested in progress notification, cancellation, pausing, or low-level binding information
pihlbc
[in, unique] Address of the IHlinkBrowseContext interface to use for this navigation. Cannot be NULL. As part of navigation, this browse context's navigation stack can be updated (depending on the navigation flags in grfHLNF), and its cache of hyperlink targets is consulted for a matching to the current hyperlink target.

See also HlinkNavigate, HLNF, IHlinkFrame::Navigate, IHlinkTarget::Navigate

IHlink::SetAdditionalParams

HRESULT SetAdditionalParams(
    LPCWSTR  pwzAdditionalParams    //Extensible parameter string
   );

Sets the additional parameters or properties for the hyperlink.

pwzAdditionalParams
[in, unique] The string containing a list of parameters or properties for the hyperlink in the following format:
<ID1 = "value1"> <ID2 = "value2"> ... <IDn = "valuen">

The parameters saved in this string are primarily interpreted by the hyperlink frame.

See also IHlink::GetAdditionalParams

IHlink::SetFriendlyName

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.

pwzFriendlyName
[in, unique] The friendly name string of the hyperlink target.

See also IHlink::GetFriendlyName

IHlink::SetHlinkSite

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.

pihlSite
[in, unique] Address of a new IHlinkSite object for this hyperlink.
dwSiteData
[in] DWORD that specifies additional information about the site. For instance, each site can differ in color or style from other sites in the same container.

See also IHlink::GetHlinkSite

IHlink::SetMonikerReference

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.

grfHLSETF
[in] Used to indicate whether to set the hyperlink target, the location within the target, or both.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.

See also HLINKSETF

IHlink::SetStringReference

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.

grfHLSETF
[in] Used to indicate whether to set the hyperlink target, the location within the target, or both.
pwzTarget
[in, unique] The string target name for the hyperlink.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.

See also HLINKSETF

IHlink::SetTargetFrameName

HRESULT SetTargetFrameName(
    LPCWSTR  pwzTargetFrameName    //Target frame name for the hyperlink
   );

Sets the target frame name for the hyperlink.

pwzTargetFrameName
[in, unique] The string target frame name for the hyperlink.

See also IHlink::GetTargetFrameName

IHlinkBrowseContext

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.

Implementing IHlinkBrowseContext

The system provides a default implementation.

IHlinkBrowseContext Methods in Vtable Order

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.

IHlinkBrowseContext::Clone

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.

piunkOuter
[in, unique] Address of the controlling IUnknown interface for the new browse context. If NULL, the new browse context is not aggregated.
riid
[in] The interface to return on the new hyperlink. Typically IID_IHlink or IID_IUnknown when punkOuter is non-NULL.
ppiunkObj
[out, iid_is] Indirect pointer to the clone of the browse context object.

IHlinkBrowseContext::Close

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.

dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.

See also IHlinkBrowseContext::Register

IHlinkBrowseContext::EnumNavigationStack

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.

dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.
grfHLFNAMEF
[in] Indicator of what kind of friendly names to enumerate for the Hlink objects in the navigation stack.
ppienumhlitem
[out] Location to return the IEnumHLITEM enumeration interface over the set of hyperlinks in this navigation stack.

See also HLID, HLITEM, IEnumHLITEM

IHlinkBrowseContext::GetBrowseWindowInfo

HRESULT GetBrowseWindowInfo(
    HLBWINFO * phlbwi    //Location to receive the HLBWINFO structure
   );

Retrieves the HLBWINFO structure currently associated with this browse context.

phlbwi
[out] Address of the location to return the current HLBWINFO structure.

See also HLBWINFO, IHlinkBrowseContext::SetBrowseWindowInfo

IHlinkBrowseContext::GetHlink

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.

uHLID
[in] Used to identify the hyperlink to retrieve. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.
ppihl
[out] Address of the buffer to return the IHlink interface pointer of the hyperlink object.

See also HLID, IHlink, IHlinkBrowseContext::SetCurrentHlink

IHlinkBrowseContext::GetObject

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.

pimk
[in,unique] Used to identify the object being retrieved.
fBindIfRootRegistered
[in] If set to TRUE, this method binds to the moniker and retrieves the object (if the object referred to by pimk is not registered in the browse context).
ppiunk
[out] Indirect pointer to the IUnknown interface of the object being retrieved.

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

IHlinkBrowseContext::OnNavigateHlink

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.

grfHLNF
[in] Flags describing how the navigation is to proceed. The value of the flag can be any valid HLNF enumeration value.
pimkTarget
[in, unique] Address of an IMoniker interface on the hyperlink target.
pwzLocation
[in, unique] A string identifying the location within the hyperlink target that was navigated to. Must not be NULL.
pwzFriendlyName
[in, unique] The friendly name of the location within the hyperlink target that has been navigated to. Must not be NULL.
puHLID
[out] Address of the hyperlink indentifier to set in the current browse context's navigation stack.

See also HlinkOnNavigate, HLNF, IHlinkFrame::OnNavigate, IHlinkSite::OnNavigationComplete

IHlinkBrowseContext::QueryHlink

HRESULT QueryHlink(
    DWORD grfHLQF,    //Value from the HLQF enumeration
    ULONG uHLID       //Hyperlink identifier to query
   );

Tests the validity of a uHLID value.

grfHLQF
[in] A single value taken from the HLQF enumeration.
uHLID
[in] Used to identify the hyperlink to query about. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

See also HLID, HLQF

IHlinkBrowseContext::Register

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.

dwReserved
[in] Reserved for future use; must be set to zero by the caller. To ensure compatibility with future use, the callee must not check for zero.
piunk
[in, unique] The object being registered.
pimk
[in, unique] Address of the IMoniker interface pointer that identifies the object being registered.
pdwRegister
[out] Address of a location to return a value identifying the registration, which can be used to subsequently revoke the registration.

See also HlinkCreateBrowseContext, IHlinkBrowseContext::Close, IHlinkBrowseContext::Revoke

IHlinkBrowseContext::Revoke

HRESULT Revoke(
    DWORD dwRegister    //Object to revoke
   );

Revokes an object previously registered with this browse context.

dwRegister
[in] Used to identify the object to revoke. Returned by a previous call to IHlinkBrowseContext::Register.

See also IHlinkBrowseContext::Register

IHlinkBrowseContext::SetBrowseWindowInfo

HRESULT SetBrowseWindowInfo(
    HLBWINFO * phlbwi    //Pointer to the new HLBWINFO structure for this browse context
   );

Establishes the HLBWINFO structure of this browse context.

phlbwi
[in,unique] Address of the new HLBWINFO structure for this browse context.

See also HLBWINFO, IHlinkBrowseContext::GetBrowseWindowInfo

IHlinkBrowseContext::SetCurrentHlink

HRESULT SetCurrentHlink(
    ULONG uHLID    //Hyperlink ID to set in the navigation stack
   );

Sets the current hyperlink in this browse context's navigation stack.

uHLID
[in] Used to identify the hyperlink to set in the current browse context's navigation stack. Can be a value taken from the HLID constants to indicate a logically identified hyperlink, such as HLID_PREVIOUS or HLID_NEXT.

See also HLID, IHlinkBrowseContext::GetHlink

IHlinkFrame

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.

Implementing IHlinkFrame

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.

Using IHlinkFrame

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 in Vtable Order

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.