(**************************************************************************

     $RCSfile: AmigaGuide.mod $
  Description: Interface to amigaguide.library

   Created by: fjc (Frank Copeland)
    $Revision: 3.2 $
      $Author: fjc $
        $Date: 1994/08/08 01:13:39 $

  Includes Release 40.15

  (C) Copyright 1990-1993 Commodore-Amiga, Inc.
      All Rights Reserved

  Oberon-A Interface Copyright © 1994, Frank Copeland.
  This file is part of the Oberon-A Interface.
  See Oberon-A.doc for conditions of use and distribution.

*************************************************************************)

MODULE AmigaGuide;

(*
** $C- CaseChk       $I- IndexChk  $L+ LongAdr   $N- NilChk
** $P- PortableCode  $R- RangeChk  $S- StackChk  $T- TypeChk
** $V- OvflChk       $Z- ZeroVars
*)

IMPORT E := Exec, U := Utility, D := Dos, I := Intuition, SYS := SYSTEM;


TYPE

(**-- Pointer declarations ---------------------------------------------*)

  AmigaGuideMsgPtr * = CPOINTER TO AmigaGuideMsg;
  ContextTablePtr * = CPOINTER TO ContextTable;
  NewAmigaGuidePtr * = CPOINTER TO NewAmigaGuide;
  XRefPtr * = CPOINTER TO XRef;
  AmigaGuideHostPtr * = CPOINTER TO AmigaGuideHost;
  MsgPtr * = CPOINTER TO Msg;
  OpFindHostPtr * = CPOINTER TO OpFindHost;
  OpNodeIOPtr * = CPOINTER TO OpNodeIO;
  OpExpungeNodePtr * = CPOINTER TO OpExpungeNode;


(**-- Library definitions ----------------------------------------------*)

CONST

  apshToolId       * = 11000;
  startupMsgId     * = apshToolId+1;  (* Startup message *)
  loginToolId      * = apshToolId+2;  (* Login a tool SIPC port *)
  logoutToolId     * = apshToolId+3;  (* Logout a tool SIPC port *)
  shutdownMsgId    * = apshToolId+4;  (* Shutdown message *)
  activateToolId   * = apshToolId+5;  (* Activate tool *)
  deactivateToolId * = apshToolId+6;  (* Deactivate tool *)
  activeToolId     * = apshToolId+7;  (* Tool Active *)
  inactiveToolId   * = apshToolId+8;  (* Tool Inactive *)
  toolStatusId     * = apshToolId+9;  (* Status message *)
  toolCmdId        * = apshToolId+10; (* Tool command message *)
  toolCmdReplyId   * = apshToolId+11; (* Reply to tool command *)
  shutdownToolId   * = apshToolId+12; (* Shutdown tool *)

(* Attributes accepted by GetAmigaGuideAttr() *)
  agaDummy         * = U.tagUser;
  agaPath          * = agaDummy+1;
  agaXRefList      * = agaDummy+2;
  agaActivate      * = agaDummy+3;
  agaContext       * = agaDummy+4;

  agaHelpGroup     * = agaDummy+5;    (* E.ULONG: Unique identifier *)

  agaReserved1     * = agaDummy+6;
  agaReserved2     * = agaDummy+7;
  agaReserved3     * = agaDummy+8;

  agaARexxPort     * = agaDummy+9;
    (* E.MsgPortPtr: Pointer to the ARexx message port (V40) *)

  agaARexxPortName * = agaDummy+10;
    (* E.STRPTR: Used to specify the ARexx port name (V40) (not copied) *)

TYPE

  AmigaGuideContext * = CPOINTER TO RECORD END;

  AmigaGuideMsg * = RECORD (E.Message) (* Embedded Exec message structure *)
    agmType * :  E.ULONG;              (* Type of message *)
    data    * :  E.APTR;               (* Pointer to message data *)
    dSize   * :  E.ULONG;              (* Size of message data *)
    dType   * :  E.ULONG;              (* Type of message data *)
    priRet  * :  E.ULONG;              (* Primary return value *)
    secRet  * :  E.ULONG;              (* Secondary return value *)
    system1 * :  E.APTR;
    system2 * :  E.APTR;
  END;

