
Kurze Beschreibung der Modulschnittstelle fr CAB.APP (bzw. HTML.APP).
----------------------------------------------------------------------

Kontakt
-------
Alexander Clauss
Stresemannstr. 44
D-64297 Darmstadt      email: aclauss@rbg.informatik.th-darmstadt.de


Hinweise
--------
Das Programm CAB.APP besitzt keine Routinen um online auf das Internet
(bzw. das WWW) zuzugreifen. Der Grund ist: ich habe kein Modem und knnte
diese Routinen deshalb auch nicht testen. ber ein externes Modul
(CAB.OVL) knnen diese Routinen aber nachgerstet werden.

Die Schnittstelle soll auch unter Single-TOS funktionieren, daher werden
keine speziellen Mint-Features verwendet. Sollte sie fr bestimmte Module
unbrauchbar sein, bitte ich um Nachricht.

Die Schnittstelle kann an einigen Stellen noch erweitert und verbessert
werden. Sie enthlt wahrscheinlich auch ein paar berflssige Aufrufe, die
zwar in irgendwelchen Alpha-Version eines Moduls benutzt wurden, aber
jetzt hchst wahrscheinlich niemand mehr benutzen wird (z.B. begin_pexec(),
end_pexec() wurden bentigt, weil fr die ersten Versuche ein ZMODEM
Programm gestartet wurde, um Daten zu bertragen).

Vorschlge zur Verbesserung bzw. Erweiterung der Modul-Schnittstelle werden
gerne entgegengenommen.


Aufruf des Moduls
-----------------
Es gibt (zur Zeit) zwei Mglichkeiten:

1) CAB.APP ld das Modul CAB.OVL mit pexec(3,...). Das Modul wird dadurch
   in den Speicher geladen und reloziert, aber nicht gestartet. Nun sucht
   CAB.APP nach einer 'magic number' im Speicherbereich des Moduls. Direkt
   hinter dieser Zahl erwartet es die Adresse der Initialisierungs-Routine
   des Moduls. Nun springt es diese Funktion an und bergibt die Adressen
   zweier Strukturen. Eine dieser Strukturen enthlt Funktionen, die
   CAB.APP zur Verfgung stellt, und die vom Modul verwendet werden knnen.
   Die andere Struktur mu von der Initialisierungs-Funktion des Moduls
   ausgefllt werden, diese mu dort die Adressen der Modul-Funktionen
   eintragen damit sie von CAB.APP aufgerufen werden knnen.

   Die 'magic number' ist:
        0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536552
   CAP.APP gibt dabei nach dem Laden des Moduls mit mshrink() den vom
   Modul nicht bentigten Speicher frei.

   Muss das Modul diesen mshrink() Aufruf selbst durchfhren, dann mu die
   'magic number' flgendermaen lauten:
        0x48744d6c, 0x2f577757, 0x2d42724f, 0x77536572

   Nachteil dieser Methode: Der Startupcode des Moduls wird nicht
       ausgefhrt (und deshalb sind alle Aufrufe von Funktionen die im
       Startupcode initialisiert werden, nicht mglich (betrifft z.B.
       printf()).

2) Als Alternative ist es auch mglich, da ein Programm, welches die
   Funktionen des Moduls bereitstellt, CAB.APP selbst nachstartet. In
   diesem Fall mu CAB.APP mit dem Parameter -initfunc=<adresse> in der
   Kommandozeile aufgerufen werden. <adresse> steht dabei fr die Adresse
   der init-Funktion (in dezimaler Darstellung, also nicht(!) Hexadezimal).
   Die 'Magic Number' wird in diesem Falle nicht bentigt.

   Unter Mint mit Memory-Protection mu man dann die Memory-Flags auf
   GLOBAL setzen (bei beiden Programmen), da beide Programme Routinen des
   jeweils anderen aufrufen.


Aufrufkonventionen
------------------
Alle Funktionsparameter mssen auf dem Stack bergeben werden. Das
Ergebnis wird im Register D0 bergeben. Variablem vom Typ 'long' sind 32
Bit breit, vom Typ 'int' 16 Bit. Bit 0 bezeichnet das niederwertigste Bit

Das bedeutet fr Pure C: Alle Funktionen mit 'cdecl' deklarieren
Das bedeutet fr den gcc: Die Option '-mshort' verwenden.


