Presumptions

Before you start to work with Help Access Library you need to:

Basic Windows Help File concepts

Internal File System

Windows Help files and Media Viewer files are orgainzed internally as "Internal File Systems" meaning that a help file consists of many other internal files much the same way a ZIP or LHA-Archiv does. The internal files are not compressed like the ones used with ZIP, but for an application program using help files, these files can be handled like a set of distinct files located in a special directory.

To see a listing of all files contained in a given help file, you might try the TIFSENU.EXE program example:

C:\hlpacces>tifsenu hlpacces.hlp
FileOffset:0x00000010 Size:0x0000007c FileName:"bag.ini"
FileOffset:0x00011b00 Size:0x00000826 FileName:"|CONTEXT"
FileOffset:0x0001082d Size:0x00000002 FileName:"|CTXOMAP"
FileOffset:0x000105bb Size:0x00000269 FileName:"|FONT"
FileOffset:0x00010aa2 Size:0x00000826 FileName:"|KWBTREE"
FileOffset:0x00010838 Size:0x00000250 FileName:"|KWDATA"
FileOffset:0x00010a91 Size:0x00000008 FileName:"|KWMAP"
FileOffset:0x000004c4 Size:0x00000284 FileName:"|SYSTEM"
FileOffset:0x00000751 Size:0x0000fe61 FileName:"|TOPIC"
FileOffset:0x000112d1 Size:0x00000826 FileName:"|TTLBTREE"
FileOffset:0x0001232f Size:0x00001a4f FileName:"|bm0"

Files placed automatically by HC31 or HCW usually start with a "|"-Character, the file "bag.ini" in this example is a file included into the IFS by placing it into the [baggage] of an HPJ help project file.

This listing shows up where a internal file starts inside of the .HLP-File and the size of the internal file, so you could now theoretically read this files using your own code. But to easify this Process, Help Access Library supports functions to make reading from an internal file as easy as "open" and "close":

Accessing the IFS by Help Access Library

First you have to open the physical help or media viewer file using the Function IFSOpen. The result of this operation is a HIFS-Handle you'll need to use for all subsequent operations on this help file. You can't use this handle for Windows-Based file I/O functions, you have to use the Help Access Library functions instead.

{ HIFS ifs;

ifs = IFSOpen("Filename.hlp");

if (ifs)

{ /* File is available, could be opened and is indeed an IFS */

IFSClose(ifs);

}

}

After all operations on the help file have completed you can close the file by calling IFSClose to free up memory and the file handle associated with the file. Be aware to close all other handles assigned to this HIFS before closing it.

Accessing a named internal file

Once you have a HIFS-Handle retrieved by IFSOpen you can now open an internal file for reading by using the IFSOpenFile function. The Result of this operation is a HIFSFILE-Handle:

{ HIFSFILE ifsfile;

ifsfile = IFSOpenFile(ifs,"|bm0");

if (ifsfile)

{ /* A file of that name exists. */

IFSCloseFile(ifsfile);

}

}

Note that an HIFSHANDLE does not requre ist own operating system file handle. It is just a memory structure requiring some 100 bytes.

Reading an internal file

Once you have an HIFSFILE handle you can now perform read operations by using IFSReadFile and IFSSeekFile. To ask for the size of an internal file, you might use a call to IFSSeekFile with the whence-parameter set to 2.

{ DWORD  dwSize;

HGLOBAL  hmem;

LPSTR  pmem;

/* Get file size, and go back to start of file */

dwSize = IFSSeekFile(ifsfile, 0, 2);

IFSSeekFile(ifsfile, 0, 0);

/* Allocate a memory-Block of that size*/

hmem = GlobalAlloc(LPTR, dwSize);

if (hmem)

{

pmem = (LPSTR) GlobalLock(hmem);

/* Read Data from the internal file into the memory block */

IFSReadFile(ifsfile, pmem, dwSize);

GlobalUnlock(hmem);

}

}

Special Windows Help internal files

Windows Help uses several internal files to represent the data retrieved from a Help Project during compilation:

TopicOffset values linking internal files together

References done from the |CONTEXT, |KWDATA or |TTLBTREE internal file to the |TOPIC internal file are done using a 32 bit value named TopicOffset in Help Access library. These TopicOffset values are never used in the regular Windows Help API, as they reference directly into the binary location of data stored in the |TOPIC file. For the |TOPIC file is being compressed, the meaning of a TopicOffset is rather complex, but don't worry about that as Help Access Library manages these for you.

Hash Values and Context ID strings