(* Allocation description structure *)

  ContextTable * = ARRAY 32767 OF E.STRPTR;

  NewAmigaGuide * = RECORD
    lock       * : D.FileLockPtr; (* Lock on the document directory *)
    name       * : E.STRPTR;      (* Name of document file *)
    screen     * : I.ScreenPtr;   (* Screen to place windows within *)
    pubScreen  * : E.STRPTR;      (* Public screen name to open on *)
    hostPort   * : E.STRPTR;      (* Application's ARexx port name *)
    clientPort * : E.STRPTR;      (* Name to assign to the clients ARexx port *)
    baseName   * : E.STRPTR;      (* Base name of the application *)
    flags      * : SET;           (* Flags *)
    context    * : ContextTablePtr; (* NULL terminated context table *)
    node       * : E.STRPTR;      (* Node to align on first (defaults to Main) *)
    line       * : LONGINT;       (* Line to align on *)
    extens     * : U.TagListPtr;  (* Tag array extension *)
    client       : E.APTR;        (* Private! MUST be NULL *)
  END;

CONST

(* public Client flags *)

  loadIndex  * = 0;  (* Force load the index at init time *)
  loadAll    * = 1;  (* Force load the entire database at init *)
  cacheNode  * = 2;  (* Cache each node as visited *)
  cacheDb    * = 3;  (* Keep the buffers around until expunge *)
  unique     * = 15; (* Unique ARexx port name *)
  noActivate * = 16; (* Don't activate window *)

  sysGads    * = 31;

(* Callback function ID's *)
  hOpen  * = 0;
  hClose * = 1;

  errNotEnoughMemory  * = 100;
  errCantOpenDatabase * = 101;
  errCantFindNode     * = 102;
  errCantOpenNode     * = 103;
  errCantOpenWindow   * = 104;
  errInvalidCommand   * = 105;
  errCantComplete     * = 106;
  errPortClosed       * = 107;
  errCantCreatePort   * = 108;
  errKeywordNotFound  * = 113;

TYPE

(* Cross reference node *)
  XRef * = RECORD (E.Node)   (* Embedded node *)
    pad    * :  E.UWORD;     (* Padding *)
    df     * :  E.APTR (*DocFilePtr*);  (* Document defined in *)
    file   * :  E.STRPTR;    (* Name of document file *)
    xrName * :  E.STRPTR;    (* Name of item *)
    line   * :  LONGINT;     (* Line defined at *)
  END;

CONST

  xrSize * = SIZE (XRef);

(* Types of cross reference nodes *)
  xrGeneric  * = 0;
  xrFunction * = 1;
  xrCommand  * = 2;
  xrInclude  * = 3;
  xrMacro    * = 4;
  xrStruct   * = 5;
  xrField    * = 6;
  xrTypedef  * = 7;
  xrDefine   * = 8;

TYPE

(* Callback handle *)

  AmigaGuideHost * = RECORD (U.Hook) (* Dispatcher *)
    reserved   * :  E.ULONG;         (* Must be 0 *)
    flags      * :  SET;
    useCnt     * :  E.ULONG;         (* Number of open nodes *)
    systemData   :  E.APTR;          (* Reserved for system use *)
    userData   * :  E.APTR;          (* Anything you want... *)
  END;

CONST

(* Methods *)
  hmFindnode  * = 1;
  hmOpennode  * = 2;
  hmClosenode * = 3;
  hmExpunge   * = 10;  (* Expunge DataBase *)

TYPE

  Msg * = RECORD
    methodID * : E.ULONG;
  END;

(* hmFindnode *)
  OpFindHost * = RECORD (Msg)
    attrs - :  U.TagListPtr; (*  R: Additional attributes *)
    node  - :  E.STRPTR;     (*  R: Name of node *)
    TOC   * :  E.STRPTR;     (*  W: Table of Contents *)
    title * :  E.STRPTR;     (*  W: Title to give to the node *)
    next  * :  E.STRPTR;     (*  W: Next node to browse to *)
    prev  * :  E.STRPTR;     (*  W: Previous node to browse to *)
  END;

(* hmOpennode, hmClosenode *)
  OpNodeIO * = RECORD (Msg)
    attrs     - : U.TagListPtr;  (*  R: Additional attributes *)
    node      - : E.STRPTR;      (*  R: Node name and arguments *)
    fileName  * : E.STRPTR;      (*  W: File name buffer *)
    docBuffer * : E.STRPTR;      (*  W: Node buffer *)
    buffLen   * : E.ULONG;       (*  W: Size of buffer *)
    flags     * : SET;           (* RW: Control flags *)
  END;

CONST

(* OpNodeIO.flags *)
  nKeep      * = 0;      (* Don't flush this node until database is
                          * closed. *)
  nReserved1 * = 1;      (* Reserved for system use *)
  nReserved2 * = 2;      (* Reserved for system use *)
  nAscii     * = 3;      (* Node is straight ASCII *)
  nReserved3 * = 4;      (* Reserved for system use *)
  nClean     * = 5;      (* Remove the node from the database *)
  nDone      * = 6;      (* Done with node *)

(* OpNodeIO.attrs *)
  naDummy     * = U.tagUser;
  naScreen    * = naDummy+1;  (* I.ScreenPtr: Screen that window resides in *)
  naPens      * = naDummy+2;  (* Pen array (from DrawInfo) *)
  naRectangle * = naDummy+3;  (* Window box *)

  naHelpGroup * = naDummy+5;  (* E.ULONG: unique identifier *)

TYPE

(* hmExpunge *)
  OpExpungeNode * = RECORD (Msg)
    attrs - :  U.TagListPtr;  (*  R: Additional attributes *)
  END;

(**-- Library Base variable --------------------------------------------*)

CONST

  name * = "amigaguide.library";

TYPE

  AmigaGuideBasePtr* = CPOINTER TO AmigaGuideBase;
  AmigaGuideBase* = RECORD (E.Library) END;

VAR

  base* : AmigaGuideBasePtr;


(**-- Library Functions ------------------------------------------------*)

(*--- functions in V40 or higher (Release 3.1) ---*)

(* Public entries *)

LIBCALL (base : AmigaGuideBasePtr) LockAmigaGuideBase  *
  ( handle [8] : AmigaGuideContext )
  : LONGINT;
  -36;
LIBCALL (base : AmigaGuideBasePtr) UnlockAmigaGuideBase  *
  ( key [0] : LONGINT );
  -42;
LIBCALL (base : AmigaGuideBasePtr) OpenAmigaGuideA  *
  ( VAR nag [8] : NewAmigaGuide;
    attrs   [9] : ARRAY OF U.TagItem )
  : AmigaGuideContext;
  -54;
LIBCALL (base : AmigaGuideBasePtr) OpenAmigaGuide  *
  ( VAR nag [8]  : NewAmigaGuide;
    attrs   [9]..: U.Tag )
  : AmigaGuideContext;
  -54;
LIBCALL (base : AmigaGuideBasePtr) OpenAmigaGuideAsyncA  *
  ( VAR nag [8] : NewAmigaGuide;
    attrs   [0] : ARRAY OF U.TagItem )
  : AmigaGuideContext;
  -60;
LIBCALL (base : AmigaGuideBasePtr) OpenAmigaGuideAsync  *
  ( VAR nag [8]  : NewAmigaGuide;
    attrs   [0]..: U.Tag )
  : AmigaGuideContext;
  -60;
LIBCALL (base : AmigaGuideBasePtr) CloseAmigaGuide  *
  ( cl [8] : AmigaGuideContext );
  -66;
LIBCALL (base : AmigaGuideBasePtr) AmigaGuideSignal  *
  ( cl [8] : AmigaGuideContext )
  : E.ULONG;
  -72;
LIBCALL (base : AmigaGuideBasePtr) GetAmigaGuideMsg  *
  ( cl [8] : AmigaGuideContext )
  : AmigaGuideMsgPtr;
  -78;
LIBCALL (base : AmigaGuideBasePtr) ReplyAmigaGuideMsg  *
  ( amsg [8] : AmigaGuideMsgPtr );
  -84;
LIBCALL (base : AmigaGuideBasePtr) SetAmigaGuideContextA  *
  ( cl    [8] : AmigaGuideContext;
    id    [0] : E.ULONG;
    attrs [1] : ARRAY OF U.TagItem )
  : BOOLEAN;
  -90;
LIBCALL (base : AmigaGuideBasePtr) SetAmigaGuideContext  *
  ( cl    [8] : AmigaGuideContext;
    id    [0] : E.ULONG;
    attrs [1] ..: U.Tag )
  : BOOLEAN;
  -90;
LIBCALL (base : AmigaGuideBasePtr) SendAmigaGuideContextA  *
  ( cl    [8] : AmigaGuideContext;
    attrs [0] : ARRAY OF U.TagItem )
  : BOOLEAN;
  -96;
LIBCALL (base : AmigaGuideBasePtr) SendAmigaGuideContext  *
  ( cl    [8]  : AmigaGuideContext;
    attrs [0]..: U.Tag )
  : BOOLEAN;
  -96;
LIBCALL (base : AmigaGuideBasePtr) SendAmigaGuideCmdA  *
  ( cl    [8] : AmigaGuideContext;
    cmd   [0] : ARRAY OF CHAR;
    attrs [1] : ARRAY OF U.TagItem )
  : BOOLEAN;
  -102;
LIBCALL (base : AmigaGuideBasePtr) SendAmigaGuideCmd  *
  ( cl    [8]  : AmigaGuideContext;
    cmd   [0]  : ARRAY OF CHAR;
    attrs [1]..: U.Tag )
  : BOOLEAN;
  -102;
LIBCALL (base : AmigaGuideBasePtr) SetAmigaGuideAttrsA  *
  ( cl    [8] : AmigaGuideContext;
    attrs [9] : ARRAY OF U.TagItem )
  : LONGINT;
  -108;
LIBCALL (base : AmigaGuideBasePtr) SetAmigaGuideAttrs  *
  ( cl    [8]  : AmigaGuideContext;
    attrs [9]..: U.Tag )
  : LONGINT;
  -108;
LIBCALL (base : AmigaGuideBasePtr) GetAmigaGuideAttr  *
  ( tag         [0] : U.Tag;
    cl          [8] : AmigaGuideContext;
    VAR storage [9] : ARRAY OF SYS.BYTE )
  : LONGINT;
  -114;
LIBCALL (base : AmigaGuideBasePtr) LoadXRef  *
  ( lock [8] : D.FileLockPtr;
    name [9] : ARRAY OF CHAR )
  : LONGINT;
  -126;
LIBCALL (base : AmigaGuideBasePtr) ExpungeXRef  * ();
  -132;
LIBCALL (base : AmigaGuideBasePtr) AddAmigaGuideHostA  *
  ( h     [8] : U.HookPtr;
    name  [0] : ARRAY OF CHAR;
    attrs [9] : ARRAY OF U.TagItem )
  : AmigaGuideHostPtr;
  -138;
LIBCALL (base : AmigaGuideBasePtr) AddAmigaGuideHost  *
  ( h     [8]  : U.HookPtr;
    name  [0]  : ARRAY OF CHAR;
    attrs [9]..: U.Tag )
  : AmigaGuideHostPtr;
  -138;
LIBCALL (base : AmigaGuideBasePtr) RemoveAmigaGuideHostA  *
  ( hh    [8] : AmigaGuideHostPtr;
    attrs [9] : ARRAY OF U.TagItem )
  : LONGINT;
  -144;
LIBCALL (base : AmigaGuideBasePtr) RemoveAmigaGuideHost  *
  ( hh    [8]  : AmigaGuideHostPtr;
    attrs [9]..: U.Tag )
  : LONGINT;
  -144;
LIBCALL (base : AmigaGuideBasePtr) GetAmigaGuideString  *
  ( id [0] : LONGINT )
  : E.STRPTR;
  -210;

(**-- Library Base variable --------------------------------------------*)

(**-----------------------------------*)
PROCEDURE* CloseLib ();

BEGIN (* CloseLib *)
  IF base # NIL THEN E.base.CloseLibrary (base) END
END CloseLib;

(**-----------------------------------*)
PROCEDURE OpenLib * (mustOpen : BOOLEAN );

BEGIN (* OpenLib *)
  IF base = NIL THEN
    base :=
      SYS.VAL (
        AmigaGuideBasePtr,
        E.base.OpenLibrary (name, E.libraryMinimum));
    IF base # NIL THEN SYS.SETCLEANUP (CloseLib)
    ELSIF mustOpen THEN HALT (100)
    END;
  END;
END OpenLib;

BEGIN
  base := NIL
END AmigaGuide.