Microsoft has decided to open itself to the Internet/intranet world and has oriented its whole strategy around this key idea. Thus, it is already getting its products ready to fully integrate the Internet philosophy:
So far, what does this give you: An Internet-oriented environment where you can display and edit any OLE Document Object stored anywhere on the local hard disk or on the Internet. In Microsoft's vision, DocObject replaces HTML as the standard Web document format. HTML pages are now considered as standard DocObjects (whose server is the Internet Explorer). The next step is to enable every DocObject to provide the functionality that is the base technology of HTML and is responsible for the Web's success: hyperlinking.
A hyperlink is a reference to another location (it can be a document, a file, or whatever else) generally represented in an HTML page by colored, underlined text. The user can access this reference by simply clicking on the text. A hyperlink enables you to jump from a document to another through a simple click. Though it was greatly popularized by the World Wide Web, hyperlinking has been used for a long time (for example, in Windows online help).
OLE Hyperlinks enable DocObjects or ActiveX controls to fully support hyperlinking. As a result, an OLE Hyperlinks-compliant document can contain hyperlinks to other existing documents, objects, and applications. This technology also enables a document to use Web browser features.
Before going any further, you may want to review the definition of a few key terms, along with an example:
In order to make everything clear, take a look at the concrete example shown in Figure 19.1.
Figure 19.1. A hyperlink frame (Internet Explorer) displaying a hyperlink container (the HTML page).
In Figure 19.1, the hyperlink frame (Internet Explorer 3.0) contains a hyperlink container (the HTML page whose Internet address is http://www.mcp.com/sams/samspub/e-book/30874-6/index.htm, as shown in the Address combo box). This page contains several hyperlinks (represented as the underlined blue or red sentences). These hyperlinks are composed of a friendly name (for example, "Topic Quick Reference") and of a hyperlink reference (the relative reference vcuif.htm#l3, as shown in the bottom of the Internet Explorer window). These references point to the hyperlink target (the HTML page whose address is http://www.mcp.com/sams/samspub/e-book/30874-6/vcuif.htm). The location within the target is symbolized by #l3 and points to a hyperlink target's bookmark.
The Internet Explorer also manages a navigation stack, which is the list of all the previously displayed HTML pages (the friendly names of the stack's elements are represented in the Go menu bar, as shown in Figure 19.2). This navigation stack is managed by the browse context (some Internet Explorer code and data devoted to this task), thus enabling the user to use buttons such as Back or Forward.
Figure 19.2. After the jump, the navigation stack has been updated accordingly, as the menu shows (numbers 1 to 4).
The hyperlink navigation performed between Figure 19.1 and 19.2 is a fully integrated one. Indeed, the navigation stack is updated after the jump, as shown in Figure 19.2.
Of course, hyperlinking implementation may not seem to be a big deal. After all, OLE Hyperlink API provides only the hyperlink jump itself; the programmer still has to determine when to launch it (depending on user-created events).
But OLE Hyperlinking first of all allows an easy implementation. Indeed, using the Simple Hyperlink Navigation API, the programmer implements a hyperlink jump with just one function call. Furthermore, using the full Hyperlink Navigation API, the programmer can implement a hyperlink navigation that is fully integrated within an OLE hyperlink-compliant Web browser. That is, when the programmer's OLE hyperlinking-compliant document "jumps" to another document within a hyperlink frame, the jump is notified to the frame's browse context (if any). This means that the navigation stack is updated accordingly, and that the previous document can still be retrieved by using the browser's Go Back command. A hyperlink container can behave like an HTML page. Its URL (Uniform Resource Locator) will be added automatically in the navigation stack.
Furthermore, a hyperlink container can control the hyperlink frame's browse context. It can have access to commands like Go Back or Go Forward, and even to the entire navigation stack (either for visualization purposes or for modifying one).
For example, take a regular HTML page containing a link to a DocObject. In order to go back to the main page, this DocObject can use the browser's Go Back command rather than displaying a hyperlink pointing to the main page. This avoids adding extra copies of the same hyperlink reference in the navigation stack. If such a feature isn't a big deal for an HTML page because browser-widespread scripting languages such as Visual Basic Script or JavaScript provide functions for these types of tasks, OLE Hyperlinking is the only way for a DocObject to access these Web browser's commands (indeed, a DocObject can't call Visual Basic Script or JavaScript code). Furthermore, an ActiveX control may want to directly implement such a feature instead of calling some external script code.
But OLE Hyperlinking provides more functionality than just using the browser's popular commands. Indeed, it provides access to the browser's navigation stack. For example, a DocObject (or an ActiveX control enhanced HTML page) can retrieve the navigation stack, filter its elements that comply to a given set of specifications, and show them to the user. When the user chooses a given hyperlink, the DocObject just sends it to the Web browser (actually, it only sends the hyperlink position within the navigation stack). The browse context will just move the current hyperlink pointer in the stack, without having to reload the referenced hyperlink target.
OLE Hyperlinks come with two APIs: the Hyperlinks Navigation API and the Simple Hyperlink Navigation API. Both have their advantages and their drawbacks and are used for different purposes.
The Simple Hyperlink Navigation API is a reduced set of the full Hyperlink Navigation API and allows basic hyperlinking programming on the hyperlink container side (there is no such thing as simple hyperlinking on the hyperlink frame side). This API is the minimum requirement a DocObject or ActiveX control needs to implement OLE hyperlinking. Even people who are interested in the full Hyperlink Navigation API should first have a look at this API. The advantages of this API are:
The Simple Hyperlink Navigation API consist of six global functions:
HlinkSimpleNavigateToString() HlinkSimpleNavigateToMoniker() HlinkNavigateString() HlinkNavigateMoniker() HlinkGoBack() HlinkGoForward()
It also includes an enumeration:
typedef enum tagHLNF { HLNF_INTERNALJUMP, HLNF_OPENINNEWWINDOW } HLNF;
Because this API is simple, an example is given after each function description. All the examples assume that they are executed within an OLE Document Object (or DocObject). In order to better understand the code, first review some of the argument types that may be required:
This function performs a hyperlink jump. The hyperlink target is determined by a Unicode string.
HRESULT HlinkSimpleNavigateToString(LPCWSTR, LPCWSTR, LPCWSTR, IUnknown*, IBindCtx*, IBindStatusCallBack*, DWORD, DWORD);Argument Type Description LPCWSTR Hyperlink target. A NULL value means the navigation is an internal jump. LPCWSTR Location within the hyperlink target (optional, maybe NULL). LPCWSTR Frame within the hyperlink target (optional, maybe NULL). IUnknown* The IUnknown pointer to the document that is initiating the hyperlink. A NULL value means the hyperlink was initiated from a non-OLE-compliant application. IBindCtx* The bind context that will be used for any moniker binding during this navigation. IBindStatusCallback* The bind status callback that will be used for any asynchronous moniker binding during this navigation. A NULL value means that the hyperlink initiator isn't interested in having information such as status or navigation progress. DWORD HLNF enumeration values. DWORD Reserved for a future use. Must be zero.
HRESULT hr; WCHAR text[21]; MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, "D:\\download\\nt40.htm", 21, text, 21); hr = HlinkSimpleNavigateToString(text, NULL, NULL, (IUnknown*)&m_xOleDocument, NULL, NULL, 0, 0);
This function performs a hyperlink jump. Contrary to HlinkSimpleNavigateToString(), the hyperlink target is not set by a text string but by a moniker.
HRESULT HlinkSimpleNavigateToMoniker(IMoniker*, LPCWSTR, LPCWSTR, IUnknown*, IBindCtx*, IBindStatusCallBack*, DWORD, DWORD);Argument Type Description IMoniker* Hyperlink target. A NULL value means the navigation is within a document. LPCWSTR Location within the hyperlink target (optional, maybe NULL). LPCWSTR Frame within the hyperlink target (optional, maybe NULL). IUnknown* The IUnknown pointer to the document that is initiating the hyperlink. A NULL value means the hyperlink was initiated from a non-OLE-compliant application. IBindCtx* The bind context that will be used for any moniker binding during this navigation. IBindStatusCallback* The bind status callback that will be used for any asynchronous moniker binding during this navigation. A NULL value means that the hyperlink initiator isn't interested in having information such as status or navigation progress. DWORD HLNF enumeration values. DWORD Reserved for a future use. Must be zero.
HRESULT hr; hr = HlinkSimpleNavigateToMoniker(moniker, NULL, NULL, (IUnknown*)&m_xOleDocument, NULL, NULL, 0, 0);
This function is actually a macro that expands itself into a HlinkSimpleNavigateToString() call where most arguments are NULL.
HRESULT HlinkNavigateString(IUnknown*, LPCWSTR);Argument Type Description IUnknown* The IUnknown pointer to the document that is initiating the hyperlink. A NULL value means the hyperlink was initiated from a non-OLE-compliant application. LPCWSTR Hyperlink target.
HRESULT hr; WCHAR text[21]; MultiByteToWideChar(CP_ACP, MB_PRECOMPOSED, "D:\\download\\nt40.htm", 21, text, 21); hr = HlinkNavigateString((IUnknown*)&m_xOleDocument, text);
This function is actually a macro that expands itself into a HlinkSimpleNavigateToMoniker() call where most arguments are NULL.
HRESULT HlinkNavigateMoniker(IUnknown*, IMoniker*);Argument Type Description IUnknown* The IUnknown pointer to the document that is initiating the hyperlink. A NULL value means the hyperlink was initiated from a non-OLE-compliant application. IMoniker* Hyperlink target.
HRESULT hr; hr = HlinkNavigateString((IUnknown*)&m_xOleDocument, moniker);
This function asks the hyperlink frame (that is, the Web browser) to jump backward in the navigation stack. Here, the only argument that points to the document or object initiating the hyperlink jump cannot be NULL. Furthermore, this function will only work if this same document or object is contained in an OLE hyperlink-compliant container, such as Internet Explorer 3.0.
HRESULT HlinkGoBack(IUnknown*);Argument Type Description IUnknown* Pointer to the document or object initiating the hyperlink jump.
HRESULT hr; hr = HlinkGoBack((IUnknown*)&m_xOleDocument);
This function asks the hyperlink frame (that is, the Web browser) to jump forward in the navigation stack. Here, the only argument that points to the document or object initiating the hyperlink jump cannot be NULL. Furthermore, this function will only work if this same document or object is contained in an OLE hyperlink-compliant container, such as Internet Explorer 3.0.
HRESULT HlinkGoBack(IUnknown*);Argument Type Description IUnknown* Pointer to the document or object initiating the hyperlink jump.
HRESULT hr; hr = HlinkGoForward((IUnknown*)&m_xOleDocument);
The Hyperlink Navigation API allows much more possibilities than the Simple Hyperlink Navigation API. It is composed of several global functions, enumerations, structures and interfaces. As a result, the HLINK.H file (the hyperlink API include file) from the ActiveX SDK is different from the file provided with Visual C++ 4.1. This means a given program may not compile when the HLINK.H is changed (for example, when the Visual C++ HLINK.H file is replaced by ActiveX SDK's), even if the changes are only minor. You can even expect this file to change during the next Visual C++ releases.
This API is still in flux and can be modified by Microsoft at any time. Microsoft strongly encourages programmers to use only the simple hyperlink navigation API.
In order to implement the Hyperlink Navigation API, the programmer first needs to understand which are OLE Hyperlink components and how they interact with each other. OLE Hyperlink is composed of two types of programs: the hyperlink frame program and the hyperlink container program. Typically, the hyperlink frame program is a DocObject client and the hyperlink container program is a DocObject server (beware not to mix between a Hyperlink container and a DocObject container). Thus, the frame program can display not only its own native format but also multiple hyperlink container formats.
This program manages an outer frame that contains and shows hyperlink container. It is called through its IHlinkTarget interface, which must be supported by the class derived from COleClientItem.
This program also contains the hyperlink browse context. This component manages the navigation stack: it notes every hyperlink jump and stores all the containers' references into the stack. It can also allow the user to look at the stack and go to specific hyperlink references within it. The browse context is controlled through its unique IHlinkBrowseContext interface, which must be supported by the class implementing it. This class is typically created for this sole purpose and has its interface pointer given away through the hyperlink frame.
This program manages the hyperlink document being displayed. It can manage either a hyperlink container (that is, a document being displayed) or a hyperlink target (that is, a document pointed at by a hyperlink). For example, the hyperlink container program corresponding to HTML pages is the OLE server part of the Internet Explorer.
This program doesn't always need to implement interfaces. Indeed, it is controlled through the standard OLE and DocObject interfaces. However, if the program wants its documents to be included in the navigation stack by the browse context after a hyperlink jump, it must implement the IHlinkTarget interface.
The hyperlink target can also support the IPersistMoniker interface rather than IPersistFile. Thus, the target can support asynchronous download as a persistence mechanism.
The hyperlink container, as it name implies, contains some hyperlinks and hyperlink sites. A hyperlink site is used by the hyperlink to get the container moniker. Thus, the hyperlink can notice an internal jump by comparing the target moniker to the container moniker and perform the necessary optimizations.
Hyperlinks manage the reference to a document (or more generally any kind of application/document/file). A hyperlink is composed of the hyperlink target (stored as a moniker) and the location within this target (stored as a string). The graphical representation of the hyperlink (such as its friendly name) is up to the container itself. A hyperlink is controlled through its IHlink interface.
This section examines how OLE hyperlink works when a hyperlink navigation occurs. Both simple hyperlink navigation and fully integrated hyperlink navigation will be detailed. Both types of navigation are mainly the same; the last type of navigation just performs some extra work in order to have the browse context integrate the hyperlink references that are navigated to. The diagram below describes the major steps of hyperlink navigation. The numbers indicate the order with which the steps are executed over time and are common to both types of navigation.
As you can see, the hyperlink container calls the hyperlink frame, sending it the desired hyperlink reference interface. The frame then calls the hyperlink reference, which calls the hyperlink target. Then, the target notifies the frame that the navigation successfully performed. This notification is useful for asynchronous navigation, where it is the only way for the frame to know when the navigation is over.
This section describes how the different components interact when a simple hyperlink jump occurs. Of course, only the global function call must be implemented (provided the hyperlink frame already exists). In this example, neither the hyperlink container nor the hyperlink target use (or even know the presence of) the frame's browse context..
This kind of navigation allows the integration of navigated hyperlinks within the browse context. All tasks described in the previous section are supposed to be performed here too.
The interfaces of the Hyperlink Navigation API often use enumerations and/or structures either as input or output arguments. Some of the following enumerations can take several values; some can only take a single value.
These values give some information about a hyperlink navigation.
Name Description
HLNF_INTERNALJUMP Indicates the navigation is an internal jump. This value allows some internal jump-specific optimization, like avoiding to reload the document. The system will have the hyperlink automatically send this value to IHlink::Navigate() if the moniker is NULL.
HLNF_NAVIGATINGBACK Indicates the navigation occurs because the Go Back command was selected. The position in the navigation stack should be moved back one element, without altering the stack. The hyperlink frame and hyperlink container send this value to IHlink::Navigate().
HLNF_NAVIGATINGFORWARD Indicates the navigation occurs because the Go Forward command was selected. The position in the navigation stack should be moved forward one element, without altering the stack. The hyperlink frame and hyperlink container send this value to IHlink::Navigate().
HLNF_USERBROWSECONTEXTCLONE When IHlink::Navigate() is passed this value, it should clone the browse context passed-in argument by calling IHlinkBrowseContext::Clone(). This new browse context will always be used during the rest of the hyperlink navigation.
HLNF_OFFSETWINDOWORG When IHlinkTarget::Navigate() is passed this value, it should alter its window position according to the information contained by the HLBWINFO returned by IHlinkBrowseContext::GetBrowseContextWindowContext(). This value is generally used with the HLNF_USERBROWSECONTEXTCLONE value to implement the Open in new window command.
HLNF_OPENINNEWWINDOW Using this value is like using both HLNF_USERBROWSECONTEXTCLONE and HLNF_OFFSETWINDOWORG values.
HLNF_CREATENOHISTORY When IHlinkBrowseContext::OnNavigateHlink() is passed this value, it should not add the hyperlink to the navigation stack.
HLNF_NAVIGATINGTOSTACKITEM Same as HLNF_CREATENOHISTORY. Furthermore, IHlinkBrowseContext::OnNavigateHlink() should set the passed hyperlink as the browse context's current hyperlink. This value is used when the user decides to jump to a hyperlink from the navigation stack: though the navigation occurs, the navigation stack should not be altered, only the position on the stack.
A single value from this enumeration is used by the IHlinkSite::GetMoniker() interface member function to know whether it must return a moniker for the container or a base moniker specific to the site.
Name Description
HLINKWHICHMK_CONTAINER Return the moniker for the hyperlink container corresponding to a particular hyperlink site.
HLINKWHICHMK_BASE Return the base moniker corresponding to a particular hyperlink site.
A single value from this enumeration is used by the IHlink::GetMonikerReference() and IHlink::GetStringReference() interface functions to know if they must return the absolute or relative reference for the hyperlink target.
Name Description
HLINKGETREF_DEFAULT Return the default reference for hyperlink target.
HLINKGETREF_ABSOLUTE Return the absolute reference for hyperlink target.
HLINKGETREF_RELATIVE Return the relative reference for hyperlink target.
A single value from this enumeration is used by IHlink::GetFriendName() to know which type of friendly name to return.
Name Description
HLFNAMEF_TRYCACHE Returns the friendly name that is cached on the Hlink interface object.
HLFNAMEF_TRYFULLTARGET Returns the full display name of the hyperlink target.
HLFNAMEF_TRYPRETTYTARGET Returns a beautiful version of the full display name of the hyperlink target.
HLFNAMEF_TRYWIN95SHORTCUT Returns the version of the full display name of the hyperlink target without any path or extension.
HLFNAMEF_DEFAULT Returns the cached friendly name.
A single value of this enumeration is returned by IHlink::GetMiscStatus() to tell whether a hyperlink is relative or absolute.
Name Description
HLINKMISC_ABSOLUTE The hyperlink contains an absolute reference to the hyperlink target.
HLINKMISC_RELATIVE The hyperlink contains a relative reference to the hyperlink target.
This structure is used by the IEnumHLITEM interface, which belongs to enumerators returned by IHlinkBrowseContext::EnumNavigationStack().
Name Type Description
uHLID ULONG The hyperlink ID.
szFriendlyName LPWSTR The friendly name of the hyperlink.
Values from this enumeration are passed in an HLBWINFO structure, which is associated with each browse context. The HLIBWINFO structure is accessed by calling IHlinkBrowseContext::GetBrowseWindowContext() and IHlinkBrowseContext::SetBrowseWindowContext().
Name Description
HLBWIF_HASFRAMEWNDINFO The browse context has available frame-level window positioning information.
HLBWIF_HASDOCWNDINFO The browse context has available document-level window positioning information.
HLBWIF_FRAMEWNDMAXIMIZED The browse context's frame-level windows should appear maximized. Always used with HLBWIF_HASFRAMEWNDINFO.
HLBWIF_DOCWNDMAXIMIZED The browse context's document-level windows should appear maximized. Always used with HLBWIF_HASDOCWNDINFO.
This structure contains information about the locations and sizes of frame-level and document-level windows within a browse context. This structure is returned from the browse context by calling IHlinkBrowseContext::GetBrowseWindowContext() and sending to the browse context by calling IHlinkBrowseContext::SetBrowseWindowContext(). This structure is used by a hyperlink target during IHlinkTarget::Navigate() so that it can reposition its user interface.
Name Type Description
cbSize ULONG Size of the structure in bytes.
grfHLBWIF DWORD HLBWIF enumeration values.
rcFramePos RECTL If grfHLBWIF has the FLBWIF_HASFRAMEWNDINFO value, this variable contains the rectangle in screen coordinates of current frame-level windows within the browse context. If grfHLBWIF has the FLBWIF_FRAMEWNDMAXIMIZED value, this means the frame-level windows are currently maximized, and rcFramePos represents the non-maximized size of the document-level windows.
rcDocPos RECTL If grfHLBWIF has the FLBWIF_HASDOCWNDINFO value, this contains the rectangle in screen coordinates of current document-level windows within the browse context. If grfHLBWIF has the FLBWIF_DOCWNDMAXIMIZED value, this means the document-level windows are currently maximized, and rcFramePos represents the non-maximized size of the document-level windows.
Some specific hyperlinks are identified by an HLID constant rather by a IHlink interface pointer. Thus, the hyperlink frame can perform specific optimization.
Name Description
HLID_PREVIOUS Indicates the hyperlink before the current one in the navigation stack. If such a hyperlink does not exist (either the current hyperlink is the first one in the navigation stack or the stack is empty), methods like IHlinkBrowseContext::GetHlink() return NULL and E_FAIL.
HLID_NEXT Indicates the hyperlink past the current one in the navigation stack. If such a hyperlink does not exist (either the current hyperlink is the last one in the navigation stack or the stack is empty), methods like IHlinkBrowseContext::GetHlink() return NULL and E_FAIL.
HLID_CURRENT Indicates the current hyperlink in the navigation stack. This value can be used when the hyperlink has to be physically navigated again. For example, a page can have to be reloaded (to implement a Reload command), a sound sample may have to be replayed, and so on.
HLID_STACKBOTTOM Indicates the first hyperlink of the navigation stack. If the stack is empty, methods like IHlinkBrowseContext::GetHlink() return NULL and E_FAIL.
HLID_STACKTOP Indicates the last hyperlink of the navigation stack. If the stack is empty, methods like IHlinkBrowseContext::GetHlink() return NULL and E_FAIL.
A single value of this enumeration is used by IHlinkBrowseContext::QueryHlink() to know which kind of hyperlink test it must perform.
Name Description
HLQF_ISVALID Indicates to test the validity of a particular hyperlink.
HLQF_ISCURRENT Indicates to test if a particular hyperlink is the browse context's current hyperlink.
A single value from this enumeration is used by the HlinkGetSpecialReference() or HlinkSetSpecialReference() global functions to know which value to set or get.
Name Description
HLSR_HOME Hyperlink reference to the user's home page.
HLSR_SEARCHPAGE Hyperlink reference to the user's search page.
HLSR_HISTORYFOLDER Hyperlink reference to the user's history folder page.
This format consists of a serialized hyperlink. When used with IDataObject, this format is passed under TYMED_ISTREAM or TYMED_HGLOBAL mediums. The OleSaveToStreamEx() function stores a hyperlink into an IStream, provided the hyperlink supports the OLE IPersistStream interface.
The full Hyperlink Navigation API provides a set of global functions. This allows the creation of a hyperlink from different types of data, and the initiation of a hyperlink navigation.
This function creates an empty browse context instance, whose interface is returned through the last argument.
HRESULT HlinkCreateBrowseContext(IUnknown*, REFIID, void**);Argument Type Description IUnknown* IUnknown interface of the object controlling the new browse context. A NULL value (the most common) means the browse context isn't aggregated. REFIID Which type of browse context's interface to return, typically IID_IHlinkBrowseContext. void** Where to send the browse context REFIID interface.
This function determines if a hyperlink can be created from the IDataObject interface passed-in argument, that is, if:
Here, the result is returned by the function itself, and not through any argument.
HRESULT HlinkQueryCreateFromData(IDataObject*);Argument Type Description IDataObject* The source data interface.
This function creates a hyperlink from the IDataObject passed as the first argument. The created hyperlink is returned through the last argument.
This function can be called after a cut-and-paste operation from the clipboard, in which case the IDataObject interface is retrieved by calling OleGetClipboard(). It can be also called after a drag-and-drop operation, in which case the IDataObject interface is retrieved by calling IDropTarget::Drop(), where the IDropTarget interface is the one registered to the target drag-and-drop window.
HRESULT HlinkCreateFromData(IDataObject*, IHlinkSite*, DWORD, IUnknown*, REFIID, void**);Argument Type Description IDataObject* Source data from which the hyperlink must be created. IHlinkSite* The hyperlink site associated to the new hyperlink. DWORD Additional hyperlink site data. IUnknown* IUnknown interface of the object controlling the new hyperlink. A NULL value (the most common) means the hyperlink object isn't aggregated. REFIID Which hyperlink interface must the function return, generally IID_IHlink. void** Where to send the hyperlink desired interface.
This function creates a hyperlink from a moniker whose IMoniker interface is passed as the first argument. The created hyperlink is returned through the last argument. This function is faster than HlinkCreateFromString() if the moniker is already defined.
It is generally called when the program wants to create a hyperlink from an already existing hyperlink. It can retrieve the already existing hyperlink's moniker's interface and target location through Hlink::GetMonikerReference() and its friendly name through GetFriendlyName().
HRESULT HlinkCreateFromMoniker(IMoniker*, LPCWSTR, LPCWSTR, IHlinkSite*, DWORD, IUnknown*, REFIID, void**);Argument Type Description IMoniker* The interface of the moniker from which the hyperlink must be created. LPCWSTR Location of the new hyperlink within the hyperlink target. May not be NULL. LPCWSTR The new hyperlink friendly name. IHlinkSite* The hyperlink site to be associated to the hyperlink. DWORD Additional hyperlink site data. IUnknown* IUnknown interface of the object controlling the new hyperlink. A NULL value (the most common) means the hyperlink object isn't aggregated. REFIID The hyperlink's interface to be returned, generally IID_IHlink. void** Where to return the desired hyperlink interface.
This function creates a hyperlink from strings representing the hyperlink target, the location within this target, and the friendly name. The created hyperlink is returned through the last argument. This function is slower than HlinkCreateFromMoniker() as it must parse the text strings and create a moniker. The HlinkCreateFromMoniker() function should be called if the hyperlink target's moniker already exists.
HRESULT HlinkCreateFromString(LPCWSTR, LPCWSTR, LPCWSTR, IHlinkSite*, DWORD, IUnknown*, REFIID, void**);Argument Type Description LPCWSTR String describing the hyperlink target. LPCWSTR Location of the new hyperlink within the hyperlink target. May not be NULL. LPCWSTR The new hyperlink friendly name. IHlinkSite* The hyperlink site to be associated to the hyperlink. DWORD Additional hyperlink site data. IUnknown* IUnknown interface of the object controlling the new hyperlink. A NULL value (the most common) means the hyperlink object isn't aggregated. REFIID The hyperlink's interface to be returned, generally IID_IHlink.
This function retrieves the current user's global home, search, or history page as a string. The result is returned through the second argument, and it can be turned into a hyperlink by calling the HlinkCreateFromString() global function.
HRESULT HlinkGetSpecialReference(DWORD, LPCWSTR*);Argument Type Description DWORD A HLSR enumeration value. Determines if the function must return the home page, search page, or history page. LPWSTR* Where to send the required page as a string.
This function sets the current user's global home, search, or history page as a string.
HRESULT HlinkSetSpecialReference(DWORD, LPCWSTR);Argument Type Description DWORD A HLSR enumeration value. Determines if the function must set the home page, search page, or history page. LPCWSTR Where to send the required page as a string.
This function performs a hyperlink navigation by regrouping common function calls: It creates a hyperlink from a string by calling HlinkCreateFromString(), performs hyperlink navigation by calling HlinkNavigate(), and then releases the hyperlink by calling Hlink::Release().
HRESULT HlinkNavigateToStringReference(LPCWSTR, LPCWSTR, IHlinkSite*, DWORD, IHlinkFrame*, DWORD, IBindCtx*, IBindStatusCallback* IHlinkBrowseContext*);Argument Type Description LPCWSTR String describing the hyperlink target. LPCWSTR Location within the hyperlink target. IHlinkSite* The hyperlink site to be associated to the hyperlink. DWORD Additional site data. IHlinkFrame* Hyperlink frame of the hyperlink container. A NULL value means the container doesn't have any frame. DWORD HLNF enumeration values. IBindCtx* The bind context to use for every moniker that will be created during the navigation. May not be NULL. IBindStatusCallback* The bind status callback to use for asynchronous moniker binding. A NULL value means the caller doesn't need to know information such as cancellation, progress state, and so on. IHlinkBrowseContext* The browse context to use for this navigation.
This function calls IHlinkFrame::Navigate() if it is passed a hyperlink frame as argument, and calls IHlink::Navigate() if it is only passed a hyperlink as argument.
HRESULT HlinkNavigate(IHlink*, IHlinkFrame*, DWORD, IBindCtx*, IBindStatusCallback*, IHlinkBrowseContext*);Argument Type Description IHlink* The hyperlink to navigate to. IHlinkFrame* The hyperlink frame of the hyperlink container. A NULL value means the hyperlink container doesn't have any frame. DWORD HLNF enumeration values. IBindCtx* The bind context to use for every moniker that will be created during the navigation. May not be NULL. IBindStatusCallback* The bind status callback to use for asynchronous moniker binding. A NULL value means the caller doesn't need to know information such as cancellation, progress state, and so forth. IHlinkBrowseContext* The browse context to use for this navigation.
This function encapsulates functions during IHlinkTarget::Navigate() execution. It calls IHlinkBrowserContext::OnNavigateHlink() and IHlinkFrame::OnNavigate() if the hyperlink target has a hyperlink frame.
HRESULT HlinkOnNavigate(IHlinkFrame*, IHlinkBrowseContext*, DWORD, IMoniker*, LPCWSTR, LPCWSTR);Argument Type Description IHlinkFrame* Hyperlink frame of the hyperlink container. A NULL value means the container doesn't have any frame. IHlinkBrowseContext* The browse context to use for this navigation. DWORD HLNF enumeration values. IMoniker* The hyperlink target's moniker. May not be NULL. LPCWSTR Location within the hyperlink target. LPCWSTR The friendly name of the hyperlink.
This interface is used by a hyperlink site and allows the site's associated hyperlink to retrieve information about the container.
BEGIN_INTERFACE_PART(HlinkSite, IHlinkSite) INIT_INTERFACE_PART(CMyDocObject, HlinkSite) STDMETHOD(GetMoniker)(DWORD, DWORD, DWORD, Moniker**); STDMETHOD(GetInterface)(DWORD, DWORD, REFIID, void**); STDMETHOD(OnNavigateComplete)(DWORD, HRESULT, LPCWSTR); END_INTERFACE_PART(HlinkSite)
This member function retrieves the moniker of the hyperlink site's container, which is returned through the last argument.
STDMETHOD(GetMoniker)(DWORD, DWORD, DWORD, Moniker**);Argument Type Description DWORD Hyperlink associated with the site. This value was given by IHlink::SetHlinkSite(). DWORD An OLEGETMONIKER enumeration value. An OLEGETMONIKER_ONLYIFTHERE value means the function must not create a moniker, even if it doesn't already exist. An OLEGETMONIKER_FORCEASSIGN value means the function should create a moniker if it doesn't already exist. DWORD An OLEWHICHMK enumeration value. An OLEWHICHMK_CONTAINER value means the hyperlink site must return the container's moniker. IMoniker** Where to send the container's moniker interface pointer.
This member function retrieves a hyperlink site's container interface, which is returned through the last argument.
If a hyperlink, while comparing the target's moniker to the container's moniker (returned by IHlinkSite::GetMoniker()), finds that the navigation is an internal jump, it retrieves the hyperlink target's IHlinkTarget interface by calling this function.
This function differs slightly from IUnknown::QueryInterface(). First, it may return an interface based on the hyperlink passed-in argument. Second, the returned interface may not belong to the hyperlink site.
STDMETHOD(GetInterface)(DWORD, DWORD, REFIID, void**);Argument Type Description DWORD Hyperlink associated with the site. This value was given by IHlink::SetHlinkSite(). DWORD Reserved for future use. Must be zero. REFIID The desired interface's IID. void** Where to send the container's desired interface pointer.
This member function is called whenever a hyperlink jump has been performed. This function can be useful when the jump is executed asynchronously, because it's the only way for the site to know when the navigation has completed.
STDMETHOD(OnNavigateComplete)(DWORD, HRESULT, LPCWSTR);Argument Type Description DWORD Hyperlink associated with the site. This value was given by Ihlink::SetHlinkSite(). HRESULT Result of the hyperlink navigation. Must be S_OK, E_ABORT or E_FAIL. LPCWSTR A text string describing, in case of a problem, the failure that occurred.
This interface is used by a hyperlink. It allows hyperlink-specific information management (that is, either retrieving or setting) such as its moniker, its hyperlink site, its friendly name, and so forth.
BEGIN_INTERFACE_PART(Hlink, IHlink) INIT_INTERFACE_PART(CMyDocObject, Hlink) STDMETHOD(GetHlinkSite)(IHlinkSite**, DWORD*); STDMETHOD(SetHlinkSite)(IHlinkSite*, DWORD); STDMETHOD(GetMonikerReference)(DWORD, IMoniker**, LPWSTR*); STDMETHOD(GetStringReference)(DWORD, LPWSTR*, LPWSTR*); STDMETHOD(GetFriendlyName)(DWORD, LPCWSTR*); STDMETHOD(SetFriendlyName)(LPCWSTR); STDMETHOD(GetTargetFrameName)(LPCWSTR*); STDMETHOD(SetTargetFrameName)(LPCWSTR); STDMETHOD(GetAdditionalParams)(LPCWSTR*); STDMETHOD(SetAdditionalParams)(LPCWSTR); STDMETHOD(Navigate)(DWORD, IBindCtx*, IBindStatusCallback*, IHlinkBrowseContext*); STDMETHOD(GetMiscStatus)(DWORD*); END_INTERFACE_PART(Hlink)
This member function retrieves the hyperlink's associated site, along with its data, which are returned through the two arguments.
STDMETHOD(GetHlinkSite)(IHlinkSite**, DWORD*);Argument Type Description IHlinkSite** Where to send the hyperlink associated site's interface. A NULL value is not accepted. DWORD* Where to send further site data. A NULL value is not accepted.
This member function associates the hyperlink with a hyperlink site whose interface is passed in the first argument. A hyperlink must be associated with a hyperlink site in order to work properly when IHlink::Navigate() is called.
STDMETHOD(SetHlinkSite)(IHlinkSite*, DWORD);Argument Type Description IHlinkSite* Hyperlink site's interface. DWORD Further site's data.
This member function retrieves the container's moniker and the location within the target container, which are returned through the last two arguments.
Implementation note: the moniker passed in the second argument can bind to the target by calling IMoniker::BindToObject(). Once the hyperlink jump succeeded, this function can perform an internal hyperlink jump to go to the location, by calling Hlink::Navigate().
STDMETHOD(GetMonikerReference)(DWORD, IMoniker**, LPWSTR*);Argument Type Description DWORD An HLINKGETREF enumeration value. IMoniker** Where to send the container's moniker interface pointer. LPWSTR* Location within the hyperlink target.
This member function retrieves the container's address and location as strings, which are returned through the last two arguments.
STDMETHOD(GetStringReference)(DWORD, LPWSTR*, LPWSTR*);Argument Type Description DWORD A HLINKGETREF enumeration value. LPWSTR* Where to send the string. LPWSTR* Where to send the location.
This member function retrieves the friendly name of the hyperlink reference, which is returned through the last argument. This function is called by the hyperlink container when updating its user interface.
Note that the friendly name returned from the hyperlink may differ from the one returned from the target, as the hyperlink may cache it.
STDMETHOD(GetFriendlyName)(DWORD, LPCWSTR*);Argument Type Description DWORD An HLFNAMEF enumeration value. Indicates which friendly name must be returned. LPWSTR* Where to send the friendly name.
This member function sets the friendly name of a hyperlink reference.
STDMETHOD(SetFriendlyName)(LPCWSTR);Argument Type Description LPCWSTR Where to send the friendly name.
This member function retrieves the name of the target frame (as in HTML framesets). The name is returned through the single argument and is useless if the container doesn't support frame-sets.
STDMETHOD(GetTargetFrameName)(LPCWSTR*);Argument Type Description LPWSTR* Where to send the target frame name.
This member function sets the target frame name. The name is useless if the container doesn't support frame-sets.
STDMETHOD(SetTargetFrameName)(LPCWSTR);Argument Type Description LPCWSTR Target frame name.
This member function retrieves additional parameters or properties of the hyperlink, which are returned through the single argument. The parameter string's format is designed as follows:
<ID1="value1"><ID2="value2">...<Idn="valuen">
Most of the parameters saved in this string are specific to the hyperlink frame.
STDMETHOD(GetAdditionalParams)(LPCWSTR*);Argument Type Description LPWSTR* Where to send the parameter string.
This member function sets additional parameters or properties of the hyperlink. The string format is described in IHlink::SetAdditionalParams().
STDMETHOD(SetAdditionalParams)(LPCWSTR);Argument Type Description LPCWSTR Parameter string.
This member function perform a hyperlink jump.
STDMETHOD(Navigate)(DWORD, IBindCtx*, IBindStatusCallback*, IHlinkBrowseContext*);Argument Type Description DWORD HLNF enumeration values. IBindCtx* The bind context to use for every moniker that will be created during the navigation. May not be NULL. IBindStatusCallback* The bind status callback to use for asynchronous moniker binding. A NULL value means the caller doesn't need to know information such as cancellation, progress state, and so on. IHlinkBrowseContext* The browse context that will be used during this hyperlink navigation.
Asks if the hyperlink is an absolute or relative link. The answer is returned through the single argument.
STDMETHOD(GetMiscStatus)(DWORD*);Argument Type Description DWORD* Where to send an HLINKMISC enumeration value.
This interface is used to access a hyperlink container, typically when it is viewed as a hyperlink target (hence the interface name).
BEGIN_INTERFACE_PART(HlinkTarget, IHlinkTarget) INIT_INTERFACE_PART(CMyDocObject, HlinkTarget) STDMETHOD(GetBrowseContext)(IHlinkBrowseContext**); STDMETHOD(SetBrowseContext)(IHlinkBrowseContext*); STDMETHOD(Navigate)(DWORD, IBindCtx*, IBindStatusCallback*, IHlink*); STDMETHOD(GetMoniker)(LPCWSTR, DWORD, IMoniker**); STDMETHOD(GetFriendlyName)(LPCWSTR, LPWSTR*); END_INTERFACE_PART(HlinkTarget)
This member function retrieves the browse context of the target. This function returns the desired interface through the argument and calls HlinkBrowseContext::AddRef() in order to tell the browse context the target is holding a reference to it.
This function doesn't need to be implemented for simple hyperlinking.
STDMETHOD(GetBrowseContext)(IHlinkBrowseContext**);Argument Type Description IHlinkBrowseContext** Where to send the browse context interface.
This member function sets the hyperlink target's browse context. This function will typically release its previous browse context (if any) by calling IHlinkBrowseContext::Release() and hold a reference to the browse context passed-in argument by calling IHlinkBrowseContext::AddRef().
This function doesn't need to be implemented for simple hyperlinking.
STDMETHOD(SetBrowseContext)(IHlinkBrowseContext*);Argument Type Description IHlinkBrowseContext* The new browse context interface pointer.
This function navigates to the location and shows it if not visible (that is, display it on screen). Note that if the target supports browse context, it calls IHlinkBrowseContext::OnNavigateHlink() to notify a hyperlink jump.
This function doesn't need to be implemented for simple hyperlinking.
STDMETHOD(Navigate)(DWORD, IBindCtx*, IBindStatusCallback*, IHlink*);Argument Type Description DWORD HLNF enumeration values. LPCWSTR Location within the hyperlink target.
This member function returns a moniker pointing to the hyperlink target, for the given hyperlink location. The moniker's interface is returned through the last argument.
STDMETHOD(GetMoniker)(LPCWSTR, DWORD, IMoniker**);Argument Type Description LPCWSTR Location within the hyperlink target. DWORD An OLEGETMONIKER enumeration. Must be either OLEGETMONIKER_ONLYIFTHERE (if the moniker does not exist, return E_FAIL) or OLEGETMONIKER_FORCEASSIGN (if the moniker does not exist, create it). IMoniker** Where to send the resulting moniker.
This member function retrieves the friendly name, which is returned through the last argument.
STDMETHOD(GetFriendlyName)(LPCWSTR, LPWSTR*);Argument Type Description LPCWSTR The location within the target. LPWSTR* Where to return the friendly name. This string must be allocated by the function by calling CoTaskMemFree() and freed by the function's caller through CoTaskMemFree().
This interface is used by the hyperlink frame. It is mostly used for browse context management (either retrieving or setting the browse context).
BEGIN_INTERFACE_PART(HlinkTarget, IHlinkTarget) INIT_INTERFACE_PART(CMyDocObject, HlinkTarget) STDMETHOD(GetBrowseContext)(IHlinkBrowseContext**); STDMETHOD(SetBrowseContext)(IHlinkBrowseContext*); STDMETHOD(Navigate)(DWORD, IBindCtx*, IBindStatusCallback*, IHlink*); STDMETHOD(OnNavigate)(DWORD); END_INTERFACE_PART(HlinkTarget)
This member function retrieves the hyperlink frame browse context, which is returned through the function's single argument.
This function doesn't need to be implemented for simple hyperlinking.
STDMETHOD(GetBrowseContext)(IHlinkBrowseContext**);Argument Type Description IHlinkBrowseContext** Where to send the browse context interface pointer.
This member function sets the hyperlink frame browse context.
This function doesn't need to be implemented for simple hyperlinking.
STDMETHOD(SetBrowseContext)(IHlinkBrowseContext*);Argument Type Description IHlinkBrowseContext* The browse context interface.
This member function performs a hyperlink navigation. It is called by the IHlink::Navigate() interface member function when it is given a non-NULL IHlinkFrame pointer. The goal of this function is to allow the hyperlink frame to perform some action during the hyperlink jump.
STDMETHOD(Navigate)(DWORD, IBindCtx*, IBindStatusCallback*, IHlink*);Argument Type Description DWORD HLNF enumeration values. IBindCtx* The bind context to use for every moniker that will be created during the hyperlink jump. IBindStatusCallback* The bind status callback to use for every asynchronous moniker that will be created during the hyperlink jump. IHlink* The hyperlink to navigate to.
This member function is called to notify the hyperlink frame that the navigation succeeded. This allows a hyperlink frame to update its window. This function is called by the hyperlink target during IHlinkTarget::Navigate() using the global function HlinkOnNavigate().
STDMETHOD(OnNavigate)(DWORD);Argument Type Description DWORD HLNF enumeration values.
This interface is returned by the hyperlink frame and is used for browse context management.
BEGIN_INTERFACE_PART(HlinkBrowseContext, IHlinkBrowseContext) INIT_INTERFACE_PART(CMyDocObject, HlinkBrowseContext) STDMETHOD(Register)(DWORD, IUnknown*, IMoniker*, DWORD*); STDMETHOD(GetObject)(IMoniker*, IUnknown**); STDMETHOD(Revoke)(DWORD); STDMETHOD(GetBrowseWindowInfo)(HLBWINFO*); STDMETHOD(SetBrowseWindowInfo)(HLBWINFO*); STDMETHOD(EnumNavigationStack)(IEnumHLITEM**); STDMETHOD(QueryHlink)(ULONG); STDMETHOD(GetHlink)(ULONG, Iklink**); STDMETHOD(SetCurrentHlink)(ULONG); STDMETHOD(OnNavigateHlink)(DWORD, IMoniker*, LPCWSTR, LPCWSTR); STDMETHOD(Clone)(IUnknown*, REFIID, IUnknown**); STDMETHOD(Close)(DWORD); END_INTERFACE_PART(HlinkBrowseContext)
This member function registers an object with the browse context. The browse context maintains a table of moniker-object bindings. This table can be accessed for navigation to already registered hyperlink targets. When a hyperlink jump occurs, the browse context looks at this table and checks if the hyperlink target is already registered and is running. If so, it doesn't have to reload the same document object. This function returns a registration ID (through the last argument), which can be used to revoke the registration.
STDMETHOD(Register)(DWORD, IUnknown*, IMoniker*, DWORD*);Argument Type Description DWORD Reserved for future use. Must be zero. IUnknown* The object to register. IMoniker* The moniker that points to the object being registered. DWORD* Where to send the output value, that is, the registration ID.
This member function retrieves the object corresponding to the moniker passed in the first argument. The resulting object is returned through the last argument.
STDMETHOD(GetObject)(IMoniker*, IUnknown**);Argument Type Description IMoniker* Identifies the object to retrieve. IUnknown** Where to send the object's IUnknown interface pointer.
This member function cancels the object whose registration ID is the one passed in argument. This ID is given by IHlinkBrowseContext::Register().
STDMETHOD(Revoke)(DWORD);Argument Type Description DWORD Registration ID of the object to be revoked.
This member function retrieves the HLBWINFO structure currently associated with the browse context, which is returned through the only function argument. This function is generally called by a hyperlink target during IHlinkTarget::Navigate() in order to draw its user interface.
STDMETHOD(GetBrowseWindowInfo)(HLBWINFO*);Argument Type Description HLBWINFO* Where to return the HLBWINFO structure containing window information.
This member function is the opposite of IHlinkBrowseContext::GetBrowseWindowInfo(). It sets the browse context window information from a HLBWINFO structure passed-in argument. This function is generally used by the hyperlink target and the hyperlink container when the window is resized.
STDMETHOD(SetBrowseWindowInfo)(HLBWINFO*);Argument Type Description HLBWINFO* The HLBWINFO structure containing window information.
This member function creates an HLITEM enumerator that will browse a sequence of HLITEM structures. The sequence structures will contain information about the navigation stack's hyperlinks and friendly names associated. This function returns through the argument the enumerator's interface, that is IEnumHLITEM.
STDMETHOD(EnumNavigationStack)(IEnumHLITEM**);Argument Type Description IEnumHLITEM** Where to send the enumerator's interface.
This member function tests the validity of a hyperlink. It is generally called by the hyperlink frame to determine the validity of commands such as Go Forward or Go Back by passing HLID_NEXT and HLID_PREVIOUS. The HLQF enumeration must be either HLQF_ISVALID or HLQF_ISCURRENT. A HLQF_ISVALID value means the function must check if the hyperlink (whose ID is passed in the second argument) is valid within the browse context. A HLQF_ISCURRENT value means the function must check if the hyperlink is the current browse context hyperlink.
STDMETHOD(QueryHlink)(ULONG);Argument Type Description DWORD A HLQF enumeration value. ULONG Identifies the hyperlink to check. Can be an HLID constant.
This member function retrieves from the browse context the hyperlink whose ID is passed as the first argument. The resulting hyperlink IHlink interface is returned through the second argument.
STDMETHOD(GetHlink)(ULONG, Iklink**);Argument Type Description ULONG Identifies the hyperlink to retrieve. Can be an HLID constant. IHlink** Where to send the interface of the hyperlink to retrieve.
This member function sets as current hyperlink in the browse context the hyperlink whose ID is passed in argument.
STDMETHOD(SetCurrentHlink)(ULONG);Argument Type Description ULONG Identifies the hyperlink to set as current browse context hyperlink. Can be an HLID constant.
This member function is called by the hyperlink target during IHlinkTarget::Navigate() to notify the browse context that a hyperlink jump has been performed.
STDMETHOD(OnNavigateHlink)(DWORD, IMoniker*, LPCWSTR, LPCWSTR);Argument Type Description DWORD HLNF enumeration values. IMoniker* The moniker of the hyperlink target. LPCWSTR The location within the hyperlink target. May not be NULL. LPCWSTR The friendly name of the location within the hyperlink target. May not be NULL.
This member function clones the browse context. The clone is returned through the last argument.
STDMETHOD(Clone)(IUnknown*, REFIID, IUnknown**);Argument Type Description IUnknown* IUnknown interface of the object controlling the new browse context. A NULL value (the most common) means the browse context isn't aggregated. REFIID Interface ID of the created browse context. Generally IID_IHlinkBrowseContext. void** Where to return the new browse context desired interface.
This member function closes the browse context. It releases all the hyperlink targets that are still registered through IHlinkBrowseContext::Register().
STDMETHOD(Close)(DWORD);Argument Type Description DWORD Reserved for a future use. Must be zero.
This interface is a standard OLE enumeration interface. When the IHlinkBrowseContext::EnumNavigationStack() function is called, it creates a HLITEM structures enumerator and returns its IEnumHLITEM interface. The created enumerator is controlled through this interface and can browse a HLITEM sequence.
BEGIN_INTERFACE_PART(EnumHLITEM, IEnumHLITEM) INIT_INTERFACE_PART(CMyDocObject, EnumHLITEM) STDMETHOD(Next)(ULONG, HLITEM*, ULONG*); STDMETHOD(Skip)(ULONG); STDMETHOD(Reset)(void); STDMETHOD(Clone)(IEnumHLITEM**); END_INTERFACE_PART(EnumHLITEM)
This member function retrieves a given number (passed as the first argument) of HLITEM structures. These structures will be copied in an HLITEM array (passed as the second argument).
STDMETHOD(Next)(ULONG, HLITEM*, ULONG*);Argument Type Description ULONG Number of HLITEM structures to retrieve. HLITEM* Array where the HLITEM structures will be copied. ULONG* Where to send the actual number of HLITEM copied, in case there are fewer elements left than requested.
This member function skips a given number of elements.
STDMETHOD(Skip)(ULONG);Argument Type Description ULONG The number of elements to skip.
This member function sets the enumerator at the beginning of the sequence.
STDMETHOD(Reset)(void);Returned Value Meaning S_OK Success.
This member function clones the enumerator. The clone will have the same state, that is the same position of the sequence.
STDMETHOD(Clone)(IEnumHLITEM**);Argument Type Description IEnumHLITEM** Where to send the created enumerator's interface pointer.
OLE Hyperlinking Navigation brings to ActiveX that which made the Web successful: Hyperlinks, that is, how to jump from one document to another by a simple mouse click. This technology allows either a DocObject or an ActiveX control to simply implement hyperlinks and to interact with the Web Browser. Hyperlinking Navigation comes with two sets of APIs. The first set is a simple API and enables quick hyperlinking implementation. The second API, which is far larger, implements many more features, such as a greater interaction with the Web browser than with the simple API. However, this API is tougher to implement and, most of all, still subject to change.
This chapter first explains exactly what OLE Hyperlinking Navigation is, how it works, and what you can do with it. It then describes what the differences are between the two APIs. Finally, it explains in detail each API.