
HRESULT GetBrowseContext(
IHlinkBrowseContext * ppihlbc //Buffer to receive the interface of the current browse context
);
Retrieves the browse context of the hyperlink frame.
See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::SetBrowseContext, IHlinkTarget
HRESULT Navigate(
DWORD grfHLNF, //Navigation flags
LPBC pbc, //Bind context interface pointer
IBindStatusCallback * pibsc, //Bind-status callback interface pointer
IHlink * pihlNavigate //Hyperlink target interface pointer
);
Navigates to the hyperlink target.
| S_OK | The navigation to the target has been successful. |
| IHlink::Navigate errors | Since IHlinkFrame::Navigate calls IHlink::Navigate, the errors associated with this method can be returned. |
See also HLNF, IHlink::Navigate
HRESULT OnNavigate(
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
);
Notifies the hyperlink frame that a hyperlink has been navigated to.
See also HlinkOnNavigate, HLNF, IHlinkBrowseContext::OnNavigateHlink, IHlinkSite::OnNavigationComplete
HRESULT SetBrowseContext(
IHlinkBrowseContext * phlbc //Interface pointer of the current browse context
);
Sets the browse context of the hyperlink frame.
See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::GetBrowseContext, IHlinkTarget::SetBrowseContext
HRESULT UpdateHlink(
ULONG uHLID, //Hyperlink to retrieve
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
);
Updates the hyperlink frame.
This method is called before navigation, typically by the IHlinkSite::ReadyToNavigate method. An application that does not implement the IHlinkSite interface can call this method before calling the navigation function.
See also HlinkOnNavigate, HLID, IHlinkBrowseContext::OnNavigateHlink, IHlinkSite::OnNavigationComplete
The IHlinkSite interface provides methods for a hyperlink to retrieve the moniker or the interface on its hyperlink container. The navigation process that resolves a hyperlink uses this information to efficiently handle internal (within the same container) and external (to a different container) hyperlink references.
Implement IHlinkSite when you want to hyperlink to other documents. For each hyperlink object provided by the system, a third party, or that you create, you provide an IHlinkSite object. One site object can support multiple hyperlinks.
| IHlinkSite methods | Description |
| QueryService | Queries any service or other interface from the hyperlink site object. |
| GetMoniker | Retrieves the moniker to the hyperlink target. |
| ReadyToNavigate | Notifies the hyperlink site that the hyperlink navigation is about to occur. |
| OnNavigationComplete | Notifies the hyperlink site that hyperlink navigation is complete. |
HRESULT GetMoniker(
DWORD dwSiteData, //Site data for the new hyperlink object
DWORD dwAssign, //Whether or not to create a moniker if one not found
DWORD dwWhich, //Which moniker to retrieve
IMoniker * ppimk //Buffer to receive the requested moniker interface pointer
);
Returns the relative moniker of the hyperlink's container.
See also IHlink::GetMonikerReference, IHlinkTarget::GetMoniker
HRESULT OnNavigationComplete(
DWORD dwSiteData, //Site data for the hyperlink object
DWORD dwReserved, //Reserved for future use
HRESULT hrError, //Result of the hyperlink navigation
LPCWSTR pwzError //Description of the failure, if any
);
Notifies the hyperlink site that a hyperlink navigation has been successful.
This notification is particularly useful if the hyperlink has been navigated asynchronously, because it is the only notification the hyperlink receives to realize that hyperlinking has completed.
See also HlinkOnNavigate, IHlinkBrowseContext::OnNavigateHlink, IHlinkFrame::OnNavigate
HRESULT QueryService(
DWORD dwSiteData, //Site data to identify the hyperlink its site
REFGUID guidService, //TBD
REFIID riid, //Location to return the riid interface
IUnknown* ppiunk //Location to receive the unknown interface pointer of service query
);
Allows querying of any service or other interface from the hyperlink site object. This is similar to IServiceProvider::QueryService.
See also IHlinkSite::GetMoniker
HRESULT ReadyToNavigate(
DWORD dwSiteData, //Site data for the hyperlink object
DWORD dwReserved //Reserved for future use
);
Notifies the hyperlink site that the hyperlink navigation is about to occur. To back out of the operation, return E_ABORT.
See also HlinkOnNavigate, IHlinkBrowseContext::OnNavigateHlink, IHlinkFrame::OnNavigate
A hyperlink target implements the IHlinkTarget interface and gives out hyperlink references to its contents.
Implement this interface when you have an application that can be the target for a hyperlink. In other words, hyperlinks from other applications use this interface to determine how to find, display, and navigate to your target.
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.
Note that an Active Document object need not implement this interface if hyperlink navigation is only occuring within a document object container such as Microsoft Internet Explorer. In such a situation, IHlinkTarget provides the capability to navigate to a location within the document, but it is not necessary for navigation to be completed.
You do not normally call these methods directly. When an end user selects a hyperlink through an application's user interface, the implementation of IHlink::Navigate calls these methods to determine how to display, locate, and navigate to the target.
| IHlinkTarget methods | Description |
| SetBrowseContext | Establishes the current browse context for this hyperlink target. |
| GetBrowseContext | Retrieves the current browse context within which this hyperlink target is currently running. |
| Navigate | If the given location is not visible, navigates to and shows that position within the target. |
| GetMoniker | Returns a moniker to the hyperlink target object. |
| GetFriendlyName | Returns a friendly name for the given hyperlink location within this target. |
HRESULT GetBrowseContext(
IHlinkBrowseContext * ppihlbc //Buffer to receive the current browse context's interface pointer
);
Retrieves the browse context in which this hyperlink target is currently running.
See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::GetBrowseContext, IHlinkTarget::SetBrowseContext
HRESULT GetFriendlyName(
LPCWSTR pwzLocation, //Hyperlink location within this target
LPWSTR * ppwzFriendlyName //Buffer to receive the friendly name
);
Retrieves a friendly name for the given hyperlink destination within this target.
See also IHlink::GetFriendlyName
HRESULT GetMoniker(
LPCWSTR pwzLocation, //Hyperlink destination within this target
DWORD dwAssign, //Whether or not to create a moniker if one not found
IMoniker * ppimkLocation //Buffer to receive this moniker
);
Returns a moniker to the hyperlink target object for the given hyperlink destination szLocation.
| S_OK | The moniker to the hyperlink target object was retrieved. |
| E_FAIL | A moniker does not exist for this hyperlink target, and OLEGETMONIKER_ONLYIFTHERE was specified for dwAssign. |
| CreateFileMoniker, MkParseDisplayName, and other moniker creation API errors |
See also HlinkSimpleNavigateToMoniker, IHlink::GetMonikerReference, IHlinkSite::GetMoniker
HRESULT Navigate(
DWORD grfHLNF, //Value from the HLNF enumeration
LPCWSTR * pwzJumpLocation //Location within the hyperlink target to navigate to
);
If the given location is not visible, navigates to and shows the location position within the object/document.
See also HlinkNavigate, HlinkNavigateToStringReference, HLNF, IHlinkFrame::Navigate, IHlink::Navigate
HRESULT SetBrowseContext(
IHlinkBrowseContext * pihlbc //Browse context interface pointer to set for the hyperlink target
);
Establishes the current browse context for this hyperlink target.
See also HlinkCreateBrowseContext, IHlinkBrowseContext, IHlinkFrame::SetBrowseContext, IHlinkTarget::GetBrowseContext
This section describes the following functions:
HRESULT HlinkCreateBrowseContext(
IUnknown *piunkOuter, //Controlling unknown for possible aggregation
REFIID riid, //Interface identifier to return on the new browse context
void **ppvObj //Receives the requested interface's pointer
);
Creates an empty, default instance of the system browse context object.
This helper function is identical to calling the following:
coCreateInstance(CLSID_StdHlinkBrowseContext, punkOuter, CLSCTX_SERVER, riid, ppv)
See also IHlinkBrowseContext, IHlinkFrame::GetBrowseContext, IHlinkTarget::GetBrowseContext
HRESULT HlinkCreateFromData(
IDataObject* piDataObj, //Interface on target data from which to create the hyperlink
IHlinkSite* pihlsite, //Interface on hyperlink site
DWORD dwSiteData, //Additional site data
IUnknown *piunkOuter, //Interface that controls aggregation
REFIID riid, //Interface identifier on new hyperlink object
Void ** ppvObj //Receives the requested interface's pointer
);
Creates a standard hyperlink object from a COM object that supports the IDataObject interface.
Typically, this object originates from a data transfer operation, such as copying to and pasting from the clipboard, or through a drag-and-drop operation.
HlinkCreateFromData is one of three helper functions that you can use to create a hyperlink. HlinkCreateFromData creates a hyperlink from a COM object that supports both the IDataObject interface and a hyperlink format CF_HYPERLINK on that IDataObject interface. HlinkQueryCreateFromData is typically called before the call to HlinkCreateFromData to determine if both these conditions are met. To create a hyperlink from a COM object for which you know the moniker, use HlinkCreateFromMoniker. To create a hyperlink from a COM object for which you have the name but not the moniker, use HlinkCreateFromString.
HlinkCreateFromData is typically used by a hyperlink container as part of a user interface that creates new hyperlinks through the clipboard or a drag-and-drop operation.
See also HlinkCreateFromMoniker, HlinkCreateFromString, HlinkQueryCreateFromData
HRESULT HlinkCreateFromMoniker(
IMoniker * pimkTrgt, //Interface on hyperlink target moniker
LPCWSTR pwzLocation, //Named location of hyperlink reference within target
LPCWSTR pwzFriendlyName, //Display name of hyperlink
IHlinkSite * pihlsite, //Interface on hyperlink site
DWORD dwSiteData, //Additional site data
IUnknown * piunkOuter, //Whether or not object is part of an aggregate
REFIID riid, //Interface identifier on new hyperlink object
Void * ppvObj //Receives the requested interface's pointer
);
Creates a new system hyperlink object from a moniker, a location string, and a friendly name string (used for displaying the hyperlink).
HlinkCreateFromMoniker is one of three helper functions that you can use to create a hyperlink. HlinkCreateFromData creates a hyperlink from a COM object that supports both the IDataObject interface and a hyperlink format CF_HYPERLINK on that IDataObject interface. HlinkQueryCreateFromData is typically called before the call to HlinkCreateFromData to determine if both these conditions are met. To create a hyperlink from a COM object for which you know the moniker, use HlinkCreateFromMoniker. To create a hyperlink from a COM object for which you have the name but not the moniker, use HlinkCreateFromString.
HlinkCreateFromMoniker creates new hyperlinks from an existing target moniker, a location string within the target, and a friendly name string used to identify how to display the hyperlink. This method's typical use is as part of a user interface for creating new hyperlinks from existing hyperlinks, or for editing existing hyperlinks, using a dialog box or form to prompt for the strings. This function is significantly faster than HlinkCreateFromString.
See also HlinkCreateFromData, HlinkCreateFromString, HlinkQueryCreateFromData
HRESULT HlinkCreateFromString(
LPCWSTR pwzTarget, //String helping to identify the hyperlink target
LPCWSTR pwzLocation, //Location within the hyperlink target of new hyperlink object
LPCWSTR pwzFriendlyName, //Friendly name of the hyperlink
IHlinkSite * pihlsite, //Site for the new hyperlink object
DWORD dwSiteData, //Additional site data for the new hyperlink object
IUnknown * piunkOuter, //Whether or not object is part of an aggregate
REFIID riid, //Interface identifier on new browse context object
Void * ppvObj //Location of the requested interface's pointer
);
Creates a new hyperlink object from strings representing the hyperlink target, the location within the target, and a friendly name.
HlinkCreateFromString is one of three helper functions that you can use to create a hyperlink. HlinkCreateFromData creates a hyperlink from a COM object that supports both the IDataObject interface and a hyperlink format CF_HYPERLINK on that IDataObject interface. HlinkQueryCreateFromData is typically called before the call to HlinkCreateFromData to determine if both these conditions are met.
To create a hyperlink from a COM object for which you know the moniker, use HlinkCreateFromMoniker. To create a hyperlink from a COM object for which you have the name but not the moniker, use HlinkCreateFromString.
HlinkCreateFromString is typically used by hyperlink containers as part of the user interface for creating brand new hyperlinks, where the user fills in a form or dialog box of itemstarget, location, friendly namethat are used to construct the hyperlink.
See also HlinkCreateFromData, HlinkCreateFromMoniker, HlinkQueryCreateFromData
HRESULT HlinkGetSpecialReference(
ULONG uReference, //Special reference flags
LPWSTR * ppwzReference //Buffer to return special reference string
);
For a given value from the HLSR enumeration, this function returns the current user's default global home, search, or history page for browsing as a string.
See also HlinkSetSpecialReference, HLSR
HRESULT HlinkGoBack(
IUnknown *pUnk //IUnknown pointer to the initiating document or object
);
Executes a hyperlink jump backward within the navigation stack.
The HlinkGoBack helper function should be used by all applications, documents, and objects that have simple navigational 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.
The specified pointer pUnk must point to an object that is hosted within a hyperlink-aware container, such as Microsoft Internet Explorer or an ActiveX hyperlink frame.
Note that this function will work only if the object calling the function is the current object in the navigation stack. In HTML pages with frame sets, HlinkGoBack only affects the current frame.
See also HlinkGoForward
HRESULT HlinkGoForward(
IUnknown *pUnk //IUnknown pointer to the initiating document or object
);
Executes a hyperlink jump forward within the navigation stack.
The HlinkGoForward helper function should be used by all applications, documents, and objects that have simple navigational 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.
The specified pointer pUnk must point to an object that is hosted within a hyperlink-aware container, such as Microsoft Internet Explorer or an ActiveX hyperlink frame.
Note that this function will work only if the object calling the function is the current object in the navigation stack. In HTML pages with frame sets, HlinkGoForward only affects the current frame.
See also HlinkGoBack
HRESULT HlinkNavigate(
IHlink * pihl, //The target hyperlink
IHlinkFrame * pihlframe, //The hyperlink frame of the hyperlink container
DWORD grfHLNF, //Navigation flags
LPBC pbc, //Bind context object interface pointer
IBindStatusCallback * pibsc, //Bind status callback object interface pointer
IHlinkBrowseContext * pihlbc //Browse context object interface pointer
);
Navigates to a hyperlink, given a hyperlink object and an optional hyperlink frame object.
HlinkNavigate encapsulates the following common sequence of calls:
if (phlFrame)
phlFrame->Navigate(grfHLNF, pbc, pbsc, phl);
else if (phl)
phl->Navigate(grfHLNF, pbc, pbsc, phlbc);
See also IHlinkBrowseContext, IHlink::Navigate, IHlinkFrame::Navigate, IHlinkTarget::Navigate
HRESULT HlinkNavigateMoniker(
IUnknown * pUnk, //IUnknown pointer to the initiating document or object
IMoniker * pmkTarget //Moniker of the hyperlink target
);
Executes a hyperlink jump to a new document or object (specified in pmkTarget).
This function can also return any value returned by IHlink::Navigate.
HlinkNavigateMoniker is implemented as a simple macro that calls the HlinkSimpleNavigateToMoniker function, passing it NULL for most parameters.
The HlinkNavigateMoniker 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, HlinkNavigateString, HlinkNavigateToStringReference, HlinkSimpleNavigateToMoniker, IHlink::Navigate
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.