## WebWorks Help 4.0 & 5.0 API

> ### Overview

> WebWorks Help provides full featured, cross-platform, cross-browser HTML based help without compromises. Many companies have chosen to deploy WebWorks Help systems for their applications. WebWorks Help enables technical writers to make major changes to documentation without requiring development to modify context-sensitive help calls in their code. This affords technical writers the freedom they require without placing development schedules at risk.

> Despite the advantages given by WebWorks Help to technical writers and developers, a significant problem remains. How do developers easily display context-sensitive help links in a user's default browser?

> The answer is WebWorks Help 4.0 API, which is also compatible with WebWorks Help 5.0.

> The WebWorks Help 4.0 API is written in ANSI compliant C for portability. It compiles cleanly and runs on a variety of Windows, Macintosh, and UNIX operating systems. Full source code is provided.

> ### Description

> WebWorks Help 4.0 API supports detecting the user's current default browser and sending help topics to the browser for display. Additionally, the API will attempt to update a help topic without reloading the entire frameset. This avoids re-initialization of the Java or JavaScript navigation systems.

> WebWorks Help 4.0 API supports connections to Internet Explorer 4.0 and above, Netscape 4.x, Netscape 6.x, and Mozilla browsers running on the Windows, Macintosh, and UNIX platforms. Internet Explorer and Netscape compatible browsers may also work with the API but are not guaranteed to support reuse of help system frame sets.

> ### API Functions

> WebWorks Help 4.0 API consists of the following functions:

>     int  WWHelp_Startup(const char* pParamBaseURL);
>     int  WWHelp_Shutdown();

