Plugin-Schnittstelle - Funktionsweise

• Siehe: Plugin-Schnittstelle, Befehle, Ereignisse, Plugin-Schnittstelle in CONZEPT 16

Die Plugin-Funktionalität des Designers wird aktiviert, wenn in der Konfigurationsdatei der Eintrag PluginPort mit einer gültigen Portnummer (<= 65535) eingetragen ist. Die Portnummer kann beim Start über die Kommandozeilenoption /c16PluginPort oder auch über die Umgebungsvariable C16PluginPort definiert werden.

Zusätzlich zu dem Port muss bei dem jeweiligen Benutzer des Designers noch ein Plugin-Kennwort festgelegt werden.

Der Designer baut nach dem Starten und vor dem Laden des Benutzerprofils eine passive Socket-Verbindung über die angegebene Portnummer auf. Danach können sich ein oder mehrere Plugin-Clients mit dem Designer verbinden.

Da die Kommunikation von Plugin-Client und Designer über ein textbasiertes Protokoll abläuft, können Plugin-Clients in jeder Sprache (C++, C#, etc.) entwickelt werden, die Sockets unterstützen. Für die Entwicklung von Plugin-Clients in CONZEPT 16 wurde eine Core-API entwickelt, welche die Entwicklung für Plugin-Anwendungen vereinfacht.

info

Fehler, die bei der Kommunikation auftreten werden im Anwendungsprotokoll des Designers festgehalten.

Überblick

1. Nachrichtenaustausch

   1. Genereller Aufbau des Nachrichtenformates

      1. Antwortkennung
      2. Befehlskennung
      3. Befehlsname
      4. Argumentliste
      5. Rückgabe-Argumentliste

   2. Beispiele

      1. Befehl
      2. Ereignis
      3. Antwort

2. Verbindungsherstellung

3. Authentifikation

Nachrichtenaustausch

Der Nachrichtenaustausch von Plugin-Client zu Designer und umgekehrt läuft über ein textbasiertes Nachrichtenformat. Alle Zeichenketten sind hierbei UTF-8 kodiert. Zwischen Groß- und Kleinschreibung wird nicht unterschieden (außer bei Dateninhalten).

Genereller Aufbau des Nachrichtenformates

Der Aufbau einer Nachricht hat den folgenden syntaktischen Aufbau:

[<serial> | ] <type> [<command-name>] (<arg-list>) [\[<return-arg-list>\] ]

Antwortkennung (<serial>)

Bei <serial> handelt es sich um eine fortlaufende 64-bit ganzzahlige Nummer, die mit gesendet wird, wenn eine Antwort auf ein Kommando oder ein Ereignis erwartet wird. Die Nummer fehlt, wenn keine Antwort erwartet wird.

Befehlskennung (<type>)

Es gibt drei Befehlskennungen:

• CMD: Bei der Nachricht handelt es sich um einen Befehl.
• EVT: Bei der Nachricht handelt es sich um ein Ereignis.
• RET: Bei der Nachricht handelt es sich um die Antwort auf CMD oder EVT.

Befehlsname (<command-name>)

Sofern ein Kommando (CMD) oder ein Ereignis (EVT) gesendet wird, muss ein Befehlsname angegeben sein. Dieser gibt darüber Auskunft, welches Ereignis ausgelöst, bzw. welcher Befehl durchgeführt werden soll. Der Befehlsname wird in URL-Schreibweise angegeben (siehe Befehlsbeschreibung). Befehlsnamen können neben dem Punkt (.) nur aus Buchstaben, Ziffern und dem Unterstich (_) bestehen.

Argumentliste (<arg-list>)

Die Argumentliste enthält die zum Befehl bzw. Ereignis gehörenden Argumente. Die Argumentliste kann auch leer sein. In diesem Fall muss eine leere Argumentliste () angegeben werden.

<arg-list> = [<arg-name>=<arg-value>[[,<arg-name>=<arg-value>]]]

<arg-name> bezeichnet den Argumentname. Das erste Zeichen des Arguments muss ein Buchstabe sein (A...Z). Danach können sowohl Buchstaben also auch Ziffern, sowie der Unterstrich (_) folgen.

<arg-value> enthält den Wert des durch <arg-name> angegebenen Arguments und kann folgende Werte annehmen:

<arg-value> = { <string-literal> | <number> | true | false | ? }

1. String-Literal (<string-literal>)

   Hierdurch wird eine UTF8-kodierte Zeichenkette angegeben. Diese muss in doppelten Hochkommata eingeschlossen sein.

   <string-literal> = "[[<char>]]"

   <char> ist jedes gültige UTF8-codierte Zeichen. Darüber hinaus gibt es reservierte Zeichen, die durch das Escape-Zeichen \ maskiert werden müssen:

   • \": Doppelte Hochkommata
   • \n: Zeilenvorschub (Line feed)
   • \t: Tabulatorzeichen
   • \b: Backspace
   • \f: Seitenvorschub
   • \r: Zeilenrücklauf (Carriage return)
   • \\: Backslash
   • \/: Slash

2. Nummer (<number>)

   Hierdurch wird ein positiver oder negativer ganzzahliger numerischer Wert (32-bit) angegeben.

3. Logische Werte (true, false)

   Hierdurch wird ein Argument mit einem logischen Wert (true oder false) angegeben.

4. Fragezeichen (?)

   Durch das Fragezeichen wird angegeben, dass die Rückgabe eines Argumentes mit dem angegebenen Name erwartet wird. Die Angabe ist nur in der Rückgabe-Argumentliste bei CMD bzw. EVT (nicht aber bei RET) erlaubt.

Rückgabe-Argumentliste (<return-arg-list>)

Die Rückgabe-Argumentliste ist optional und gibt an, welche Argumente als Antwort auf einen Befehl (CMD) oder ein Ereignis (EVT) erwartet werden oder bei der Antwort (RET) zurückgegeben wurden. Der Aufbau ist identisch zur Argumentliste.

Beispiele

Befehl

CMD Designer.Forms.Open (Name="MyFrame", ReadOnly=true) []

Hiermit wird der Befehl (CMD) Designer.Forms.Open zum Öffnen des Frames "MyFrame" im Read-Only-Modus definiert. Es werden keine Rückgabe-Argumente erwartet.

Ereignis

EVT Designer.Forms.CloseDone (Name="MyFrame", Type="0") []

Hiermit wird das Ereignis (EVT) Designer.Forms.CloseDone spezifiziert. Dieses Ereignis wird vom Designer ausgelöst, wenn eine Designform geschlossen wurde. Es wird auf keine Antwort des Plugin-Client gewartet (Rückgabe-Argumentliste ist leer).

Antwort

Die Plugin-Anwendung muss sich nach Aufbau der Verbindung beim Designer anmelden. Hierzu sendet der Designer folgendes Kommando: (1234 steht exemplarisch für die vom Designer generierte fortlaufende Antwortkennung.)

1234 | CMD Designer.Auth (Area="codelib", user="Alfons") [PluginName=?, Password=?]

Der Plugin-Client antwortet durch Rückgabe des entsprechenden Kommandos:

1234 | RET [PluginName="MyPlugin", Password="Password1234"]

Verbindungsherstellung

Nachdem der Designer gestartet wurde, lauscht dieser auf Verbindungen am spezifizierten Port des lokalen Rechners. Eine Plugin-Anwendung kann anschließend die Verbindung herstellen, indem diese eine Socketverbindung auf den Port des Designers herstellt.

Authentifikation

Nach Verbindungsherstellung sendet der Designer das Kommando Designer.Auth unter Angabe von Datenbankname sowie Datenbankbenutzer. Die Plugin-Anwendung muss innerhalb von 5 Sekunden auf dieses Kommando unter Angabe von Plugin-Name und Kennwort antworten.

Designer:

<serial> | CMD Designer.Auth (Area=<area-name>, User=<user-name>) [PluginName=?, Password=?]

Plugin-Anwendung:

<serial> | RET (PluginName=<plugin-name>, Password=<password>)

<serial> kennzeichnet die vom Designer automatisch vergebenene, fortlaufende Antwortkennung. Diese muss beim RET-Kommando wieder angegeben werden.

Bei erfolgreicher Anmeldung antwortet der Designer mit dem Kommando:

CMD Designer.Auth (Area=<area-name>, User=<user-name>, AccessGranted=true)

Bei nicht erfolgreicher Anmeldung wird AccessGranted=false zurückgesendet. Bei Erreichen des Timeouts von 5 Sekunden wird die Verbindung vom Designer geschlossen.

Das für die Plugin-Authentifikation notwendige Kennwort muss beim Benutzer in der Benutzerverwaltung (Seite Sicherheit) der Datenbank hinterlegt sein. Wenn das Kennwort leer ist, startet der Designer ohne Plugin-Funktionalität.

info

Fehler, die bei der Authentifizierung auftreten, werden unter Angabe des PluginName im Anwendungsprotokoll des Designers festgehalten.