API - Application Interface English ..... A-1 Deutsch ..... A-2 Français .... A-3 A-1 English BASICS GoldED offers a message-based application interface (API). This interface may be used by third party applications to register with GoldED: after having registered by sending the API command to GoldED's ARexx port they will recieve notify messages from GoldED. Depending on these messages they can take approbiate actions (e.g. close their windows if GED is about to close its screen, indicating this by sending API_ACTION_HIDE messages to all registered clients). HOW TO RUN CLIENTS Clients are launched during startup of GoldED (use the API list of the config menu if you want to add or remove clients). The name of GoldED's port is passed as HOST=... argument. The client is expected to register with GED by sending the API command to this port, thus providing a port for notifys and requesting notify classes (clients may select a subset of the available notifys). Shortly after the API client has registered with GoldED it will recieve an API_ACTION_SHOW notify of the API_CLASS_SCREEN class (if the client has requested API_CLASS_SCREEN events), telling the client to open its windows. This notify (and any other notify) includes a variety of informations about the editor's current state (including text of current line, window dimensions and screen name). RESTRICTIONS After a client has registered with GoldED it has to be able to answer notifys immediately until the API_ACTION_DIE command is recieved (the user has to WAIT for your client to complete processing). To avoid deadlock problems, you may not wait for completion of ARexx requests sent to GED using WaitPort() (thus ignoring incoming API messages). Use Wait() instead. A-2 Deutsch Grundlagen GoldED bietet externen Programmen mit dem API-Interface eine Möglichkeit, sich in die internen Abläufe des Editors einzuklinken. Ein Programm, das dieses Interface benutzt, wird im folgenden als Client bezeichnet. Das API-Interface baut wie auch ARexx auf Messages auf. Im Gegensatz zu ARexx geht die Richtung des Informationsflusses aber primär von GoldED zu den externen Programmen: der Ablauf wird durch den Editor gesteuert. Grundsätzlich kann man sich Clients wie Unterprogramme des Editors vorstellen: sie werden vom Editor "aktiviert", übernehmen die Ausführung und geben i.d.R. ein Ergebnis zurück. Die Client-Einbindung erfolgt, indem sich dieser bei GoldED mit dem ARexxBefehl API anmeldet. Dabei hat er mitzuteilen, in welchen Situationen er "aufgerufen" werden möchte und an welchem Port GoldED die entsprechende Nachricht hinterlegen soll. Tritt eine der ausgewählten Situationen auf, schickt GoldED an den angegebenen Port eine Message (Notify), die nähere Informationen (vgl. golded.h) enthält. Der Client wird diese Nachricht untersuchen, geeignete Aktionen durchführen und dann die Nachricht beantworten. Erst mit der Beantwortung fährt GoldED in seinem Programmablauf fort. Die Art der Antwort kann den weiteren Programmablauf beeinflussen. Wie werden Clients gestartet ? Benutzen Sie den API-Requester, um Clients auszuwählen. Jedes dort eingetragene Programm wird im Zuge des Editor-Startups aufgerufen. Der Name des ARexx-Ports von GED wird dem Client als (letztes) Argument HOST=... übergeben. Der Client bekommt so die Möglichkeit, sich über ARexx beim Editor anzumelden. Mit dem API-Kommando teilt er dem Editor mit, in welchen Situationen er informiert werden soll und an welchen Message-Port die Informationen verschickt werden sollen. Kurz nachdem sich der Client angemeldet hat, erhält er von GoldED eine erste API_ACTION_SHOW-Benachrichtigung (sofern der Client Informationen der API_CLASS_SCREEN angefordert hat): dies ist sein Signal, die eigenen Fenster (sofern vorgesehen) zu öffnen. Dazu benötigte Informationen wie der zu benutzende Screen kann er der Benachrichtigung entnehmen. Einschränkungen Nachdem sich ein Client über den API-Befehl erfolgreich beim Editor angemeldet hat, muss er in der Lage sein, eingehende Nachrichten unverzüglich zu bearbeiten, bis er eine API_ACTION_DIE-Benachrichtigung erhält. Wenn GoldED auf einen Client wartet, dann wartet auch der Anwender/die Anwenderin. Um DeadLock-Probleme zu vermeiden, darf niemals per WaitPort() auf abgesandte ARexx-Requests gewartet werden (GED könnte auf eine API-Reaktion des Clients warten, der Client wartet auf GoldED: das System ist blockiert). Verwenden Sie ersatzweise Wait(). A-3 Français FONDEMENTS GoldED propose un interface application (API), basé sur les messages. Cet interface peut être utilisée par des applications pour s'enregistrer à GoldED: après s'être enregistrées en envoyant la commande API au port ARexx de GoldED, celles-ci recevront les messages de notification de GoldED. Selon ces messages, ces applications peuvent alors accomplir les actions appropriées (par exemple fermer leurs fenêtres si GED va fermer son écran, indiquant cela en envoyant les messages API_ACTION_HIDE à tous ses clients enregistrés). COMMENT DEMARRER DES CLIENTS Les clients sont lancés lors du démarrage de GoldED (utilisez la liste API du menu Config si vous voulez ajouter ou retirer des clients). Le nom du port de GoldED est passé comme argument . Le client doit s'enregistrer à GED en envoyant la commande API à ce port, fournir en plus un port pour les notifications et demander les classes de notifications (les clients peuvent sélectionner une partie des notifications disponibles). Dès que le client API a été enregistré à GoldED, celui-ci reçoit une notification API_ACTION_SHOW de la classe API_CLASS_SCREEN (si le client a demandé les événements API_CLASS_SCREEN), lui disant d'ouvrir ses fenêtres. Cette notification (et toutes les autres notifications) inclut une quantité d'informations sur l'état actuel de l'éditeur (incluant le texte sur la ligne actuelle, les dimensions de la fenêtre et le nom de l'écran). RESTRICTIONS Dès qu'un client a été enregistré à GoldED, celui-ci doit être capable de répondre immédiatement aux notifications jusqu'à ce que la commande API_ACTION_DIE soit reçue (l'utilisateur devra ATTENDRE la fin du traitement par le client). Pour éviter des problèmes de temps mort (deadlock), vous ne devez pas attendre la fin des requêtes ARexx envoyées à GED en utilisant WaitPort() (en ignorant en plus les messages API arrivants). Utilisez Wait() à la place.