/*
** help.h
**
** typedefs & definitions used in the help system and by those who use it.
**
** define:
**  HOFFSET	- to define buffer pointers (PB's) as handle/offset, else
**		  they are defined as void far *.
*/
typedef char f;              /* boolean                      */
typedef unsigned char uchar;
typedef unsigned long ulong;
typedef unsigned short ushort;

/*
** lineattr
** external representation of line attributes, as returned by HelpGetLineAttr
*/
typedef struct lineattr {		/* LA */
    ushort attr;			/* attribute index		*/
    ushort cb;				/* count of bytes		*/
    } lineattr;
/*
** mh
** a memory handle is defined for use with systems that use dynamic, moveable
** memory. It is long, so that in simple cases where memory is NOT moveable,
** the handle can contain the far pointer to the base.
*/
typedef void * mh;                      /* dynamic memory handle        */
/*
** nc
** a context number is a unique id associated with each context string.
**
** fhnc     returns the file memory handle from the nc
** fLocal   returns TRUE if the context is a uniq context number (local, or
**		    result of explicit uniq call.
*/
typedef struct _nc {
        mh     mh;
        ulong  cn;
        } nc ;                       /* context number               */
// rjsa #define fmhnc(x)   ((unsigned)(((unsigned long)x & 0xffff0000L) >> 16))
#define fmhnc(x)   ((x).mh)
#define fUniq(x)   ((x).cn & 0x8000)

/*
** topichdr
** header placed (by HelpDecomp) at the begining of every decompressed topic
*/
typedef struct topichdr {		/* TH */
    uchar appChar;			/* app-specific character const */
    uchar linChar;			/* character for line removal	*/
    uchar ftype;			/* source file type		*/
    ushort lnCur;			/* line number last accessed	*/
    ushort lnOff;			/* offset into topic for that line*/
    } topichdr;

/*
** hotspot
** defines the position of an embedded cross reference, or "hotspot". Used by
** HelpHlNext and HelpXRef
*/
typedef struct hotspot {		/* HS */
    ushort line;			/* the topic line with an xref	*/
    ushort col; 			/* the starting column of xref	*/
    ushort ecol;			/* the ending columng of xref	*/
    uchar far *pXref;			/* pointer to xref string	*/
    } hotspot;
/*
** helpheader
** This defines the actual structure of a help file header. Provided here
** for HelpGetInfo
*/
#define HS_count	      9 	/* number-1 of sections defined */

#pragma pack(1)
typedef struct helpheader {		/* HH */
    ushort wMagic;			/* word indicating help file	*/
    ushort wVersion;			/* helpfile version		*/
    ushort wFlags;			/* flags			*/
    ushort appChar;			/* application specific char	*/
    ushort cTopics;			/* count of topics		*/
    ushort cContexts;			/* count of context strings	*/
    ushort cbWidth;			/* fixed width			*/
    ushort cPreDef;			/* count of pre-defined contexts*/
    uchar fname[14];			/* base file name		*/
    ushort reserved[2]; 		/* unused			*/
    ulong tbPos[HS_count];		/* positions for file sections	*/
    } helpheader;
#pragma pack()
/*
** fdb
** Dynamically allocated structure which is created for each open help file.
** Remains allocated for the life of the file.
**
** rgmhSections contains dynamic memory handles. Each open file has various
** dynamic memory buffers associated with it. Each can be present or discarded,
** as memory constrictions determine. If needed and not present, they are
** reloaded from the associated help file. All may be discarded when memory
** gets tight. An entry is defined for each help file section, except for the
** Topics themselves.
**
*/
typedef struct fdb {			/* FDB */
    FILE * fhHelp;                      /* OS file handle               */
    nc ncInit;				/* initial context (includes mh)*/
    mh rgmhSections[HS_count-1];	/* dynamic memory handles	*/
    uchar ftype;			/* file type			*/
    uchar fname[14];			/* base file name		*/
    ulong foff; 			/* our file offset, if appended */
    nc ncLink;				/* nc linking any appended file */
    helpheader hdr;			/* file header			*/
    } fdb;
/*
** helpinfo
** structure of information relating to a help file and/or context returned
** by HelpGetInfo
*/
typedef struct helpinfo {		/* HI */
    fdb     fileinfo;			/* entire fdb copied out	*/
    char    filename[1];		/* filename appended to data	*/
    } helpinfo;