>     int  WWHelp_DisplayHelp(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_DisplayHelpWithNavigation(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_DisplayHelpWithContents(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_DisplayHelpWithIndex(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_DisplayHelpWithSearch(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_DisplayHelpWithFavorites(const char* pParamContext, const char* pParamTopic);

>     int  WWHelp_DisplayHelpNavigation();
>     int  WWHelp_DisplayHelpContents();
>     int  WWHelp_DisplayHelpIndex();
>     int  WWHelp_DisplayHelpSearch();
>     int  WWHelp_DisplayHelpFavorites();

> All functions return 0 if successful and non-zero if an error occurs.

> ### API Usage

> Developers need to insert a call to `WWHelp_Startup` during program initialization and a call to `WWHelp_Shutdown` just before the program exits. The call to `WWHelp_Startup` takes a single parameter, a C style, NULL terminated string that specifies the location of the help set. This string should point to the directory containing the help set and should not include a filename such as "index.htm".

> To display context-sensitive help topics, developers should call either `WWHelp_DisplayHelp` or `WWHelp_DisplayHelpWithNavigation`. The first function, `WWHelp_DisplayHelp`, displays the help topic without navigation aides such as a table of contents, index, or search options. The second function, `WWHelp_DisplayHelpWithNavigation`, will display the help topic with navigation aides. The calls `WWHelp_DisplayHelpWithContents`, `WWHelp_DisplayHelpWithIndex`, `WWHelp_DisplayHelpWithSearch`, and `WWHelp_DisplayHelpWithFavorites` allow developers to display context-sensitive help with a particular tab selected.

> To display the help set with navigation, developers should call `WWHelp_DisplayHelpNavigation`. This will display the help set in the default browser with navigation aides. The calls `WWHelp_DisplayHelpContents`, `WWHelp_DisplayHelpIndex`, `WWHelp_DisplayHelpSearch`, and `WWHelp_DisplayHelpFavorites` allow developers to display the help set with a particular tab selected.

> Note
> Since the WebWorks API functions always attempt to reuse the existing frameset, calling `WWHelp_DisplayHelpWithNavigation` will not reload the frameset in order to display navigation aides. Similarly, calling `WWHelp_DisplayHelp` will not reload the frameset to eliminate navigation aides.

> ### Platform Notes

> Each platform may require platform-specific initializations before using the WebWorks Help 4.0 API.

> Windows
> Under Windows, developers must include `<objbase.h>` and call `CoInitialize` during program initialization and `CoUninitialize` before the program exits. These calls are required since the WebWorks Help 4.0 API uses COM to communicate with running instances of Internet Explorer. These calls cannot be made inside of `WWHelp_Startup` and `WWHelp_Shutdown` since they must be called once and only once for your program.
> Required libraries: `kernel32.lib`, `user32.lib`, `advapi32.lib`, `oleaut32.lib`, `ole32.lib`, `uuid.lib`

> The Windows platform also supports calling the API via Visual Basic from a DLL and Windows platform languages (C#, VB .Net, VBScript, etc.) via COM. The following interfaces are used to support these runtimes:

>     int  WWHelp_VB_Startup(const char* pParamBaseURL);
>     int  WWHelp_VB_Shutdown();

>     int  WWHelp_VB_DisplayHelp(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_VB_DisplayHelpWithNavigation(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_VB_DisplayHelpWithContents(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_VB_DisplayHelpWithIndex(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_VB_DisplayHelpWithSearch(const char* pParamContext, const char* pParamTopic);
>     int  WWHelp_VB_DisplayHelpWithFavorites(const char* pParamContext, const char* pParamTopic);

>     int  WWHelp_VB_DisplayHelpNavigation();
>     int  WWHelp_VB_DisplayHelpContents();
>     int  WWHelp_VB_DisplayHelpIndex();
>     int  WWHelp_VB_DisplayHelpSearch();
>     int  WWHelp_VB_DisplayHelpFavorites();

> The BSTR API is used to implement the "WWHelp4.API" COM interface.

>     int  WWHelp_BSTR_Startup(const BSTR  ParamBaseURL);
>     int  WWHelp_BSTR_Shutdown();

>     int  WWHelp_BSTR_DisplayHelp(const BSTR  ParamContext, const BSTR  ParamTopic);
>     int  WWHelp_BSTR_DisplayHelpWithNavigation(const BSTR  ParamContext, const BSTR  ParamTopic);
>     int  WWHelp_BSTR_DisplayHelpWithContents(const BSTR  ParamContext, const BSTR  ParamTopic);
>     int  WWHelp_BSTR_DisplayHelpWithIndex(const BSTR  ParamContext, const BSTR  ParamTopic);
>     int  WWHelp_BSTR_DisplayHelpWithSearch(const BSTR  ParamContext, const BSTR  ParamTopic);
>     int  WWHelp_BSTR_DisplayHelpWithFavorites(const BSTR  ParamContext, const BSTR  ParamTopic);

>     int  WWHelp_BSTR_DisplayHelpNavigation();
>     int  WWHelp_BSTR_DisplayHelpContents();
>     int  WWHelp_BSTR_DisplayHelpIndex();
>     int  WWHelp_BSTR_DisplayHelpSearch();
>     int  WWHelp_BSTR_DisplayHelpFavorites();

> Macintosh
> No Macintosh specific initialization is required for the WebWorks Help 4.0 API. However, it is recommended that developers call `LSInit` during program initialization and `LSTerm` before the program exits. This will minimize the performance overhead associated with using Launch Services under Mac OS X.
> Additionally, developers should be aware that WebWorks Help 4.0 API creates temporary instances of InternetConfig to access browser information during calls to `WWHelp_Comm_SetDefaultBrowserInfo`. No known side-effects occur if your application maintains it's own InternetConfig instance. However, if problems do arise, you will need to modify the `WWHelp_Comm_SetDefaultBrowserInfo` function to use your application's InternetConfig instance.
> Projects created under Metrowerks Codewarrior should enable the "Interpret DOS and Unix paths" option under "Target", "Access Paths". Additionally, developers should specify "Prefix File:" under "Language", "C/C++ Language" to point to a header file that defines `TARGET_API_MAC_OS8`, `TARGET_API_MAC_CARBON`, `TARGET_API_MAC_OSX`, and `CALL_NOT_IN_CARBON` as required before including Apple's `<ConditionalMacros.h>` header file.
> Carbon builds require the latest available Carbon SDK, currently Carbon 1.4 SDK.
> Required libraries for Classic applications: `InterfaceLib`, `InternetConfigLib`, `MathLib`
> Required libraries for Carbon applications: `CarbonLib` `CarbonFrameworkLib`

> Unix
> No Unix specific initialization is required for the WebWorks Help 4.0 API.

> ### API Example

> Below is an example program that uses the WebWorks Help 4.0 API to display a context-sensitive topic defined in the example help set.

>     #include "wwhelp/wwhapi.h"
>     #include <stdio.h>
>     #include <string.h>

>     #if defined(_WIN32)
>     #include <objbase.h>
>     #elif TARGET_OS_MAC
>     #if (TARGET_API_MAC_CARBON)
>     #include <CodeFragments.h>
>     #include <LaunchServices.h>
>     #endif
>     #else
>     #endif

>     int  main(int   argc,
>               char* argv[])
>     {
>       char* pBaseHelpURL = "file:///P:/work/wwhapi/example/helpset";
>       int   ReturnCode;

>       /* Platform specific initializations */
>       /*                                   */
>     #if defined(_WIN32)
>       CoInitialize(NULL);
>     #elif TARGET_OS_MAC
>     #if (TARGET_API_MAC_CARBON)
>       if (((UInt32)LSInit) != ((UInt32)kUnresolvedCFragSymbolAddress))
>       {
>         LSInit(kLSInitializeDefaults);
>       }
>     #endif
>     #else
>     #endif

>       /* Initialize WWHelp API */
>       /*                       */
>       ReturnCode = WWHelp_Startup(pBaseHelpURL);
>       if (ReturnCode == 0)
>       {
>         /* Display help URL */
>         /*                  */
>         ReturnCode = WWHelp_DisplayHelp("beta", "section2");

>         /* Shutdown WWHelp API */
>         /*                     */
>         WWHelp_Shutdown();
>       }

>       /* Platform specific cleanup */
>       /*                           */
>     #if defined(_WIN32)
>       CoUninitialize();
>     #elif TARGET_OS_MAC
>     #if (TARGET_API_MAC_CARBON)
>       if (((UInt32)LSTerm) != ((UInt32)kUnresolvedCFragSymbolAddress))
>       {
>         LSTerm();
>       }
>     #endif
>     #else
>     #endif

>       return ReturnCode;
>     }