A context ID string is a string connected to a #-Footnote to signify a Jump target for a popup or a topic. Context ID strings are usually not stored explicitly in a help file with the exception of context ID strings stored in SHG segmented hypergraphics and macros.

Instead Windows Help computes hash value representations from the context ID strings and stores these hash values into the |CONTEXT internal file. As the hash value contains much less information than the context ID string it is impossible to regenerate the context ID string from the hash value. Help Access Library contains the function HlpCreateStringForHashValue to generate a string having the same hash value representation, but it won't usually generate the same string passed to generate the hash value. To generate a hash value representation yourself you can use the HlpGenerateHashValue function.

Help Access Library concepts

Enumeration callbacks

For the amount of data stored in a help file can be pretty huge we choose to use enumeration callback based functionality whereever the amount of data to be retrieved is not limited. This is especially true for the Topic data, the context, key word and title lists.

For this reason most of the Help Access Library API cannot get accessed by interpreting languages like Visual Basic and Windows Help.

Examples for the use of these callbacks are to be found in a the example programs.

Accessing topic text

As the |TOPIC internal file references into the |FONTS and the |Phrases internal file and gets referenced by |KWDATA and |CONTEXT internal files, all these files need to be loaded into memory before accessing the topic text. The result of this process is summerized into a HTOPIC handle retrieved by calling HlpTopicOpen.

{ HTOPIC  htopic;

htopic = HlpTopicOpen(ifs, HTO_FONTS | HTO_CONTEXT | HTO_KEYWORDS);

if (htopic)

{

HlpTopicClose(htopic);

}

}

If your application does not need to know about keyword usage and jump targets, you can omit the HTO_CONTEXT and HTO_KEYWORDS flags to speed up processing.

If your application is interested in plain text data only, you can even omit HTO_FONTS. HlpTopicOpen is a rather slow function so you should call it once when opening the help file and use it for all subsequent calls to HlpTopicSeek and HlpTopicEnumerate.

Reading topic text

To read the topic text you first have to call HlpTopicSeek to setup the HTOPIC-Handle to read from the specified address. The TopicOffset value transfered to HlpTopicSeek has to point directly to the beginning of a topic, so you should retrieve it by a call to HlpEnumTitles or HlpGetTopicTitle. A TopicOffset if zero (0x00000000) is always valid and signifies the start of the file.

HlpTopicSeek(htopic, 0x00000000L);

After the seek operation has been performed you are now ready to read the topic text by enumerting it thru a callback function:

BOOL CALLBACK MyCallback(LPCSTR lpszTopicText, DWORD dummy, TEXTTYPE eTextType, LPARAM lParam)

{

return TRUE;

}

HlpTopicEnumerate(htopic, MyCallback, 0L);

The HlpTopicEnumerate function retrieves the text from the help file and passes it to the callback paragraph by paragraph. Several TextTypes telling the callback what to do about the data transfered, it is about the same as a message parameter in a Window Procedure.

Handling of formatting informations

Help Access Library transfers all formatting informations like bold, itcalic, font size, color etc. as strings in RTF (Richt Text Format) very likely to the format they had in the help file source code. These formatting informations are sent in texttype=TOPIC_RTF_TEXT. The text data itself is not included in the RTF data and it is sent as texttype=TOPIC_TEXT.

In case your application does not need to process any formatting informations you'll usually need to process the texttypes TOPIC_TEXT and TOPIC_TEXT_CONTROL. TOPIC_TEXT_CONTROL contains the same informations as TOPIC_RTF_TEXT for carriage returns, tabs and line feeds.

If your application needs to do a good representation of the text formatting, you need to process TOPIC_RTF_TEXT and TOPIC_TEXT, in addition Help Access Library sends RTTF initialization sequenced in TOPIC_RTF_INIT and the ending "}" in TOPIC_RTF_EXIT. Thus you can add your own stylesheets, headlines etc. after TOPIC_RTF_INIT or you can inhibit TOPIC_RTF_INIT on subsequent calls to HlpTopicEnumerate after TOPIC_RTF_INIT has been included once.

To get a close idea of how formatting is to be done, take a look at the TRTF, TCNV and TCGI-examples.

Accessing Bitmaps

All Bitmaps and Metafile graphics used in Help Files are stored in a file format most likely to the Segmented Hypergraphics SHG format used by the SHED help design tool. To give your application access to the data included in these files, include the files SHGIMPOR.H and SEG.H in your C-Sourcecode and use the SHGImport function to convert data to DIB or METAFILE format. See TCNV example for more details.