DEFINITION MODULE INIData;

        (************************************************************)
        (*                                                          *)
        (*               Looking after INI file data                *)
        (*                                                          *)
        (* This is the version designed to be implemented as a DLL  *)
        (*                                                          *)
        (*    Started:        30 March 2000                         *)
        (*    Last edited:    7 April 2019                          *)
        (*    Status:         Working                               *)
        (*                                                          *)
        (*  NOTE: any reference to an INI file can mean either a    *)
        (*  binary INI file or a text-based TNI file.  We           *)
        (*  distinguish between the two by seeing whether the file  *)
        (*  name ends with .INI or .TNI                             *)
        (*                                                          *)
        (************************************************************)


FROM SYSTEM IMPORT
    (* type *)  LOC;

FROM OS2 IMPORT
    (* type *)  HWND;

TYPE
    HINI;                       (* is private *)
    StringReadState;            (* is private *)

<* DLLEXPORT+ *>

PROCEDURE ChooseDefaultINI (appname: ARRAY OF CHAR;
                                   VAR (*OUT*) useTNI: BOOLEAN): BOOLEAN;

    (* Returns useTNI=TRUE if we should default to using appname.TNI to *)
    (* hold this application's data, useTNI=FALSE if the default should *)
    (* be to use appname.INI.  The decision is based on factors like    *)
    (* which file exists.  Of course the caller might in some cases     *)
    (* override this decision; all we are supplying is an initial       *)
    (* default.  The function result is FALSE if we are unable to make  *)
    (* a decision, i.e. either choice is equally good, and in that case *)
    (* the returned useTNI value should be ignored.                     *)

PROCEDURE CommitTNIDecision (appname: ARRAY OF CHAR;  useTNI: BOOLEAN);

    (* Stores the specified useTNI value in such a way that it will     *)
    (* become the default for the next ChooseDefaultINI decision, all   *)
    (* other factors being equal.                                       *)

PROCEDURE OpenINIFile (VAR (*IN*) filename: ARRAY OF CHAR): HINI;

    (* Opens an INI or TNI file, returns its handle. *)

PROCEDURE CreateINIFile (VAR (*IN*) filename: ARRAY OF CHAR): HINI;

    (* Like OpenINIFile, but creates an initially empty new file. *)

PROCEDURE INIValid (hini: HINI): BOOLEAN;

    (* Returns TRUE iff hini <> NIL. *)

PROCEDURE CloseINIFile (VAR (*INOUT*) hini: HINI);

    (* Closes an INI file. *)

PROCEDURE ItemSize (hini: HINI;  VAR (*IN*) application: ARRAY OF CHAR;
                          key: ARRAY OF CHAR;
                                VAR (*OUT*) size: CARDINAL): BOOLEAN;

    (* Sets size to the size in bytes of the given INI file entry,      *)
    (* or returns FALSE if there is no such entry.                      *)

PROCEDURE INIGetTrusted (hini: HINI;  VAR (*IN*) application: ARRAY OF CHAR;
                                       key: ARRAY OF CHAR;
                                       VAR (*OUT*) result: ARRAY OF LOC;
                                                         size: CARDINAL): BOOLEAN;

    (* Retrieves the value of a variable from the INI file.  Returns FALSE if   *)
    (* the variable was not found.  This the version in which we trust the      *)
    (* caller to have ensured that the size is correct.                         *)

PROCEDURE INIGet (hini: HINI;  VAR (*IN*) application: ARRAY OF CHAR;
                        key: ARRAY OF CHAR;
                            VAR (*OUT*) result: ARRAY OF LOC): BOOLEAN;

    (* Retrieves the value of a variable from the INI file.  Returns    *)
    (* FALSE if the variable was not found.                             *)

PROCEDURE INIGetString (hini: HINI;  VAR (*IN*) name1: ARRAY OF CHAR;
                              name2: ARRAY OF CHAR;
                                    VAR (*OUT*) variable: ARRAY OF CHAR): BOOLEAN;

    (* Like INIGet, but we accept any size data that will fit in the variable,  *)
    (* and we add a Nul terminator in the case of a size mismatch.              *)

PROCEDURE INIPut (hini: HINI;  VAR (*IN*) name1: ARRAY OF CHAR;  name2: ARRAY OF CHAR;
                                   variable: ARRAY OF LOC);

    (* Writes a fixed-size datum to the INI file. *)

PROCEDURE INIPutBinary (hini: HINI;  VAR (*IN*) name1: ARRAY OF CHAR;
                        name2: ARRAY OF CHAR;
                        VAR (*IN*) variable: ARRAY OF LOC;  amount: CARDINAL);

    (* Writes data to the INI file. *)

PROCEDURE INIPutString (hini: HINI;  VAR (*IN*) name1: ARRAY OF CHAR;
                                     name2: ARRAY OF CHAR;
                                        VAR (*IN*) string: ARRAY OF CHAR);

    (* Writes a character string to the INI file. *)

PROCEDURE GetStringList (hini: HINI;  VAR (*IN*) app, key: ARRAY OF CHAR;
                                   VAR (*OUT*) state: StringReadState);

    (* Initialisation in preparation for a "NextString" operation. *)

PROCEDURE NextString (state: StringReadState;  VAR (*OUT*) result: ARRAY OF CHAR);

    (* Reads the next character string from a string-of-strings field.  *)
    (* An empty string is returned when we have run out of strings.     *)

PROCEDURE CloseStringList (VAR (*INOUT*) state: StringReadState);

    (* Must be called to release the memory used in fetching a  *)
    (* string of strings.                                       *)

PROCEDURE INIDeleteApp (hini: HINI;  VAR (*IN*) app: ARRAY OF CHAR);

    (* Deletes an application from the INI file. *)

PROCEDURE INIRenameApp (hini: HINI;  VAR (*IN*) oldapp, newapp: ARRAY OF CHAR);

    (* Changes the name of an application, retaining the data. *)

PROCEDURE INIDeleteKey (hini: HINI;  VAR (*IN*) app: ARRAY OF CHAR;
                                         key: ARRAY OF CHAR);

    (* Deletes a key from the INI file. *)

PROCEDURE OurDirectory (VAR (*OUT*) dirname: ARRAY OF CHAR);

    (* Tells the caller the name of the program directory. *)

PROCEDURE SetInitialWindowPosition (hwnd: HWND;
                                    INIFileName, label: ARRAY OF CHAR);

    (* If this window has a previously stored position in our INI file, *)
    (* positions the window to that position.                           *)

PROCEDURE SetInitialWindowSize (hwnd: HWND;
                                  INIFileName, label: ARRAY OF CHAR);

    (* If this window has a previously stored size in our INI file, *)
    (* adjusts the window to that size.                             *)

PROCEDURE SetFont (hwnd: HWND;  INIFileName, label: ARRAY OF CHAR);

    (* Sets the font for this window, provided a font is stored in      *)
    (* the INI file.                                                    *)

PROCEDURE StoreWindowPosition (hwnd: HWND;
                               INIFileName, label: ARRAY OF CHAR);

    (* Saves the location of this window in our INI file. *)

PROCEDURE StoreWindowSize (hwnd: HWND;
                           INIFileName, label: ARRAY OF CHAR);

    (* Saves the size of this window in our INI file. *)

PROCEDURE StoreFont (hwnd: HWND;  INIFileName, label: ARRAY OF CHAR);

    (* Saves the font of this window in our INI file. *)

PROCEDURE GetProgramDirectory (VAR (*OUT*) dir: ARRAY OF CHAR);

    (* Returns the directory where the executable resides. *)

PROCEDURE SetWorkingDirectory;

    (* Sets the working drive and directory to be the same as that  *)
    (* where the executable resides.                                *)

<* DLLEXPORT- *>

END INIData.

