Wenn ein OLGA-Client ein Dokument öffnet (z.B. mit "Datei - Neu" oder "Datei - Öffnen..."), muß dem OLGA-Manager folgende Message geschickt werden. Die Gruppenkennung bezeichnet dabei eine beliebige, aber innerhalb des Clients eindeutige Zahl, mit der der Client und der Server das Dokument eindeutig identifizieren können - schließlich ist es möglich, daß eine Datei innerhalb eines Clients mehrfach, nur in verschiedenen Dokumenten, eingebunden ist. Falls ein Client nur ein Dokument gleichzeitig bearbeiten kann (IdeaList hat z.B. immer nur eine Datei geladen), kann man hier eine Null übergeben.
OLGA_OPENDOC (Client -> Manager) msg[0] $123b (4667) msg[1] apID msg[2] 0 msg[3] 0 msg[4] 0 msg[5] Gruppenkennung msg[6] 0 msg[7] 0Schließt ein Client ein Dokument, wird dem Manager folgende Message geschickt, die automatisch alle Links mit der entsprechenden Gruppenkennung gelöscht. Wichtig: Beim Programmende darf man diese Message nicht verschicken, da OLE_EXIT alle Gruppenkennungen freigibt!
OLGA_CLOSEDOC (Client -> Manager) msg[0] $123c (4668) msg[1] apID msg[2] 0 msg[3] 0 msg[4] 0 msg[5] Gruppenkennung msg[6] 0 msg[7] 0Das eigentliche "Object Linking" geschieht mit folgender Message. Wenn der Client eine fremde Datei in eines seiner Dokumente einbettet, muß er sich intern den Dateinamen mit absolutem Pfad merken und mit OLGA_LINK einen Link darauf setzen. Wird die Datei von einem OLGA-Server verändert, erhält der Client dann eine OLGA_UPDATED-Message.
Möchte der Client nicht nur ein Linking, sondern auch ein Embedding realisieren, muß er nicht nur den Dateinamen der eingebetteten Datei im Dokument speichern, sondern auch die gesamte Datei. Das bläht die Dokumente zwar ziemlich auf, hat aber den Vorteil, daß man solche Dateien sehr einfach weitergeben kann, da _alle_ Daten im Dokument gespeichert sind.
Wird ein Dokument geladen, das eingebettete Dateien enthält, muß der Client nach dem Laden und Öffnen des Dokuments (siehe OLGA_OPENDOC) auf alle eingebetteten Objekte, die ja mit ihrem Dateinamen gespeichert wurden, einen Link auf die zugehörige Datei setzen. Wird ein Dokument auf einem fremden System geöffnet, bei dem die eingebetteten Dateien nicht auf Platte vorhanden sind, kann ein Linking-Client diese Dateien auch nicht anzeigen - dem Anwender sollte dies z.B. durch ein leeres Rechteck o.ä. im Dokument angezeigt werden. Ein Embedding-Client hat alle notwendigen Daten im Dokument gespeichert und kann z.B. die Grafiken (allgemeiner: Objekte) trotzdem anzeigen.
Beim Doppelklick auf ein eingebettetes Objekt sollte die entsprechende Datei per OLGA_START (s.u.) geöffnet werden, damit der Anwender diese Datei im zugehörigen Server bearbeiten kann. Ein Embedding-Client sollte vorher noch prüfen, ob die zu öffnende Datei überhaupt vorhanden ist. Im negativen Fall sollte er die im Dokument gespeicherte Datei auf Platte ablegen (unter einem automatisch generierten temporären Namen), den alten Link mit OLGA_UNLINK löschen und einen neuen Link auf die temporäre Datei setzen.
OLGA_LINK
(Client -> Manager)
msg[0] $123d (4669)
msg[1] apID
msg[2] 0
msg[3]
+ Pointer auf den Dateinamen, der überwacht werden soll (incl.
absolutem Pfad)
msg[4]
msg[5] Gruppenkennung (siehe OLGA_OPENDOC)
msg[6] 0
msg[7] 0
Als Bestätigung verschickt der Manager folgende Message:
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3]
+ exakt dieselben Werte von OLGA_LINK
msg[4]
msg[5] Gruppenkennung
msg[6] 0=Fehler, sonst: Link eingerichtet
msg[7] OLGA_LINK
Soll die Überwachung für eine Datei beendet werden,
muß der Client dem Manager folgende Message schicken. Beim
Schließen eines Dokuments sollte stattdessen allerdings
OLGA_CLOSEDOC verwendet werden, und beim Beenden der
Client-Applikation werden die Links mit OLE_EXIT automatisch
gelöscht.
OLGA_UNLINK
(Client -> Manager)
msg[0] $123e (4670)
msg[1] apID
msg[2] 0
msg[3] Pointer auf den Dateinamen (incl. absolutem Pfad), der nicht mehr
+ überwacht werden soll (muß exakt mit der Zeichenkette aus OLGA_LINK
msg[4] übereinstimmen)
msg[5] Gruppenkennung
msg[6] 0
msg[7] 0
Als Bestätigung erhält der Client folgende Message:
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3]
+ exakt dieselben Wert von OLGA_UNLINK
msg[4]
msg[5] Gruppenkennung
msg[6] 0=Fehler, sonst: Link entfernt
msg[7] OLGA_UNLINK
Mit der nächsten Message wird ein Client darüber
informiert, daß eine seiner eingebetteten Dateien
verändert wurde. Ein Linking-Client muß daraufhin die
Datei neu anzeigen, ein Embedding-Client sollte die Datei
zusätzlich komplett neu in sein Dokument laden.
OLGA_UPDATED
(Manager -> Client)
msg[0] $123f (4671)
msg[1] manID
msg[2] 0
msg[3]
+ Pointer auf den Dateinamen (incl. absolutem Pfad) der Datei,
die verändert wurde
msg[4]
msg[5] reserviert
msg[6] reserviert
msg[7] Gruppenkennung
Wenn ein Server eine Datei umbenannt oder verschoben hat, erhält
der Client folgende Message. Sie dient nur dazu, daß der Client
seine interne Referenz aktualisiert, d.h. das Dokument muß
_nicht_ neu gezeichnet werden!
OLGA_RENAMELINK
(Manager -> Client)
msg[0] $1240 (4672)
msg[1] manID
msg[2] 0
msg[3]
+ Pointer auf den alten Dateinamen incl. absolutem Pfad
msg[4]
msg[5]
+ Pointer auf den neuen Dateinamen incl. absolutem Pfad
msg[6]
msg[7] Gruppenkennung
Als Antwort auf OLGA_RENAMELINK muß der Client an den Manager
folgende Message schicken, damit letzterer seine Referenz
aktualisiert und unnötigen Speicherplatz freigibt (der Client
muß dazu einfach nur die Messagenummer austauschen und die
erhaltene Message zurücksenden). Unterbleibt diese Antwort, ist
der entsprechende Link "tot", kann also nicht mehr überwacht
werden.
OLGA_LINKRENAMED
(Client -> Manager)
msg[0] $1241 (4673)
msg[1] apID
msg[2] 0
msg[3]
+ Pointer auf den alten Dateinamen incl. absolutem Pfad
msg[4]
msg[5]
+ Pointer auf den neuen Dateinamen incl. absolutem Pfad
msg[6]
msg[7] Gruppenkennung
Wenn eine Datei dem Client plötzlich nicht mehr zur
Verfügung steht (weil sie z.B. vom Server gelöscht wurde),
wird dies vom Manager mit folgender Message mitgeteilt. Der Client
kann daraufhin z.B. den Benutzer informieren oder per Fileselectbox
eine andere Datei auswählen lassen.
Außerdem muß der Client den jetzt ungültigen Link mit der normalen OLGA_UNLINK-Message auflösen, wobei als Pointer die Werte von OLGA_LINKBROKEN übergeben werden.
OLGA_LINKBROKEN
(Manager -> Client)
msg[0] $1245 (4677)
msg[1] manID
msg[2] 0
msg[3]
+ Pointer auf den Dateinamen incl. absolutem Pfad
msg[4]
msg[5] Gruppenkennung
msg[6] 0
msg[7] 0
Für Clients bietet der Manager eine einfache Möglichkeit,
passende Server nachzustarten bzw. aufzurufen. Dazu wird (bei
OLS_TYPE und OLS_EXTENSION) die Datei OLGA.INF ausgewertet (siehe
Beschreibung in der OLGA-Dokumentation). Zunächst wird der darin
gefundene Server im Speicher gesucht und bei Erfolg mit VA_START
(siehe Gemini- bzw. Thing-Dokumentation) aufgerufen. Ansonsten wird
das Programm unter MultiTOS bzw. MagiC mit shel_write()
nachgestartet.
OLGA_START
(Client -> Manager)
msg[0] $1246 (4678)
msg[1] apID
msg[2] 0
msg[3] eine der OLS-Konstanten (s.u.)
msg[4]
+ Angaben, welches Programm bzw. welcher Programmtyp gestartet
msg[5] werden soll (abhängig von [3], s.u.)
msg[6]
+ Pointer auf Kommandozeile (i.A. nur die zu ladende Datei) oder NULL
msg[7]
OLS_TYPE = $0001 [4]=0, in [5] steht ein XAcc-Programmtyp
OLS_EXTENSION = $0002 in [4]+[5] steht eine Extension (z.B. ".GEM")
OLS_NAME = $0003 in [4]+[5] steht ein Pointer auf den absoluten
Dateinamen der zu startenden Applikation
Als Bestätigung erhält man folgende Message:
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3] OLS-Konstante von OLGA_START
msg[4]
+ exakt dieselben Wert von OLGA_START
msg[5]
msg[6] 0=Fehler, sonst: Server gestartet
msg[7] OLGA_START
Um die Kommandozeile leichter freigeben zu können, erhält
man außerdem noch eine zweite Message, falls für die
Kommandozeile nicht NULL übergeben wurde.
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3] 0 (im Unterschied zur obigen OLGA_ACK-Message!)
msg[4]
+ exakt dieselben Wert von OLGA_START [6]+[7]
msg[5]
msg[6] 0=Fehler, sonst: Server gestartet
msg[7] OLGA_START
Hier geht es weiter.