Unit Hlpdll32

This header is a port of Microsoft's C header file for Help DLLs as published in the Help Applications Generator authoring guide (the "HAG"). It contains a number of additions based on discoveries by a number of authors, additional commentary and a critical correction to the definition of the HE_GETINFO function abstraction. This header may be used interchangeably for both 16 and 32 bit Help. Among those responsible for the additions, comments and corrections include Bernd Herd, Cub Lea, Jim Mischel, and Matthew Withopf. A few of Matthew's comments remain here untranslated, and additional info on some functions is available in the HAG docs (downloadable from Microsoft and www.shareware.com via a partfilename search on WHAG or WHAT6). Several versions of the WinHelp header file created for use with Pascal environments have been found to be faulty in some areas. This version has been fairly well tested with Delphi, Delphi 2 and Delphi 3 with baggage and embeddings. Cub Lea (9/97) *) {unit Hlpdll16;

Classes

Functions

GetCallBacks - GetCallBacks -- Copy function pointers from array to global function pointers.

Types

FPtrs
HF
HFS
LPFN_ErrorSz
LPFN_ErrorW
LPFN_FAccessHfs
LPFN_FAPI
LPFN_FEofHf
LPFN_HfCreateFileHfs
LPFN_HfOpenHfs
LPFN_HfsCreateFileSys
LPFN_HfsOpenSz
LPFN_LcbReadHf
LPFN_LcbSizeHf
LPFN_LcbSizeHfs
LPFN_LcbWriteHf
LPFN_LGetInfo
LPFN_LSeekHf
LPFN_LTellHf
LPFN_RcAbandonHf
LPFN_RcCloseHf
LPFN_RcCloseHfs
LPFN_RcDestroyFileSys
LPFN_RcFlushHf
LPFN_RcLLInfoFromHf
LPFN_RcLLInfoFromHfs
LPFN_RcRenameFileHfs
LPFN_RcUnlinkFileHfs
ME
pEWData
pFPtrs
pME
pRenderInfo
QCI
QRI
RC
TEWData
TRenderInfo

Constants

DC_Activate
DC_CallBacks
DC_InitTerm
DC_Jump
DC_MinMax
DW_Activate
DW_CallBacks
DW_ChgFile
DW_EndJump
DW_Init
DW_MinMax
DW_NotUsed
DW_Size
DW_StartJump
DW_Term
DW_Unknown1
DW_WhatMsg
EWM_AskPalette
EWM_FindNewpalette
EWM_QuerySize
EWM_Render
fFSOpenReadOnly
fFSOpenReadWrite
fFSReadOnly
fFSReadWrite
fwMERR_Abort
fwMERR_Continue
fwMERR_Retry
GI_BKColor
GI_CurrHWnd
GI_FGColor
GI_HFS
GI_HPath
GI_Instance
GI_MainHWnd
GI_Nothing
GI_TopicNo
HELP_GotoMark
HELP_JmpId
HELP_JumpHash
HELP_PopupHash
HELP_PopupId
HELP_SetContents
HE_API
HE_ErrorSz
HE_ErrorW
HE_FAccessHfs
HE_FEofHf
HE_GetInfo
HE_HfCreateFileHfs
HE_HfOpenHfs
HE_HfsCreateFileSys
HE_HfsOpenSz
HE_LcbReadHf
HE_LcbSizeHf
HE_LcbSizeHfs
HE_LcbWriteHf
HE_LSeekHf
HE_LTellHf
HE_NotUsed
HE_RcAbandonHf
HE_RcCloseHf
HE_RcCloseHfs
HE_RcDestroyFileSys
HE_RcFlushHf
HE_RcLLInfoFromHf
HE_RcLLInfoFromHfs
HE_RcRenameFileHfs
HE_RcUnlinkFileHfs
rcBadArg
rcBadHandle
rcBadVersion
rcDiskFull
rcExists
rcFailure
rcFileChange
rcInternal
rcInvalid
rcNoExists
rcNoFileHandles
rcNoPermission
rcOutOfMemory
rcReadError
rcSuccess
rcTooBig
rcUnimplemented
wERRS_BadDrive
wERRS_BadFile
wERRS_BadKeyWord
wERRS_BadPathSpec
wERRS_DialogBoxOOM
wERRS_DiskFull
wERRS_Export
wERRS_FNF
wERRS_FSReadWrite
wERRS_NoHelpPR
wERRS_NoHelpPS
wERRS_NoPrinter
wERRS_NoTopic
wERRS_OldFile
wERRS_OOM
wERRS_PathNotFound
wERRS_Print
wERRS_Virus
wERRS_WinClass
wFSSeekCur
wFSSeekEnd
wFSSeekSet
wLLDupFid
wLLNewFid
wLLSameFid
wMACRO_ERROR
wMERR_Error
wMERR_File
wMERR_Memory
wMERR_Message
wMERR_None
wMERR_Param

Variables

ErrorSz
ErrorW
FAccessHfs
FAPI
FEofHf
HfCreateFileHfs
HfOpenHfs
HfsCreateFileSys
HfsOpenSz
LcbReadHf
LcbSizeHf
LcbSizeHfs
LcbWriteHf
LGetInfo
LSeekHf
LTellHf
RcAbandonHf
RcCloseHf
RcCloseHfs
RcDestroyFileSys
RcFlushHf
RcLLInfoFromHf
RcLLInfoFromHfs
RcRenameFileHfs
RcUnlinkFileHfs


Functions


Function GetCallBacks (vptr : pFPtrs; lVersion : Longint) : Longint;

GetCallBacks -- Copy function pointers from array to global function pointers. This declaration permits relatively simple calling of functions (see the baggage function for an example). Allows us to call "FAPI(...)" instead of "LPFN_FAPI(vptr^[HE_API])"

Types


FPtrs = Array [HE_NotUsed..HE_RcDestroyFileSys] of Pointer;

HF  = THandle
Handle to a file system
HFS = THandle
Error return code
LPFN_ErrorSz = Procedure(lpstr: PChar)
Retrieve last error by string
LPFN_ErrorW = Procedure(nError: Integer)
Retrieve last error by RC value
LPFN_FAccessHfs = Function(fs: HFS;		{handle of the open filesystem}
							 szName: PChar;	{name of the file queried}
							 bFlags: Byte): {If 0 then R/W, if 2 then ReadOnly}
							 BOOL
Determine access permissions for components of the helpfile's IFS
LPFN_FAPI = Function(qchHelp: PChar;		{qchPath of helpfile}
					   wCommand: Word;		{HELP_[command]}
					   ulData: Longint		{Pointer to string (HELP_JUMP etc)
											 or actual value to pass (HELP_CONTEXT etc}
					   ): Longint
This is equivalent to a WinHelp call done internally
LPFN_FEofHf = Function(f: HF): 			{handle to the opened file}
						BOOL
Determine end-of-file bool for reading HFS
LPFN_HfCreateFileHfs = Function(fs: HFS;	{handle to current filesystem}
						  szName: PChar;	{create new baggage file}
						  wFlags: Word		{creation mode (??)}
						  ): Word
Create a new baggage file
LPFN_HfOpenHfs = Function(fs: HFS;		{Handle to the filesystem}
							szName: PChar;	{Name of specific file, uppercase}
							bFlags: Byte    {If 0 then is read/write, if 2 then readonly}
							): HF
OpenFile equiv for Help internal filesystem
LPFN_HfsCreateFileSys = Function(szName: PChar; {name (??)}
								   Var pb	{pointer to parameter block}
								   ) : Word
wErr error code} {$IFDEF Win32
LPFN_HfsOpenSz = Function(sz: PChar;		{Name of helpfile system}
							bFlags: Byte	{If 0 then is read/write, if 2 then readonly}
							): HFS
Equivalent to our "Reset" function
LPFN_LcbReadHf = Function(f:HF;			{handle of the opened file}
							Var qb;			{variable pointer to the buffer which receives data,
											 indicates current position in the pointer for
											 blockread operations}
							lcb: Longint	{pointer size in bytes}
							): Longint
BlockRead for Help IFS
LPFN_LcbSizeHf = Function(f: HF): 		{handle to the opened file}
							Longint
Retrieve size of current open file
LPFN_LcbSizeHfs = Function(fs: HFS		{handle to current filesystem}
							): Longint
Total size of IFS
LPFN_LcbWriteHf = Function(f: HF;         {handle to baggage file}
							 Var qb;        {address of buffer with data to write}
							 lcb: Longint	{length of the buffer}
							 ): Longint
write data to a baggaged file
LPFN_LGetInfo = Function(wItem: Cardinal;	{Info to retrieve. List:
											{ $01: hInstance of this WinHelp}
											{ $02 HWnd of main window}
											{ $03 HWnd of window making call}
											{ $04 Handle to this helpfile's IFS}
											{ $05 Foreground color}
											{ $06 Background color}
											{ $07 actual topic index number}                                     { $08 Speicher-Handle    }
											{ $08 Pointer to qchPath for this helpfile}
											{ $64 Special handle for unknown}
											{ $65 ???}
											{ $66 ???}
											{ $67 PChar auf "MAIN"/"SECONDARY"}
											{ $68 Makro in Bearbeitung ($0000/$0001)}
							wnd: Hwnd		{windowhandle to query}
						   ): Longint
Retrieve specific info about the helpfile. NOTE: This function was NOT correctly defined in MS' own docs. Parameter order was reversed in the HAG documentation.
LPFN_LSeekHf = Function(f: HF;			{handle to the opened file}
						  lOffset: Longint; {offset from beginning of file}
						  wOrigin: Word     {seek mode: 0:from start,
														1: From current pos.
														2: From end}
						  ): Longint
FileSeek for Help IFS
LPFN_LTellHf = Function(f: HF				{handle to the opened file}
							): Longint
Retrieve file's position in IFS
LPFN_RcAbandonHf = Function(fs: HFS		{handle to current filesystem}
							  ): Word
Dump the current file
LPFN_RcCloseHf = Function(f:HF			{handle of opened file}
							): RC
CloseFile equivalent for Help IFS
LPFN_RcCloseHfs = Function(fs: HFS 		{Handle to the filesystem}
							): RC
Equivalent to our "Close" function
LPFN_RcDestroyFileSys = Function(szName: PChar {name (??)}
								   ): Word
wErr error code} {$IFDEF Win32
LPFN_RcFlushHf = Function(f: HF			{handle to baggage file}
							): Word

LPFN_RcLLInfoFromHf = Function(f: HF;
								 wOption: Word;
								 Var qfid: Word;
								 Var qlBase,qlcb:
								 Longint): RC
Retrieve low-level info about open file
LPFN_RcLLInfoFromHfs=Function(fs:HFS;     {handle to current filesystem}
					   szName: PChar;		{name of file, uppercase}
					   wOption: Word;		{0/1/2}
					   Var qfid: Word;		{file ID}
					   Var qlBase: Longint;	{offset of file in filesystem}
					   qlcb: Longint): RC
Retrieve data about a specific baggage file
LPFN_RcRenameFileHfs = Function(fs: HFS;	{handle to current filesystem}
						 szOldName: PChar;	{old name of file}
						 szNewName: PChar	{new name of file}
						 ): Word
Rename a baggage file
LPFN_RcUnlinkFileHfs = Function(fs : HFS;	{handle to current filesystem}
						  szName: PChar		{name of file to erase}
						  ): Word
Erase a baggage file
ME = record
fwFlags : Word;
wError : Word;
rgchError : Array [0..wMacro_Error-1] of Char;
end;

pEWData = ^TEWData
Embedded Window create structure
pFPtrs = ^FPtrs
Handle to a file system baggage file} {FPtrs is an array of pointers to functions.
pME = ^ME
Allow the "retry" option
pRenderInfo = ^TRenderInfo

QCI = ^TEWData

QRI = ^TRenderInfo
Embedded window rendering info
RC = Word

TEWData = record
idMajVersion : Integer;
idMinVersion : Integer;
szFileName : PChar;
szAuthorData : PChar;
hfs : THandle;
coFore : LongInt;
coBack : Longint;
end;

TRenderInfo = record
Rect : TRect;
DC : hDC;
end;

Constants

DC_Activate = 8

DC_CallBacks = 16

DC_InitTerm = 2

DC_Jump = 4

DC_MinMax = 1

Classes of messages that may be sent to DLLs

DW_Activate = 9

^FileName -

DW_CallBacks = 10

If 0 Then current has Lost Focus } { If <>0 then current Has Focus

DW_ChgFile = 8

TopicOffset ScrollBox Position

DW_EndJump = 7

DW_Init = 4

Lo=MaxX/Hi=MaxY -

DW_MinMax = 2

DW_NotUsed = 0

-> mögliche Antworten auf DW_WHATMSG-Nachricht } {Messages sent to DLLs

DW_Size = 3

1=Maximiz/2=Minimiz -

DW_StartJump = 6

DW_Term = 5

DW_Unknown1 = 11

^FuncTable

DW_WhatMsg = 1

EWM_AskPalette = $706C

EWM_FindNewpalette = $706D

EWM_QuerySize = $706B

EWM_Render = $706A

Embedded Window messages

fFSOpenReadOnly = 2

file (FS) is readonly

fFSOpenReadWrite = 0

File (FS) is read/write

fFSReadOnly = 1

file mode flags (help file system

fFSReadWrite = 0

file (FS) will open in readonly mode

fwMERR_Abort = 1

Macro error with message } {Flags constants indicating how error may be handled

fwMERR_Continue = 2

Allow the "abort" option

fwMERR_Retry = 4

Allow the "continue" option

GI_BKColor = 6

Foreground color used by app

GI_CurrHWnd = 3

Main window handle

GI_FGColor = 5

Handle to file system in use

GI_HFS = 4

Current window handle

GI_HPath = 8

Topic number

GI_Instance = 1

Not used

GI_MainHWnd = 2

Application instance handle

GI_Nothing = 0

File read/write failure } {Actions for LGetInfo

GI_TopicNo = 7

Background color used by app

HELP_GotoMark = $0202

HELP_JmpId = $0103

HELP_JumpHash = $0095

HELP_PopupHash = $0096

HELP_PopupId = $0104

HELP_SetContents = $0066

Function ID constants for use by FAPI

HE_API = 16

HE_ErrorSz = 14

HE_ErrorW = 13

HE_FAccessHfs = 10

HE_FEofHf = 8

HE_GetInfo = 15

HE_HfCreateFileHfs = 18

HE_HfOpenHfs = 3

HE_HfsCreateFileSys = 24

HE_HfsOpenSz = 1

HE_LcbReadHf = 5

HE_LcbSizeHf = 9

HE_LcbSizeHfs = 17

HE_LcbWriteHf = 21

HE_LSeekHf = 7

HE_LTellHf = 6

HE_NotUsed = 0

Handle containing path } {Callback Function Table offsets

HE_RcAbandonHf = 23

HE_RcCloseHf = 4

HE_RcCloseHfs = 2

HE_RcDestroyFileSys = 25

HE_RcFlushHf = 20

HE_RcLLInfoFromHf = 11

HE_RcLLInfoFromHfs = 12

HE_RcRenameFileHfs = 22

HE_RcUnlinkFileHfs = 19

rcBadArg = 6

rcBadHandle = 5

rcBadVersion = 10

rcDiskFull = 11

rcExists = 2

rcFailure = 1

rcFileChange = 14

rcInternal = 12

rcInvalid = 4

rcNoExists = 3

rcNoFileHandles = 13

rcNoPermission = 9

rcOutOfMemory = 8

rcReadError = 101

following not from core engine:

rcSuccess = 0

Return codes

rcTooBig = 15

rcUnimplemented = 7

wERRS_BadDrive = 1012

Bad .EXE

wERRS_BadFile = 1006

Cannot copy to clipboard

wERRS_BadKeyWord = 3012

Bad window class

wERRS_BadPathSpec = 3015

Invalid keyword

wERRS_DialogBoxOOM = 3018

Path not found

wERRS_DiskFull = 5001

Insufficient memory for dialog

wERRS_Export = 1005

Printing error

wERRS_FNF = 1001

No help while printing

wERRS_FSReadWrite = 5002

Disk is full

wERRS_NoHelpPR = 4

No help during printer setup

wERRS_NoHelpPS = 3

Out of memory

wERRS_NoPrinter = 1003

Topic does not exist

wERRS_NoTopic = 1002

Cannot find file

wERRS_OldFile = 1007

Not a Windows Help file

wERRS_OOM = 2

Error constants and values for Error

wERRS_PathNotFound = 3017

Invalid path specification

wERRS_Print = 1004

Cannot print

wERRS_Virus = 1011

Can't read help file

wERRS_WinClass = 1014

Invalid drive

wFSSeekCur = 1

wFSSeekEnd = 2

wFSSeekSet = 0

file (FS) is opened in read/write mode} {seek origins

wLLDupFid = 1

wLLNewFid = 2

wLLSameFid = 0

low level info options

wMACRO_ERROR = 128

Macro error structure and error code definitions

wMERR_Error = 4

Invalid file parameter

wMERR_File = 3

Invalid parameter passed

wMERR_Memory = 1

No error

wMERR_Message = 5

General macro error

wMERR_None = 0

Maximum error msg length } {Macro error constants

wMERR_Param = 2

Out of memory (local)

Variables

ErrorSz : LPFN_ErrorSz

ErrorW : LPFN_ErrorW

FAccessHfs : LPFN_FAccessHfs

FAPI : LPFN_FAPI

FEofHf : LPFN_FEofHf

HfCreateFileHfs : LPFN_HfCreateFileHfs

HfOpenHfs : LPFN_HfOpenHfs

HfsCreateFileSys : LPFN_HfsCreateFileSys

HfsOpenSz : LPFN_HfsOpenSz

Pointers to internal functions. These are accessible to DLLs that Use this unit.

LcbReadHf : LPFN_LcbReadHf

LcbSizeHf : LPFN_LcbSizeHf

LcbSizeHfs : LPFN_LcbSizeHfs

LcbWriteHf : LPFN_LcbWriteHf

LGetInfo : LPFN_LGetInfo

LSeekHf : LPFN_LSeekHf

LTellHf : LPFN_LTellHf

RcAbandonHf : LPFN_RcAbandonHf

RcCloseHf : LPFN_RcCloseHf

RcCloseHfs : LPFN_RcCloseHfs

RcDestroyFileSys : LPFN_RcDestroyFileSys

RcFlushHf : LPFN_RcFlushHf

RcLLInfoFromHf : LPFN_RcLLInfoFromHf

RcLLInfoFromHfs : LPFN_RcLLInfoFromHfs

RcRenameFileHfs : LPFN_RcRenameFileHfs

RcUnlinkFileHfs : LPFN_RcUnlinkFileHfs