WebWorks Help 4.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.

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;
}