Beschreibung der Funktionen des Moduls
--------------------------------------
In 'modul.h' und 'init.c' (zusammengestellt von Stephane Boisson) befindet
sich schon ein Grundgerst eines Moduls. Fr Aufrufmethode 1) mu man
in main() (welches nie ausgefhrt wird) einige Dummy-Aufrufe machen, damit
der Compiler nicht alle Funktionen wegoptimiert.

Das Modul CAB.OVL kann folgende Funtionen implementieren:

   init_module, get_url_info, get_version, get_url
   post, restore_module, mailto, get_url_if_modified
   
Nur zwei dieser Funktionen (init_module, get_url) mssen implementiert werden, 
alle anderen sind nicht zwingend notwendig, aber fr volle online-Funktions-
fhigkeit durchaus wichtig. 



long init_module(url_methods_t *out, browser_info_t *in, char *path);
---------------------------------------------------------------------
Diese Funktion ruft CAB.APP direkt nach dem Start auf. In dieser Funktion
mu sich das Modul initialisieren.

   'path'   enthlt den Pfad in dem sich das Modul befindet
            (abgeschlossen durch '\').
   'in'     enthlt alle Funktionen, die CAB-APP dem Modul zur
            Verfgung stellt.
   'out'    In diese Struktur mssen die Adressen der Modul-
            Funktionen eingetragen werden. Fr Funktionen, die
            nicht implementiert sind, setzt man 0L als Adresse
            ein.

Als Ergebnis mu die Funktion einen Bitvektor (long) zurckliefern, indem
die vom Modul untersttzten WWW-Protokolle eingetragen wurden.

Konstanten fr die Protokolle (mit 'Oder' zu veknpfen):
   SUPPORT_HTTP, SUPPORT_FTP, SUPPORT_GOPHER, SUPPORT_WAIS,
   SUPPORT_MAILTO, SUPPORT_NNTP, SUPPORT_TELNET

Falls das Modul weitere Programme mit pexec(0) startet, mu man zustzlich
noch folgendes in den Bitvektor eintragen:
   SUPPORT_PEXEC

Falls die Initialisierung nicht klappt mu 0L zurck geliefert werden;
weitere Aufrufe von Modul-Funktionen finden dann nicht mehr statt.

Wichtig fr Aufrufmethode 1 (siehe oben):
Die Adresse dieser Funktion mu direkt hinter der 'Magic number' irgendwo
im Programm- oder Datenbereich untergebracht werden, damit CAB.APP diese
Funktion findet und aufrufen kann (gilt nur wenn das Modul mit pexec(3)
von CAB.APP geladen wurde).

Wichtig fr Aufrufmethode 2 (siehe oben):
Das Modul wird als Programm gestartet, und startet dann selbst CAB.APP,
wobei es die Adresse dieser Funktion als Parameter bergibt:

   Parameter:  -initfunc=<adresse>


void restore_module(void);
--------------------------
Wird aufgerufen, bevor sich CAB.APP beendet. Die Funktion sollte hier allen
angeforderten Speicher freigeben, geffnete Datein schliessen, etc.

Diese Funktion mu nicht implementiert werden, wenn nichts dauerhaft
reserviert wurde (Dateihandles, Speicher, etc.)


void get_version(char **authorp, long *versionp, long *datep);
--------------------------------------------------------------
Erfragt Informationen ber Autor, Version und Datum des Moduls. Alle
Angaben werden im 'About...' Dialog von CAB.APP angezeigt.

   'authorp'   Autor und Kontaktadresse. Maximal 4 Zeilen zu je 30 Zeichen.
               Als Zeilentrenner bitte '|' verwenden.
   'versionp'  Version im BCD-Format. Oberes Wort enthlt die Haupt-
               versionsnummer, das untere Wort die Unterversionsnummer.
   'datep'     Datum im BCD-Format: 0xYYYYMMDD (Jahr, Monat, Tag)

Diese Funktion mu nicht implementiert werden.


long get_url_info(char *url, long *timep, long *sizep, char *type);
-------------------------------------------------------------------
ber das Dokument mit der URL-Adresse 'url' sollen einige Informationen
ermittelt werden. Diese Funktion wird aufgerufen um zu entscheiden, ob ein
Dokument berhaupt aus dem Internet angefordert werden mu, oder ob das
Dokument im Cache noch aktuell ist.

   'url'    URL-Adresse des Dokuments, ber das Informationen gefordert
            werden.
   'timep'  Hier mu das Datum (letzte Modifikation) eingetragen werden.
            Im UNIX-Format: Sekunden seit 1970 (01.01.1970,00:00 => *timep=0)
   'sizep'  Hier soll die Lnge (in bytes) des Dokuments eingetragen werden.
            -1L wenn nicht feststellbar.
   'type'   Der Dateityp im MIME-Format. Der String-Puffer bietet Platz fr
            250 Zeichen. Oder Leerstring '\0', falls unbekannt.

Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine
GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer.

Diese Funktion mu nicht implementiert werden. Ist fr optimale Cache-
Verwaltung aber sinnvoll.


long get_url(char *url, char *filename);
----------------------------------------
Das Modul soll das Dokument mit der URL-Adresse 'url' aus dem Internet
holen und in der Datei 'filename' speichern. 'filename' enthlt schon den
kompletten Zugriffspfad; Verzeichnisse mssen nicht mehr angelegt werden.
Das Dateidatum sollte korrekt auf das Datum der letzten Modifikation des
Dokuments gesetzt werden. Nur so funktioniert die Cache-Verwaltung in
Verbindung mit der 'get_url_info(..)' Funktion.

Sollte das Ziel der URL-Adresse ein Verzeichnis sein (z.B. beim ftp, gopher
Protokoll) sollte das Ergebnis als HTML-Datei abgelegt werden (falls das
nicht schon automatisch im HTML-Format ankommt???). Wenn man die
Verzeichniseintrge mit Icons versieht, kann man die folgenden eingebauten
Icons benutzen:

   #define BULLET_FOLDER "<img src=\"internal-gopher-menu\">"
   #define BULLET_TEXT "<img src=\"internal-gopher-text\">"
   #define BULLET_IMAGE "<img src=\"internal-gopher-image\">"
   #define BULLET_MOVIE "<img src=\"internal-gopher-movie\">"
   #define BULLET_SOUND "<img src=\"internal-gopher-sound\">"
   #define BULLET_INDEX "<img src=\"internal-gopher-index\">"
   #define BULLET_BINARY "<img src=\"internal-gopher-binary\">"
   #define BULLET_UNKNOW "<img src=\"internal-gopher-unknown\">"

Als Ergebnis leifert die Funktion 0, wenn alles geklappt hat, sonst eine
GEMDOS, XBIOS, BIOS, Mint bzw. MintNet Fehlernummer.

Wird die URL-Adresse umgeleitet (Image-Maps,...) muss man dies CAB.APP
mit der Funktion  'new_url' (siehe unten) mitteilen.


long post(char *url,char *content, char *enctype, char *filename);
------------------------------------------------------------------
Die Daten ('content') einer FORM-Umgebung werden mit 'POST' an 'url'
geschickt. Die Daten liegen im 'enctype' (MIME) Format vor. Zur Zeit ist
nur 'application/x-www-form-urlencoded' mglich.
Eventuell zurckgeschickte Daten sollen in 'filename' gespeichert werden.

Sollten die zurckgeschickten Datein eine neue URL-Adresse besitzen, dann
unbedingt die Funktion 'new_url' (siehe unten) benutzen.


long mailto(char *url, char *subject, char *filename);
------------------------------------------------------
Die Datei 'filename' soll als Mail verschickt werden. 'url' bezeichnet
die Email-Adresse des Empfngers als URL, 'subject' ist der Betreff.
Als Ergebnis liefert die Funktion 0, falls alles geklappt hat, sonst -1.


long get_url_if_modified(char *url, char *filename, long *timep);
-----------------------------------------------------------------
Kombination aus get_url und get_url_info. CAB versucht zuerst mit
get_url_if_modified auf die Daten zuzugreifen, falls diese Funktion 
implementiert ist. Ist diese Funktion nicht implementiert, werden
get_url und get_url_info verwendet.

CAB.OVL muss die url nur dann aus dem WWW holen und unter dem Dateinamen
filename abspeichern, wenn die Daten neuer aus timep (Unix-Format) sind.
Sind die Daten nicht neuer, sollte die Funktion ohne Fehlermeldung (d.h. 
mit 0) zurckkehren. Da hier, im Gegensatz zur Funktion get_url_info(), 
nicht die Lnge der Daten zurckgeliefert werden kann (die Funktion kehrt 
ja erst dann zurck, wenn alle Daten komplett geladen wurden), sollte die
Lnge ber 'msg_status(STATUS_DATALENGTH,len)' an CAB bermittelt werden.




Funktionen, die CAB.APP anbietet (browser_info_t Struktur)
----------------------------------------------------------
Das Modul kann direkt AES-Aufrufe machen, im Allgemeinen ist das aber nicht
ntig.

void (*aes_crystal)(void)
-------------------------
Fr AES-Aufrufe bitte die folgenden Arrays ausfllen und dann 'aes_crystal'
aufrufen.

  int *aes_control;
  int *aes_global;
  int *aes_intin;
  int *aes_intout;
  long *aes_addrin;
  long *aes_addrout;

void (*aes_messages)(int *msg)
------------------------------
Besitzt das Modul eine eigene AES-Event-Behandlung, sollte bei jedem
MU_MESAG-Event (bzw. jedem Event, welches nicht das Modul betrifft) der
Ereignis-Puffer mit dieser Funktion an CAB.APP weitergereicht werden, damit
dieses z.B. Redraws ausfhren kann.



void (*msg_error)(long errno)
-----------------------------
Gibt eine Fehlermeldung aus (im Statusfenster von CAB.APP). Erlaubt sind alle
GEMDOS, BIOS und MintNet Fehlernummern.


void (*msg_status)(long no,long val)
------------------------------------
Gibt eine der folgenden Statusmeldngen aus:

   no=1: 'connecting host',                val unbenutzt
   no=2: 'receive data',                   val=Anzahl der empfangenen Bytes
   no=3: 'waiting for response',           val unbenutzt
   no=4: 'resolving host',                 val unbenutzt
   no=5: 'sending request',                val unbenutzt
   no=6: 'Text formatieren...',            val unbenutzt
   no=7: 'Bild laden...',                  val unbenutzt
   no=8: 'Starte Programm...',             val unbenutzt
   no=9: 'Formatiere Tabelle...',          val unbenutzt
   no=10: 'Warte auf Daten (Timeout: #)',  val=Timeout
   no=11: 'Konvertiere Bild...',           val unbenutzt

   no=12345  val=Lnge der Daten
          Hiermit kann das OVL jederzeit die Lnge der zu bertragenden 
          Daten an CAB bermitteln. Dies ist insbesondere dann wichtig,
          wenn get_url_if_modified aufgerufen wurde, da CAB hier nicht
          die Lnge der Daten zurckgeliefert bekommt.
             

Weitere Meldungen knnen bei Bedarf aufgenommen werden. Nummern bitte mit
mir absprechen.


long (*aes_events)(long msec)
-----------------------------
Mit dieser Funktion gibt man CAB.APP die Gelegenheit auf AES-Ereignisse zu
reagieren. CAB.APP ruft evnt_multi(MU_MESAG|MU_TIMER|MU_KEYBD,..) auf,
wobei 'msec' als Zeit fr das Timer-Event benutzt wird. Mit einem kleinen
Wert fr 'msec' kehrt die Funktion also schnell wieder zurck. CAB.APP ver-
arbeitet zunchst alle eigenen Events (z.B. Redraw, Fenster verschieben,..)
und prft, ob der Benutzer die Aktion abbrechen will. Als Ergebnis liefert
die Funktion:

          0     -> kein MU_MESAG-Event. Weitermachen.
         -1     -> Aktion abbrechen (Benutzer hat ESC gedrckt).
   alles andere -> Pointer auf ein GEM-Message-Array (int msg[8]) mit den
                   Daten des aktuellen MU_MESAG-Ereignises.


long (*alert_box)(long button,long msg)
---------------------------------------
Eine Alertbox wird dargestellt. 'button' ist der Default-Button und 'msg'
die Nummer eines Textes. Die Funktion liefert 0, wenn ein Fehler auftrat
(falsche msg Nummer), sonst den ausgewhlten Button.
Mgliche Texte (msg):

   msg=0 : "[2][Aktion abbrechen?][Ja|Nein]"
   msg=1 : "[1][Transaktion war erfolgreich][Abbruch]"
   msg=2 : "[1][Transaktion war nicht|erfolgreich][Abbruch]"

Weitere Texte knnen bei Bedarf aufgenommen werden. Nummer bitte mit mir
absprechen.


void (*begin_pexec)(void)    void (*end_pexec)(void)
----------------------------------------------------
Mit diesen beiden Funktionen mu das Starten eines Programmes durch pexec(0)
geklammert werden. CAB.APP wird sich unter Single-TOS beim AES korrekt ab-
und danach wieder anmelden.


int (*clear_cache)(long size)
-----------------------------
Sorgt dafr, da mindestens 'size' Bytes im Cache frei sind. Gegebenenfalls
werden einige Dateien (auf die am lngsten nicht mehr zugegriffen wurde)
aus dem Cache entfernt. Konnte soviel Platz geschaffen werden, liefert die
Funktion 0 sonst -1.
size=0 bedeutet, da der komplette Cache gelscht wird.


int (*new_url)(char *url,char **file)
-------------------------------------
Wenn eine Dokument-Anfrage auf eine neue URL-Adresse umgeleitet wird (z.B.
Imagemaps, cgi-Scripts), mu man dies dem Hautprogramm mit dieser Funktion
mitteilen. Es ermittelt dann einen neuen Dateinamen 'file', unter dem die
Daten dann abgespeichert werden mssen. Liefert die Funktion als Ergebnis 0
soll das Dokument jetzt endgltig geholt werden, liefert sie als Ergebnis
-1, dann mu das Dokument nicht mehr geholt werden, da es sich schon im
Cache befindet.


int (*ask_user)(long msg,char **answer)
---------------------------------------
Wenn der Benutzter bestimmte Angaben machen mu, bevor fortgefahren werden
kann (z.B. bei geschtzten Dokumenten mit Passwortabfrage), kann man diese
Angaben hiermit anfordern.
'msg' ist die Nummer des Textes, der angezeigt wird, 'answer' ist der
String, der vom Benutzer eingegeben wurde. Das Resultat ist 1 wenn der
Benutzter OK gedrckt hat, 0 fr Abbruch und -1 bei einem Fehler (falsche
'msg'-Nummer). Der String 'answer' wird beim nchsten Aufruf dieser Funktion
wieder berschrieben daher, wenn ntig, umkopieren.
Mglicher Werte fr 'msg':

   msg=0 : Dokument geschtzt, Name (bzw. Kennung) eingeben
   msg=1 : Dokument geschtzt, Passwort eingeben

Weitere Texte knnen bei Bedarf definiert werden. Bitte mit mir absprechen.


long basepage
-------------
Adresse der Modul-Basepage. Nur gltig, wenn Modul mit pexec(3) gestartet
wurde.

int *reloadflag
---------------
Zeiger auf ein integer. Der Integerwert ist 1, wenn der Benutzer 'Neu laden'
(Reload) ausgewhlt hat, sonst 0. Kann dazu verwendet werden, eventuell gecachete
Informationen/Daten zu benutzen oder nicht.


long version
------------
Versionsnummer von CAB im ASCII format. Beispiel: V1.30 wre 0x30313330.


proxy_url *proxy
----------------
Zeiger auf die folgende Struktur:

struct {
   char *ftp_proxy;
   char *http_proxy;
   char *wais_proxy;
   char *gopher_proxy;
   char *news_proxy;
   char *no_proxy;
   char *smtp_server;
   char *nntp_server;
} proxy_url

Das OVL sollte diese Struktur innerhalb der init-Funktion mit
Default-Werten ausfuellen. CAB hat fuer jeden String schon Speicher
(126 Bytes) reserviert. CAB wird diese Eintrge ndern, falls der
Benutzter neue Eintrge in CAB bestimmt. Das OVL sollte deshalb
vor dem Download der Daten diese Eintrge erneut inspizieren.


void online(int state)
----------------------
Sollte vom OVL immer dann aufgerufen werden, wenn die Internet-
verbindung aufgebaut bzw. abgebrochen wird. Besteht die Verbindung
mu state=1 sonst state=0 bergeben werden. Diese Funktion darf
ab CAB-Version 1.41 aufgerufen werden (d.h.: version>=0x30313431).
Wird diese Funktion vom OVL nicht aufgerufen, geht CAB davon aus,
da die Internetverbindung besteht. Sinnvoll einsetzbar ist die
Funktion allerdings erst, wenn das CAB.OVL in einem eigenen Thread
nderungen des Online-Statuses berprft, da das OVL von CAB nur
bei Bedarf aufgerufen wird.