/*
** Macros for accessing helpinfo data
*/
#define     FHHELP(x)	((x)->fileinfo.fhHelp)
#define     NCINIT(x)	((x)->fileinfo.ncInit)
#define     FTYPE(x)	((x)->fileinfo.ftype)
#define     FNAME(x)	((x)->fileinfo.fname)
#define     FOFF(x)	((x)->fileinfo.foff)
#define     NCLINK(x)	((x)->fileinfo.ncLink)
#define     WMAGIC(x)	((x)->fileinfo.hdr.wMagic)
#define     WVERSION(x)	((x)->fileinfo.hdr.wVersion)
#define     WFLAGS(x)	((x)->fileinfo.hdr.wFlags)
#define     APPCHAR(x)	((x)->fileinfo.hdr.appChar)
#define     CTOPICS(x)	((x)->fileinfo.hdr.cTopics)
#define     CCONTEXTS(x) ((x)->fileinfo.hdr.cContexts)
#define     CBWIDTH(x)	((x)->fileinfo.hdr.cbWidth)
#define     CPREDEF(x)	((x)->fileinfo.hdr.cPreDef)
#define     HFNAME(x)	((x)->fileinfo.hdr.fname)
#define     TBPOS(x)	((x)->fileinfo.hdr.tbPos)

/******************************************************************************
**
** Some versions of the help engine run with SS!=DS, and thus require the
** _loadds attribute on function calls.
*/
#ifdef DSLOAD
#define LOADDS _loadds
#else
#define LOADDS
#endif

/******************************************************************************
**
** PB
** pointer to a buffer. Based on the switch HOFFSET, it is either a
** handle-offset or a far pointer. In the handle/offset case, the high word
** contains a memory handle which must be locked, to get a "real" address, to
** which the offset is added.
*/
#ifdef HOFFSET
#define PB	ulong
#else
#define PB	void far *
#endif

typedef PB	pb;

/******************************************************************************
**
** Forward declarations
*/
void	far pascal LOADDS HelpInit (void);

void	far pascal LOADDS HelpClose(nc);
nc	far pascal LOADDS HelpOpen(char far *);

nc	far pascal LOADDS HelpNc(char far *, nc);
nc	far pascal LOADDS HelpNcCmp (char far *, nc,
			      f (pascal far *)(uchar far *, uchar far *, ushort, f, f));
ushort	far pascal LOADDS HelpNcCb(nc);
ushort	far pascal LOADDS HelpLook(nc, PB);
f	far pascal LOADDS HelpDecomp(PB, PB, nc);
void	far pascal LOADDS HelpCtl(PB, f);

nc	far pascal LOADDS HelpNcNext(nc);
nc	far pascal LOADDS HelpNcPrev(nc);
nc	far pascal LOADDS HelpNcUniq(nc);

void	far pascal LOADDS HelpNcRecord(nc);
nc	far pascal LOADDS HelpNcBack(void);

f	far pascal LOADDS HelpSzContext(uchar far *, nc);
int	far pascal LOADDS HelpGetInfo (nc, helpinfo far *, int);

void	far pascal LOADDS HelpShrink(void);

int	far pascal LOADDS HelpGetCells(int, int, char far *, PB, uchar far *);
ushort	far pascal LOADDS HelpGetLine(ushort, ushort, uchar far *, PB);
ushort	far pascal LOADDS HelpGetLineAttr(ushort, int, lineattr far *, PB);
int	far pascal LOADDS HelpcLines(PB);

f	far pascal LOADDS HelpHlNext(int, PB, hotspot far *);
char far * pascal far LOADDS HelpXRef(PB, hotspot far *);

/******************************************************************************
**
** constant declarations
**
** Character attribute bits. These bits are order together to form attribute
** indecies. Data in the help file has associated with it attribute information
** encoded in length/index pairs. Each index is simply a constant which
** indicates which of several attributes should be applied to the characters in
** that portion of the line.
*/
#define A_PLAIN 	0		/* plain, "normal" text 	*/
#define A_BOLD		1		/* emboldened text		*/
#define A_ITALICS	2		/* italicised text		*/
#define A_UNDERLINE	4		/* underlined text		*/

/******************************************************************************
**
** Help Error Codes.
**
** Return values greater than HELPERR_MAX are valid nc's.
*/
#define HELPERR_FNF	    1		/* OpenFileOnPath failed	*/
#define HELPERR_READ	    2		/* ReadHelpFile failed on header*/
#define HELPERR_LIMIT	    3		/* to many open helpfiles	*/
#define HELPERR_BADAPPEND   4		/* bad appeneded file		*/
#define HELPERR_NOTHELP     5		/* Not a help file		*/
#define HELPERR_BADVERS     6		/* newer or incompatible help file */
#define HELPERR_MEMORY	    7		/* memory allocation failed	*/
#define HELPERR_MAX	    10		/* max help error		*/