/*---------------------------------------------------------------------------| | | | DLL.H | | | | Copyright (C) Microsoft Corporation 1990. | | All Rights reserved. | | | ------------------------------------------------------------------------------ | | | Module Intent | | | | Exports Winhelp's DLL macro binding functions (for LDLLHandler). | | | ------------------------------------------------------------------------------ | How it could be improved: | | rename lockcallbacks to lockvptr | remove duplicate names (search DUPLICATES) | Naming on functions is Hungarian, but may be confusing-- | eg: HFOpenHfs does not open an hfs, but a bag file | but- CloseHfs does close Hfs. | but- AccessHfs does not access hfs, but bag file status. ----------------------------------------------------------------------------*/ /*************************************************************************** * RegisterRoutine Prototypes. * * Syntax of the proto-type is as follows: * proto ::= [parmlist] * parmlist ::= NULL OR [params] * params ::= [param] OR ([param] [params]) * param ::= "i" OR "u" OR "s" OR "I" OR "U" OR "S" * rettype ::= [param] OR "v" * * Example: "uSiS" * "" * "uSs" * * Short Signed 'i' * Long Signed 'I' * Short Unsigned 'u' * Long Unsigned 'U' * Near String 's' * Far String 'S' * Void 'v' * * Custom macros may be embedded. There are coding rules. * Embedding macro calls: Syntax of the string is as follows: * list ::= NULL OR [macrolist] * macrolist ::= [macro] OR ([macro] ":" [macrolist]) * macro ::= [name] "(" [paramlist] ")" * name ::= (ALPHA OR "_") [namechars] * namechars ::= NULL OR ALPHANUM OR "_" * paramlist ::= NULL OR [params] * params ::= [param] OR ([param] "," [params]) * param ::= [posint] OR [int] OR [string] OR [macro] OR [var * posint ::= "0"..."9" * int ::= ("-" ([posint] OR [macro])) OR [posint] * string ::= (""" CHARS """) OR ("`" CHARS "'") * var ::= "hwndContext" OR "qchPath" OR "qError" * * Example: call1(5, "string", -call2()):call3("string") * call1(call1(call1(0))):call2() * * ***************************************************************************/ // // for use with the 'qError' internal variable #define wMACRO_ERROR 128 /* Maximum length of an error msz */ /* NOTE: These #defines must be */ /* ordered because they are used */ /* as indexes into rgmpWMErrWErrs */ #define wMERR_NONE 0 /* No error */ #define wMERR_MEMORY 1 /* Out of memory (local) */ #define wMERR_PARAM 2 /* Invalid parameter passed */ #define wMERR_FILE 3 /* Invalid file parameter */ #define wMERR_ERROR 4 /* General macro error */ #define wMERR_MESSAGE 5 /* Macro error with message */ /* Flags set in fwFlags to indicate*/ /* how the error *MAY* be handled.*/ #define fwMERR_ABORT 0x0001 /* Allow the "abort" option. */ #define fwMERR_CONTINUE 0x0002 /* Allow the "continue" option. */ #define fwMERR_RETRY 0x0004 /* Allow the "retry" option. */ /********** ** ** The Macro Error structure is used to allow a macro to return error ** information. It allows the macro to not only return pre-defined ** errors, but also to use the error string provided to pass back a ** customized error string. ** *********/ typedef struct { /* Contains flags indicating how an */ /* error will be handled -- init- */ WORD fwFlags; /* ially set to fwMERR_ABORT */ /* Error number if one occurs -- */ WORD wError; /* initially set to wMERR_NONE. */ /* If wError == wMERR_MESSAGE, this */ /* array will contain the error */ char rgchError[wMACRO_ERROR]; /* message to be displayed. */ } ME, NEAR * PME, FAR * QME; // end 'qError' internal variable defines. /*---------------------------------------------------------------------------| | | | Defines | | | ----------------------------------------------------------------------------*/ // Classes of messages that may be */ // sent to DLLs (legal returns for DW_WHATMSG handler // in LDLLHandler routine. (see autodoc notes & example below) typedef WORD RC; // Error return (return code) #define DC_NOMSG 0x00000000 /* Classes of messages that may be */ #define DC_MINMAX 0x00000001 /* send to DLLs */ #define DC_INITTERM 0x00000002 #define DC_JUMP 0x00000004 #define DC_ACTIVATE 0x00000008 #define DC_CALLBACKS 0x00000010 #define DW_NOTUSED 0 // Messages sent to DLLs. #define DW_WHATMSG 1 #define DW_MINMAX 2 #define DW_SIZE 3 #define DW_INIT 4 #define DW_TERM 5 #define DW_STARTJUMP 6 #define DW_ENDJUMP 7 #define DW_CHGFILE 8 #define DW_ACTIVATE 9 #define DW_CALLBACKS 10 /* Embedded Window messages */ #define EWM_RENDER 0x706A #define EWM_QUERYSIZE 0x706B #define EWM_ASKPALETTE 0x706C #define EWM_FINDNEWPALETTE 0x706D /* DLLs should process this if they want to their audio to reset correctly when another audio device attempts to use audio. */ #define WM_AUDIORESET 0x706E #define HLPMENUEDITCOPY 0x0002 typedef struct tagCreateInfo { short idMajVersion; short idMinVersion; LPSTR szFileName; // Current Help file LPSTR szAuthorData; // Text passed by the author HANDLE hfs; // Handle to the current file system DWORD coFore; // Foreground color for this topic DWORD coBack; // Background color for this topic } EWDATA, FAR *QCI; typedef struct tagRenderInfo { RECT rc; HDC hdc; } RENDERINFO, FAR * QRI; // Window variables: #define GWW_HSE 0 //Handle to the Searcher State structure #define GWW_HCALLBACKS 2 //Pointer to Help callbacks #define GWL_INIT 4 //Status if bag.ini or initialization wrong. #define wMGR_EXTRA 8 /* This should be the total size of ** everything above. */ #define INIT_FAILED 0 #define INIT_FTOK 1 #define INIT_MMWINOK 2 typedef FARPROC FAR *VPTR; extern BOOL PASCAL FAR InitRoutines(LPSTR,DWORD); extern BOOL PASCAL FAR FFinalizeMVDLL(void); extern VPTR PASCAL FAR LpLockCallbacks(void); extern BOOL PASCAL FAR FUnlockCallbacks(void); extern BOOL PASCAL FAR FInitCallBacks( VPTR VPtr, LONG lVersion); extern DWORD PASCAL FAR LGetStatus(void); extern BOOL FAR PASCAL MVHelp( HWND hwndMain, LPSTR lpszPath, LPSTR lpszFile, LPSTR lpszMacro); /*-------------------------------------------------------------------------*\ * * Defines * \-------------------------------------------------------------------------**/ /* file mode flags */ #define fFSReadOnly (BYTE)0x01 /* file (FS) is readonly */ #define fFSOpenReadOnly (BYTE)0x02 /* file (FS) is opened in readonly mode */ #define fFSReadWrite (BYTE)0x00 // file (FS) is readwrite #define fFSOpenReadWrite (BYTE)0x00 // file (FS) is opened in read/write mode /* seek origins */ #define wFSSeekSet 0 #define wFSSeekCur 1 #define wFSSeekEnd 2 /* low level info options */ #define wLLSameFid 0 #define wLLDupFid 1 #define wLLNewFid 2 // Callback Function Table offsets: #define HE_NotUsed 0 #define HE_HfsOpenSz 1 #define HE_RcCloseHfs 2 #define HE_HfOpenHfs 3 #define HE_RcCloseHf 4 #define HE_LcbReadHf 5 #define HE_LTellHf 6 #define HE_LSeekHf 7 #define HE_FEofHf 8 #define HE_LcbSizeHf 9 #define HE_FAccessHfs 10 #define HE_RcLLInfoFromHf 11 #define HE_RcLLInfoFromHfs 12 #define HE_ErrorW 13 #define HE_ErrorSz 14 #define HE_GetInfo 15 #define HE_API 16 /* Return codes */ #define rcSuccess 0 #define rcFailure 1 #define rcExists 2 #define rcNoExists 3 #define rcInvalid 4 #define rcBadHandle 5 #define rcBadArg 6 #define rcUnimplemented 7 #define rcOutOfMemory 8 #define rcNoPermission 9 #define rcBadVersion 10 #define rcDiskFull 11 #define rcInternal 12 #define rcNoFileHandles 13 #define rcFileChange 14 #define rcTooBig 15 // following not from core engine: #define rcReadError 101 /** * Errors for Error() **/ /* Errors to generate */ #define wERRS_OOM 2 /* Out of memory */ #define wERRS_NOHELPPS 3 /* No help during printer setup */ #define wERRS_NOHELPPR 4 /* No help while printing */ #define wERRS_FNF 1001 /* Cannot find file */ #define wERRS_NOTOPIC 1002 /* Topic does not exist */ #define wERRS_NOPRINTER 1003 /* Cannot print */ #define wERRS_PRINT 1004 #define wERRS_EXPORT 1005 /* Cannot copy to clipboard */ #define wERRS_BADFILE 1006 #define wERRS_OLDFILE 1007 #define wERRS_Virus 1011 /* Bad .EXE */ #define wERRS_BADDRIVE 1012 /* Invalid drive */ #define wERRS_WINCLASS 1014 /* Bad window class */ #define wERRS_BADKEYWORD 3012 /* Invalid keyword */ #define wERRS_BADPATHSPEC 3015 /* Invalid path specification */ #define wERRS_PATHNOTFOUND 3017 /* Path not found */ #define wERRS_DIALOGBOXOOM 3018 /* Insufficient memory for dialog */ #define wERRS_DiskFull 5001 /* Disk is full */ #define wERRS_FSReadWrite 5002 /* File read/write failure */ /** * Actions for LGetInfo() **/ #define GI_NOTHING 0 /* Not used. */ #define GI_INSTANCE 1 /* Application instance handle */ #define GI_MAINHWND 2 /* Main window handle */ #define GI_CURRHWND 3 /* Current window handle */ #define GI_HFS 4 /* Handle to file system in use */ #define GI_FGCOLOR 5 /* Foreground color used by app */ #define GI_BKCOLOR 6 /* Background color used by app */ #define GI_TOPICNO 7 /* Topic number */ #define GI_HPATH 8 /* Handle containing path -- caller*/ /* must free */ /*------------------------------------------------------------------------- * * Types * \-------------------------------------------------------------------------**/ typedef WORD RC; /* Error return (return code) */ typedef HANDLE HFS; /* Handle to a file system */ typedef HANDLE HF; /* Handle to a file system bag file */ /*--------------------------------------------------------------------------- * * Public Functions pointers * |-------------------------------------------------------------------------**/ /*-------------------------------------------------------------------------*\ * * Function: RcGetFSError() * * Purpose: return the most recent FS error code * * Method: Give value of last error that the file system encountered. * * ASSUMES * * globals IN: rcFSError - current error code; set by most recent FS call * * PROMISES * * returns: returns current error in file system. * \-------------------------------------------------------------------------**/ typedef RC (FAR PASCAL *LPFN_RCGETFSERROR)(void); /*-------------------------------------------------------------------------*\ * * Function: HfsOpenSz( sz, bFlags ) * * Purpose: Open a file system * * ASSUMES * * args IN: sz - path to file system to open * bFlags - fFSOpenReadOnly or fFSOpenReadWrite * * PROMISES * * returns: handle to file system if opened OK, else hNil * \-------------------------------------------------------------------------**/ typedef HFS (FAR PASCAL *LPFN_HFSOPENSZ)( LPSTR, BYTE ); /*-------------------------------------------------------------------------*\ * * Function: RcCloseHfs( hfs ) * * Purpose: Close an open file system. * All bag files must be closed or changes made will be lost * * ASSUMES * * args IN: hfs - handle to an open file system * * PROMISES * * returns: standard return code * * globals OUT: rcFSError * \-------------------------------------------------------------------------**/ typedef HFS (FAR PASCAL *LPFN_RCCLOSEHFS)( HFS ); /*-------------------------------------------------------------------------*\ * * Function: HfOpenHfs( hfs, sz, bFlags ) * * Purpose: open a bag file in a file system * * ASSUMES * * args IN: hfs - handle to file system * sz - name (key) of bag file to open * bFlags - * * PROMISES * * returns: handle to open bag file or hNil on failure * * Notes: strlen( qNil ) and strcpy( s, qNil ) don't work as they should. * \-------------------------------------------------------------------------**/ typedef HF (FAR PASCAL *LPFN_HFOPENHFS) (HFS, LPSTR, BYTE); /*-------------------------------------------------------------------------*\ * * Function: RcCloseHf( hf ) * * Purpose: close an open bag file in a file system * * Method: If the bag file is dirty, copy the scratch bag file back to the * FS bag file. If this is the first time the bag file has been closed, * we enter the name into the FS directory. If this bag file is * the FS directory, store the location in a special place * instead. Write the FS directory and header to disk. * Do other various hairy stuff. * * ASSUMES * * args IN: hf - bag file handle * * PROMISES * * returns: rcSuccess on successful closing * \-------------------------------------------------------------------------**/ typedef RC (FAR PASCAL *LPFN_RCCLOSEHF) ( HF); /*-------------------------------------------------------------------------*\ * * Function: LcbReadHf(hf, qb, lcb) * * Purpose: read bytes from a bag file in a file system * * ASSUMES * * args IN: hf - bag file * lcb - number of bytes to read * * PROMISES * * returns: number of bytes actually read; -1 on error * * args OUT: qb - data read from bag file goes here (must be big enough) * * Notes: These are signed longs we're dealing with. This means * behaviour is different from read() when < 0. * \-------------------------------------------------------------------------**/ typedef LONG (FAR PASCAL *LPFN_LCBREADHF) ( HF, LPBYTE, LONG); /*-------------------------------------------------------------------------*\ * * Function: LcbWriteHf( hf, qb, lcb ) * * Purpose: write the contents of buffer into bag file * * Method: If bag file isn't already dirty, copy data into temp file. * Do the write. * * ASSUMES * * args IN: hf - bag file * qb - user's buffer full of stuff to write * lcb - number of bytes of qb to write * * PROMISES * * returns: number of bytes written if successful, -1L if not * * args OUT: hf - lifCurrent, lcbFile updated; dirty flag set * * globals OUT: rcFSError * \-------------------------------------------------------------------------**/ typedef LONG (FAR PASCAL *LPFN_LCBWRITEHF) ( HF, LPBYTE, LONG); /*-------------------------------------------------------------------------*\ * * Function: LTellHf( hf ) * * Purpose: return current bag file position * * ASSUMES * * args IN: hf - handle to open bag file * * PROMISES * * returns: bag file position * \-------------------------------------------------------------------------**/ typedef LONG (FAR PASCAL *LPFN_LTELLHF) ( HF); /*-------------------------------------------------------------------------*\ * * Function: LSeekHf( hf, lOffset, wOrigin ) * * Purpose: set current bag file pointer * * ASSUMES * * args IN: hf - bag file * lOffset - offset from origin * wOrigin - origin (wSeekSet, wSeekCur, or wSeekEnd) * * PROMISES * * returns: new position offset in bytes from beginning of bag file * if successful, or -1L if not * * state OUT: bag file pointer is set to new position unless error occurs, * in which case it stays where it was. * \-------------------------------------------------------------------------**/ typedef LONG (FAR PASCAL *LPFN_LSEEKHF) ( HF, LONG, WORD); /*-------------------------------------------------------------------------*\ * * Function: FEofHf() * * Purpose: Tell whether bag file pointer is at end of file. * * ASSUMES * * args IN: hf * * PROMISES * * returns: fTrue if bag file pointer is at EOF, fFalse otherwise * \-------------------------------------------------------------------------**/ typedef BOOL (FAR PASCAL *LPFN_FEOFHF) ( HF); /*-------------------------------------------------------------------------*\ * * Function: LcbSizeHf( hf ) * * Purpose: return the size in bytes of specified bag file * * ASSUMES * * args IN: hf - bag file handle * * PROMISES * * returns: size of the bag file in bytes * \-------------------------------------------------------------------------**/ typedef LONG (FAR PASCAL *LPFN_LCBSIZEHF) ( HF); /*-------------------------------------------------------------------------*\ * * Function: FAccessHfs( hfs, sz, bFlags ) * * Purpose: Determine existence or legal access to a FS bag file * * ASSUMES * * args IN: hfs * sz - bag file name * bFlags - ignored * * PROMISES * * returns: fTrue if bag file exists (is accessible in stated mode), * fFalse otherwise * * Bugs: access mode part is unimplemented * \-------------------------------------------------------------------------**/ typedef BOOL (FAR PASCAL *LPFN_FACCESSHFS) ( HFS, LPSTR, BYTE); /*------------------ - - Name: ErrorW * * Purpose: Displays an error message * * Arguments: nError - string identifyer See wERRS_* messages. * * Returns: Nothing. * -----------------*/ typedef VOID (FAR PASCAL *LPFN_ERRORW) ( int ); /*-------------------------------------------------------------------------- * - Name: ErrorSz - * Purpose: Displays standard Help error message dialog based * the string passed. * * Arguments: lpstr - string to display * * Returns: Nothing. * --------------------------------------------------------------------------*/ typedef VOID (FAR PASCAL *LPFN_ERRORSZ) ( LPSTR ); /*-------------------------------------------------------------------------- * - Name: LGetInfo - * Purpose: Gets global information from the app. * * Arguments: hwnd - window handle of topic to query. * wItem - item to get * GI_INSTANCE - Application instance handle * GI_MAINHWND - Main window handle * GI_CURRHWND - Current window handle * GI_HFS - Handle to file system in use * GI_FGCOLOR - Foreground color used by app * GI_BKCOLOR - Background color used by app * GI_TOPICNO - Topic number * GI_HPATH - Handle containing path -- caller * must free * * Notes: if the HWND is NULL, then the data will come from the window * which currently has the focus. * --------------------------------------------------------------------------*/ typedef LONG (FAR PASCAL *LPFN_LGETINFO) (WORD, HWND); /*------------------ - - Name: FAPI * * Purpose: Post a message for Help requests * * Arguments: * qchHelp path (if not current directory) and file * to use for Help topic. * usCommand Command to send to Help * ulData Data associated with command: * * * Returns: TRUE iff success * -----------------*/ typedef LONG (FAR PASCAL *LPFN_FAPI) ( LPSTR, WORD, DWORD ); /*--------------------------------------------------------------------------\ * - Function: RcLLInfoFromHf( hf, wOption, qfid, qlBase, qlcb ) - * Purpose: Map an HF into low level file info. * * ASSUMES * args IN: hf - an open HF * qfid, qlBase, qlcb - pointers to user's variables * wOption - wLLSameFid, wLLDupFid, or wLLNewFid * * PROMISES * returns: RcFSError(); rcSuccess on success * * args OUT: qfid - depending on value of wOption, either * the same fid used by hf, a dup() of this fid, * or a new fid obtained by reopening the bag file. * * qlBase - byte offset of first byte in the bag file * qlcb - size in bytes of the data in the bag file * * globals OUT: rcFSError * * Notes: It is possible to read data outside the range specified * by *qlBase and *qlcb. Nothing is guaranteed about what * will be found there. * If wOption is wLLSameFid or wLLDupFid, and the FS is * opened in write mode, this fid will be writable. * However, writing is not allowed and may destroy the * file system. * * Fids obtained with the options wLLSameFid and wLLDupFid * share a file pointer with the hfs. This file pointer * may change after any operation on this FS. * The fid obtained with the option wLLSameFid may be closed * by FS operations. If it is, your fid is invalid. * * NULL can be passed for qfid, qlbase, qlcb and this routine * will not pass back the information. * * Bugs: wLLDupFid is unimplemented. * * +++ * * Method: * * Notes: * \--------------------------------------------------------------------------*/ typedef RC (FAR PASCAL *LPFN_RCLLINFOFROMHF) ( HF, WORD, WORD FAR *, LONG FAR *, LONG FAR * ); /*--------------------------------------------------------------------------\ * - Function: RcLLInfoFromHfs( hfs, sz, wOption, qfid, qlBase, qlcb ) - * Purpose: Map an HF into low level file info. * * ASSUMES * args IN: hfs - an open HFS * szName - name of bag file in FS * qfid, qlBase, qlcb - pointers to user's variables * wOption - wLLSameFid, wLLDupFid, or wLLNewFid * * PROMISES * returns: RcFSError(); rcSuccess on success * * args OUT: qfid - depending on value of wOption, either * the same fid used by hf, a dup() of this fid, * or a new fid obtained by reopening the bag file. * * qlBase - byte offset of first byte in the bag file * qlcb - size in bytes of the data in the bag file * * globals OUT: rcFSError * * Notes: It is possible to read data outside the range specified * by *qlBase and *qlcb. Nothing is guaranteed about what * will be found there. * If wOption is wLLSameFid or wLLDupFid, and the FS is * opened in write mode, this fid will be writable. * However, writing is not allowed and may destroy the * file system. * * Fids obtained with the options wLLSameFid and wLLDupFid * share a file pointer with the hfs. This file pointer * may change after any operation on this FS. * The fid obtained with the option wLLSameFid may be closed * by FS operations. If it is, your fid is invalid. * * NULL can be passed for qfid, qlbase, qlcb and this routine * will not pass back the information. * * Bugs: wLLDupFid is unimplemented. * * Method: Calls RcLLInfoFromHf(). * * Notes: * \--------------------------------------------------------------------------*/ typedef RC (FAR PASCAL *LPFN_RCLLINFOFROMHFS) (HFS, LPSTR, WORD, WORD FAR *, LONG FAR *, LONG FAR * );