Plugin-Schnittstelle - CONZEPT 16

Plugin-Schnittstelle - CONZEPT 16 Erstellung eine Plugin-Anwendung in CONZEPT 16

• Siehe: Plugin-Schnittstelle

Um den Entwicklungsprozess einer Plugin-Anwendung in CONZEPT 16 zu vereinfachen wurde eine API entwickelt, welche grundlegende Funktionen für das Versenden und Kodieren/Dekodieren von Nachrichten zu Verfügung stellt.

info

Die API wurde in CONZEPT 16 entwickelt und ist Bestandteil der CodeLibrary.

Überblick

1. Core-API
   1. Instanziierung
   2. Erstellung einer Instanz
   3. Schließen einer Instanz
   4. Schließen aller Instanzen
   5. Iterieren der Instanzen
   6. Ermitteln des JobControl-Objektes
   7. Senden einer Nachricht
   8. Empfangen einer Nachricht
   9. Eindeutige Antwortkennung generieren
   10. Informationen zur API ermitteln
   11. Ermitteln des zuletzt aufgetretenen Fehlers
2. Converter-API
   1. Authentifizierungsaufforderung erwarten
   2. Authentifizierungsaufforderung beantworten
   3. Erstellen eines neuen PluginCommand-Handles
   4. Löschen eines PluginCommand-Handles
   5. Leeren eines PluginCommand-Handles
   6. Name des Plugin-Kommandos ermitteln
   7. Name eines Plugin-Kommandos überprüfen
   8. Ermitteln des Kommando-Typs
   9. Überprüfung auf einen bestimmten Kommando-Typ
   10. Ermitteln der Antwortkennung (fortlaufende Nummer)
   11. Ermitteln des zuletzt aufgetretenen Fehlers
   12. Setzen von Argumenten
   13. String-Argument
   14. 32-bit vorzeichenbehaftetes ganzzahliges Argument
   15. Logisches Argument
   16. String-Argument als Memory-Objekt
   17. Rückgabe-Argument
   18. Argument für Resultat des Designer-Befehls
   19. Ermitteln von Argumenten
   20. Argument nach Name ermitteln
   21. Argument nach Nummer ermitteln
   22. Ermitteln der Anzahl der Argumente
   23. Ermitteln der Länge eines Argumentes
   24. Argumentwert vom Typ _TypeAlpha ermitteln
   25. Argumentwert eines Base64 kodierten Argumentes vom Typ _TypeAlpha ermitteln
   26. Argumentwert vom Typ _TypeInt ermitteln
   27. Argumentwert vom Typ _TypeLogic ermitteln
   28. String-Argument als Memory-Objekt ermitteln
   29. Kodieren / dekodieren von Kommandos
   30. Kodieren eines Plugin-Kommandos in das Nachrichtenformat
   31. Dekodieren eines Plugin-Kommandos aus dem Nachrichtenformat
   32. Empfangen und dekodieren einer Nachricht
   33. Kodieren und Senden einer Nachricht

---

Core-API

Die Core-API stellt Basisfunktionen für das Senden und Empfangen von Befehlen und Ereignissen zur Verfügung und besteht aus den Modulen Plugin.Core sowie Plugin.Core.Inc. Plugin.Core.Inc deklariert alle Funktionen, die Bestandteil der Core-API sind. Das Modul Plugin.Core implementiert diese Funktionalität und sollte nicht verändert werden, da ansonsten eine Kompatibilität mit zukünftigen Versionen der API nicht gewährleistet werden kann.

info

Funktionen, die nicht Bestandteil der Core-API sind (also solche, die nur in Plugin.Core jedoch nicht in Plugin.Core .Inc definiert sind, sollten nicht aufgerufen werden, da sich die Implementierung in Zukunft ändern kann.

Instanziierung

Eine Plugin-Anwendung kann aus ein oder mehreren Instanzen bestehen, die getrennt voneinander fungieren. Jede Plugin-Instanz verfügt über eine eigene Verbindung zum Designer und einen eigenen Thread zum Empfang von Designer-Ereignissen bzw. Befehlen.

Erstellung einer Instanz

Eine Plugin-Instanz wird über die Funktion Plugin.Core:InstanceNew erstellt:

declare Plugin.Core:InstanceNew
(
  aPluginPort  : word;    // Plugin port to connect to.
  opt aTimeout : int;     // Timeout (connect/read/write) in milliseconds.
  opt aFrame   : handle;  // Frame to receive EvtJob (Client only).
)
: int;

Der Funktion muss beim Aufruf der Port übergeben werden, auf dem sich die Instanz mit dem Designer verbinden soll. Die Funktion wartet solange, bis die Verbindung hergestellt werden konnte oder das angegebene Timeout erreicht wurde. Im Argument aFrame kann ein Frame-Handle übergeben werden. Diesem werden über das Ereignis EvtJob neu eingetroffene Nachrichten signalisiert.

info

Die Angabe des Frame-Handles ist nur im Standard- bzw. Advanced-Client erlaubt. Bei Verwendung des SOA-Service muss hier NULL übergeben werden (alternativ kann das Argument auch ganz weggelassen werden).

Bei erfolgreicher Verbindungsherstellung wird eine Instanz-ID (> 0) zurückgegeben, die für alle nachfolgenden Befehle der Core-API verwendet werden kann. Bei nicht erfolgreicher Verbindungsherstellung wird einer der folgenden Fehlercodes (< 0) zurückgeliefert.

• _ErrPluginCorePlatform: Die Funktion wurde nicht vom Standard-, Advanced- oder SOA-Service aus aufgerufen.
• _ErrPluginCoreLimitReached: Das Limit für Plugin-Instanzen (derzeit 10) ist bereits erreicht.
• _ErrPluginCoreConnectTimeout: Es konnte keine Verbindung hergestellt werden (Timeout wurde erreicht).
• _ErrPluginCoreSckConnect: Es konnte keine Verbindung hergestellt werden (Socket-Fehler / Plugin.Core:GetLastError() liefert den aufgetretenen Fehlercode).
• _ErrPluginCoreInternal: Interner Fehler aufgetreten.

Schließen einer Instanz

Terminiert sich die Plugin-Anwendung oder wird die Instanz nicht mehr benötigt, dann sollte diese durch Aufruf der Funktion Plugin.Core:InstanceClose geschlossen werden.

declare Plugin.Core:InstanceClose
(
  aID : int;          // Plugin instance ID to close.
);

Im Argument aID muss die von InstanceNew zurückgelieferte Instanz-ID angegeben werden. Die Funktion baut die Verbindung zum Designer ab und terminiert den Empfangs-Thread. Die Funktion hat keinen Rückgabewert.

Schließen aller Instanzen

Zum Schließen aller Instanzen einer Plugin-Anwendung kann die Funktion Plugin.Core:InstanceCloseAll verwendet werden.

declare Plugin.Core:InstanceCloseAll
();

Iterieren der Instanzen

Zum Iterieren der geöffneten Instanzen steht die Funktion Plugin.Core:InstanceGet zur Verfügung.

declare Plugin.Core:InstanceGet
(
  aMode           : int; // _InstanceModeGetFirst, _InstanceModeGetNext
  opt aInstanceID : int; // Reference in case of _InstanceModeGetNext
)
: int;

Im Argument aMode wird angegeben, was durchgeführt werden soll:

• _InstanceModeGetFirst: liefert die erste vorhandene Instanz zurück. Die Angabe von aInstanceID ist nicht notwendig.
• _InstanceModeGetNext: liefert ausgehend von aInstanceID die nächste vorhandene Instanz zurück.

Der Befehl liefert 0, wenn keine erste bzw. nächste Instanz existiert, ansonsten eine Instanz-ID (> 0).

Ermitteln des JobControl-Objektes

Zur Ermittlung des von einer Instanz verwendeten JobControl-Objektes kann die Funktion Plugin.Core:GetJobControl verwendet werden.

declare Plugin.Core:GetJobControl
(
  aReceiverType    : int;    // Type of receiver.
  aReceiver        : int;    // Job control object / instance id.
)
: handle;                    // Handle to job control object.

Das Argument aReceiverType kennzeichnet den Inhalt von aReceiver.

• _ReceiverByJobControl: aReceiver enthält das JobControl-Objekt.
• _ReceiverByInstanceID: aReceiver enthält die Instanz-ID.

Der Rückgabewert liefert im erfolgreichen Fall das JobControl-Objekt (> 0) oder einen Wert < 0 im Fehlerfall.

• _ErrPluginCoreInit: Es wurde noch kein InstanceNew() durchgeführt.
• _ErrPluginCoreNoInstance: Bei dem angegebenen Wert ( aReceiver ) handelt es sich nicht um eine gültige Instanz-ID.

Senden einer Nachricht

Zum Senden von Nachrichten steht die Funktion Plugin.Core:SendLine zur Verfügung.

declare Plugin.Core:SendLine
(
  aInstanceID      : int;    // Instance ID.
  aMem             : handle; // Memory object containing content to send.
  opt aWaitTimeout : int;    // > 0 = sync mode (wait time in milli seconds for reply).
  opt aMemReply    : handle; // Reply data in case of sync mode (aWaitTimeout > 0).
)
: int;                      // Result error code.

Die Funktion sendet eine Nachricht, deren Inhalt in einem Memory-Objekt enthalten ist. Das Nachrichtenformat ist hierbei wie unter (Nachrichtenaustausch) definiert.

Im Argument aInstanceID muss die Instanz-ID angegeben werden, welche die Nachricht versenden soll. Über das optionale Argument (aWaitTimeout) kann auf die Antwort einer Nachricht vom Designer gewartet werden. In diesem Fall muss auch das Argument (aMemReply) angegeben werden, welches den Inhalt der Antwort aufnimmt.

info

Das Versenden von Nachrichten über die Converter-API vereinfacht das Versenden nochmals, da hier ein zu sendender Befehl samt Argumente definiert werden kann.

Fehlerwerte:

• _ErrPluginCoreInit: Es wurde noch kein InstanceNew() durchgeführt.
• _ErrPluginCoreNoInstance: Bei dem angegebenen Wert ( aInstanceID ) handelt es sich nicht um eine gültige Instanz-ID.
• _ErrPluginCoreSckWriteFailed: Fehler beim Schreiben auf den Socket ( Plugin.Core:GetLastError() liefert den aufgetretenen Fehlercode).
• _ErrPluginCoreNoData: Nur bei synchronem Versenden, wenn keine Daten vorhanden sind.
• _ErrData: Unbekanntes MsxItem empfangen.
• _ErrPluginCoreThreadTerm: Plugin-Thread hat sich beendet. Dies ist der Fall, wenn die Socket-Verbindung im Designer beendet wurde, z. B. weil der Designer vom Anwender beendet wurde (den genauen Fehlercode liefert Plugin.Core:GetLastError() ).
• _ErrPluginCoreReceive: Fehler beim Empfangen der Daten, Fehlercode liefert Plugin.Core:GetLastError() .

Empfangen einer Nachricht

Es gibt zwei Arten, wie überprüft werden kann, ob eine neue Nachricht vorliegt:

(a) Benachrichtigung durch Ereignis EvtJob.

Dies ist die bevorzugte Art im CONZEPT 16-Standard- oder Advanced-Client. Hierzu muss beim Aufruf von InstanceNew() ein Frame-Deskriptor angegeben werden.

(b) Polling

Es kann in definierten Zeitabständen nach neuen Ereignissen "gepollt" werden. Diese Möglichkeit kann im SOA-Service genutzt werden.

Zum Empfangen und Auslesen von Daten steht die Funktion Plugin.Core:ReceiveLine() zur Verfügung.

declare Plugin.Core:ReceiveLine
(
  aReceiverType    : int;    // Type of receiver.
  aReceiver        : int;    // Job control object / instance id.
  aTargetMem       : handle; // Memory object containing received line.
  var aInstanceID  : int;    // Regarding Instance ID.
  opt aWaitTimeout : int;    // Wait for message in milliseconds (0 = no wait).
  opt aWaitReply   : logic;  // Wait for reply message. (API-Ver 1.1)
)
: int;                       // Instance ID or error code.

Der Funktion muss im ersten Argument eine der folgenden Konstanten angegeben werden:

• _ReceiverByJobControl: Bei aReceiver handelt es sich um ein JobControl-Objekt . Dies ist sinnvoll, wenn der Aufruf der Funktion aus dem Ereignis EvtJob heraus stattfindet. Dem Ereignis wird bereits das JobControl-Objekt übergeben und kann somit direkt an diese Funktion weitergegeben werden.
• _ReceiverByInstanceID: Bei aReceiver handelt es sich um eine Instanz-ID. Dies ist sinnvoll, wenn nach neuen Nachrichten gepollt werden soll.

Die Funktion liefert die empfangene Nachricht in aTargetMem zurück. Das Memory-Objekt muss zuvor mit MemAllocate ( _MemAutoSize ) angelegt worden sein. Im Argument aInstanceID wird die übermittelte Instanz-ID zurückgegeben. Diese kann zu Verifikationszwecken herangezogen werden.

Das optionale Argument aWaitTimeout wird nur beim pollen verwendet, um eine gewisse Zeitspanne in Millisekunden auf das Eintreffen einer Nachricht zu warten. Im Ereignis EvtJob braucht das Argument nicht angegeben werden, da in diesem Fall bereits mindestens eine Nachricht empfangen wurde.

Mit dem optionalen Argument aWaitReply kann auf eine Antwort des Designers gewartet werden. Als aReceiverType muss _ReceiverByInstanceID sein. Die Funktion wird intern von der Funktion Plugin.Core:SendLine() aufgerufen.

Rückgabewerte:

• _ErrOK: Es wurde eine Nachricht in aTargetMem hinterlegt.
• _ErrPluginCoreInit: Es wurde noch kein InstanceNew() durchgeführt.
• _ErrPluginCoreNoInstance: Bei dem angegebenen Wert ( aReceiver ) handelt es sich nicht um eine gültige Instanz-ID.
• _ErrPluginCoreArgumentInvalid: aWaitReply ist gesetzt und aReceiverType ist nicht _ReceiverByInstanceID , oder aWaitReply ist nicht gesetzt und aReceiverType wurde ein ungültiger Wert angegeben.
• _ErrPluginCoreNoData: Es keine Daten vorhanden sind.
• _ErrPluginCoreThreadTerm: Plugin-Thread hat sich beendet. Dies ist der Fall, wenn die Socket-Verbindung im Designer beendet wurde, z. B. weil der Designer vom Anwender beendet wurde (den genauen Fehlercode liefert Plugin.Core:GetLastError() ).
• _ErrPluginCoreReceive: Fehler beim Empfangen der Daten, Fehlercode liefert Plugin.Core:GetLastError() .

Eindeutige Antwortkennung generieren

Mit der Funktion Plugin.Core:NextSerial() kann eine eindeutige Antwortkennung generiert werden. Diese Funktion steht ab API-Version 1.1 zur Verfügung.

declare Plugin.Core:NextSerial
()
: bigint;                    // Next serial number (> 0) or error code (< 0).

Im Fehlerfall liefert die Funktion den Wert _ErrPluginCoreInit. In diesem Fall wurde die Initialisierung der Core-API noch nicht durchgeführt.

Informationen zur API ermitteln

Mit der Funktion Plugin.Core:ApiInfo() können Informationen der API abgefragt werden. Bei Übergabe eines ungültigen Modus wird eine leere Zeichenkette zurückgeliefert.

declare Plugin.Core:ApiInfo
(
  aMode : int;            // Type of information to retrieve
)
: alpha;

Folgende Konstanten können in aMode angegeben werden.

• _ApiVersion: Version der API als Zeichenkette. Derzeit wird hier '1.1.00' zurückgegeben.
• _ApiVersionCompare: Es wird die Version als Zeichenkette zurückgegeben, die für eine einfachere Versionsprüfung verwendet werden kann. Derzeit wird hier '010100' zurückgegeben. (API-Ver 1.1)

Ermitteln des zuletzt aufgetretenen Fehlers

Zu einigen Fehlercodes können die nativen Fehlercodes ermittelt werden, die von den Funktionen der Core-API gesetzt werden. Hierzu dient die Funktion Plugin.Core:GetLastError(). Bei der Rückgabe von 0 ist kein Fehlercode vorhanden.

declare Plugin.Core:GetLastError
()
: int;

Converter-API

Zum Kodieren und Dekodieren von Nachrichten (wie unter Nachrichtenaustausch beschrieben) gibt es die Converter-API. Diese baut auf die Core-API auf und vereinfacht die Erstellung von Plugin-Befehlen und Ereignissen. Die API stellt einen abstrakten Datentyp PluginCommand bereit. Ein PluginCommand wird durch einen Deskriptor abgebildet.

Die Converter-API ist in den Modulen Plugin.Converter und Plugin.Converter.Inc enthalten.

Authentifizierungsaufforderung erwarten

Die Funktion wartet auf die Nachricht Designer.Auth, die vom Designer zur Plugin-Anwendung gesendet wird, damit diese sich authentifiziert.

declare Plugin.Converter:ReceiveAuth
(
  aReceiverType    : int;    // (in)  Type of receiver.
  aReceiver        : int;    // (in)  Job control object / instance id.
  var aSerial      : bigint; // (out) Serial number.
  var aUser        : alpha;  // (out) User name
  opt aWaitTimeout : int;    // (in)  Maximum wait time in milli seconds.
)
: int;

Die Argumente aReceiverType, aReceiver und aWaitTimeout haben dieselbe Bedeutung wie unter Plugin.Core:ReceiveLine beschrieben. Liefert die Funktion _ErrOk, wird in aSerial die vom Designer erwartete Antwortkennung zurückgegeben. In aUser wird der Name des Benutzers zurückgegeben, für den die Authentifizierung erfolgen soll.

Authentifizierungsaufforderung beantworten

Die Funktion sendet die Antwort auf die Authentifizierungsaufforderung, die durch die Funktion Plugin.Converter:ReceiveAuth empfangen wurde.

declare Plugin.Converter:ReplyAuth
(
  aInstanceID          : int;         // Instance ID.
  aSerial              : bigint;      // Serial number.
  aPluginName          : alpha(40);   // Plugin short name.
  var aPassword        : alpha;       // Password (C16 charset).
  opt aWaitTimeout     : int;         // Maximum wait time in milli seconds.
  opt aDescriptiveName : alpha(4096); // Plugin descriptive name. (API-Ver 1.1)
  opt aDescription     : alpha(4096); // Plugin description. (API-Ver 1.1)
)
: int;

In aSerial wird die empfangene Antwortkennung übergeben.

In aPluginName wird ein Name für die Plugin-Anwendung übergeben. Der Name wird für Einträge, die das Plugin betreffen, im Anwendungslog des Designers verwendet. Der Name muss mindestens ein Zeichen und darf maximal 40 Zeichen umfassen und kann keine Steuerzeichen (< ASCII 32) sowie '?' und '\' enthalten. Er darf auch nicht nur aus Leerzeichen bestehen.

In aPassword muss das zum Benutzer gehörende Plugin-Kennwort übergeben werden.

In aWaitTimeout wird die maximale Zeitspanne in Millisekunden übergeben, die gewartet wird.

aDescriptiveName enthält einen Anzeigename für die Plugin-Anwendung. Dieser Name wird im Plugin-Menü des Designers angezeigt, wenn die Anwendung dort einen Menüeintrag erstellt.

aDescription enthält eine kurze Beschreibung der Plugin-Anwendung. Das Argument wird z. Zt. nicht ausgewertet.

Rückgabewert:

• _ErrOk: Authentifizierung erfolgreich.
• _ErrRights: Authentifizierung fehlgeschlagen.

Erstellen eines neuen PluginCommand-Handles

Zum Erstellen eines Plugin-Kommandos steht die Funktion Plugin.Converter:CreateCmd() zur Verfügung.

declare Plugin.Converter:CreateCmd
(
  opt aKind             : int;
  opt aName             : alpha(4096);
  opt aSerial           : bigint;
)
: handle;

Im ersten Argument wird die Art des Kommandos übergeben:

• sPluginCmdKindEvt: Es soll ein Ereignis generiert werden ( EVT ).
• sPluginCmdKindCmd: Es soll ein Befehl generiert werden ( CMD ).
• sPluginCmdKindRet: Es soll eine Antwort generiert werden ( RET ).

Im optionalen Argument aName wird der Name des Kommandos angegeben. Bei der Angabe von sPluginCmdKindRet sollte das Argument nicht angegeben werden, da das RET-Kommando keinen Namen besitzt und sich ausschließlich auf die fortlaufende Nummer (aSerial) bezieht.

Mit der Funktion Plugin.Core:NextSerial kann eine eindeutige Antwortkennung für aSerial generiert werden.

Die Funktion liefert einen Deskriptor auf ein PluginCommand zurück. Der Deskriptor muss mit Plugin.Converter:DeleteCmd() freigegeben werden, wenn er nicht mehr benötigt wird.

Löschen eines PluginCommand-Handles

declare Plugin.Converter:DeleteCmd
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
);

Die Funktion löscht ein durch Plugin.Convert:CreateCmd() erstelltes Kommando. In aPluginCmd muss das zu löschende Handle angegeben werden.

Leeren eines PluginCommand-Handles

Mit der Funktion Plugin.Converter:ClearCmd() kann ein PluginCommand-Handle für die Wiederverwendung geleert bzw. neu definiert werden.

declare Plugin.Converter:ClearCmd
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  opt aKind         : int;
  opt aName         : alpha(4096);
  opt aSerial       : bigint;
);

In aPluginCmd muss ein Handle auf ein mit Plugin.Converter:CreateCmd() generiertes PluginCommand übergeben werden.

Name des Plugin-Kommandos ermitteln

Der Name des Plugin-Kommandos kann mit der Funktion Plugin.Convert:GetCmdName() ermittelt werden.

declare Plugin.Converter:GetCmdName
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: alpha;

Name eines Plugin-Kommandos überprüfen

Mit der Funktion Plugin.Converter:IsCmdName() kann der Name eines Plugin-Kommandos auf Gleichheit (ohne Berücksichtigung von Groß-/Kleinschreibung) geprüft werden.

declare Plugin.Converter:IsCmdName
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aCmdName          : alpha(4096);    // Command name to compare.
)
: logic;

Ermitteln des Kommando-Typs

Mit der Funktion Plugin.Converter:GetCmdKind() kann der Typ eines Kommandos ermittelt werden.

declare Plugin.Converter:GetCmdKind
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: int;

Rückgabewert:

• sPluginCmdKindEvt: Ereignis
• sPluginCmdKindCmd: Befehl
• sPluginCmdKindRet: Antwort

Überprüfung auf einen bestimmten Kommando-Typ

Die folgenden Funktionen stehen für die Überprüfung auf einen bestimmten Kommando-Typ zur Verfügung:

declare Plugin.Converter:IsCmdKindEvt
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: logic;

declare Plugin.Converter:IsCmdKindCmd
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: logic;

declare Plugin.Converter:IsCmdKindRet
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: logic;

Ermitteln der Antwortkennung (fortlaufende Nummer)

Mit Plugin.Converter:GetCmdSerial() kann die im Kommando gesetzte Antwortkennung ermittelt werden. Ist der Rückgabewert 0, dann besitzt das Kommando keine Antwortkennung.

declare Plugin.Converter:GetCmdSerial
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: bigint;

Ermitteln des zuletzt aufgetretenen Fehlers

Zu einigen Fehlercodes können die nativen Fehlercodes ermittelt werden, die von den Funktionen der Converter-API gesetzt werden. Hierzu dient die Funktion Plugin.Converter:GetLastError(). Bei der Rückgabe von 0 ist kein Fehlercode vorhanden.

declare Plugin.Converter:GetLastError
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
)
: int;

Setzen von Argumenten

Zum Setzen von Argumenten und deren zugehörigen Werten gibt es je nach Datentyp unterschiedliche Funktionen.

String-Argument

Mit der Funktion Plugin.Converter:AddArgStr() wird einem Plugin-Kommando ein String-Argument hinzugefügt.

declare Plugin.Converter:AddArgStr
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Argument name.
  aValue            : alpha(4096);    // Argument value.
  aValueCharset     : int;            // Charset of value.
  opt aReturnArg    : logic;          // Function / Return argument.
);

Der Name des Argumentes muss im Parameter aName übergeben werden. Sein Wert wird im Argument aValue übergeben. aValueCharset gibt den Zeichensatz an, in dem aValue kodiert ist:

• sPluginArgStrC16: CONZEPT 16-Zeichensatz
• sPluginArgStrISO: ANSI-Zeichensatz
• sPluginArgStrUtf8: UTF-8 -Zeichensatz

Über das optionale Argument aReturnArg kann angegeben werden, ob das Argument in die Liste der Rückgabe-Argumente (true) eingefügt werden soll oder nicht (false). Letzteres ist der Default-Fall.

32-bit vorzeichenbehaftetes ganzzahliges Argument

declare Plugin.Converter:AddArgInt
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Argument name.
  aValue            : int;            // Argument value.
  opt aReturnArg    : logic;          // Function / Return argument.
);

Analog zur Funktion AddArgStr(), nur dass ein Argument vom Type _TypeInt generiert wird.

Logisches Argument

declare Plugin.Converter:AddArgLogic
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Argument name.
  aValue            : logic;          // Argument value.
  opt aReturnArg    : logic;          // Function / Return argument.
);

Analog zur Funktion AddArgStr(), nur dass ein Argument vom Type _TypeLogic generiert wird.

String-Argument als Memory-Objekt

Diese Funktion steht ab API-Version 1.1 zur Verfügung.

declare Plugin.Converter:AddArgMem
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Argument name.
  aValue            : handle;         // Argument value (copies memory object).
  opt aMemCnvMode   : int;            // Convert option for MemCnv.
  opt aReturnArg    : logic;          // Function / Return argument.
);

Die Funktion nimmt in aValue den Deskriptor eines Memory-Objektes entgegen. Der Inhalt des Memory-Objektes wird kopiert. Binäre Inhalte müssen konvertiert werden, so dass keine Steuerzeichen etc. enthalten sind. Hierfür gibt es die Option aMemCnvMode mit der eine der Optionen des CONZEPT 16-Befehls MemCnv () angegeben werden kann. Durch Angabe von _MemEncBase64 wird der Inhalt des kopierten Memory-Objektes nach Base-64 kodiert und somit übertragen werden kann.

Rückgabe-Argument

Die Funktion Plugin.Converter:AddArgRet() generiert ein Rückgabe-Argument in der Form <name>=?.

declare Plugin.Converter:AddArgRet
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Argument name.
);

Argument für Resultat des Designer-Befehls

Die Funktion Plugin.Converter:AddExecResult() fügt dem Kommando ein Argument ExecResult hinzu. Dieses wird bei der Rückantwort vom Designer gesetzt und gibt Aufschluss über Fehler bei der Ausführung eines Designer-Befehls. Diese Funktion steht ab API-Version 1.1 zur Verfügung.

declare Plugin.Converter:AddExecResult
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
);

Ermitteln von Argumenten

Analog zum Setzen von Argumenten werden Funktionen für das Ermitteln von Argumenten und Argumentwerte definiert.

Argument nach Name ermitteln

Die Funktion Plugin.Converter:GetArg() ermittelt ein Argument eines Plugin-Kommandos anhand seines Namens.

declare Plugin.Converter:GetArg
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument to retrieve.
  opt aRetArg       : logic;          // 'Return argument' y/n.
)
: handle;                             // Handle to CteNode object.

Es wird ein Deskriptor auf das im Kommando gespeicherte CteNode-Objekt zurückgegeben. Der Typ des Arguments kann anhand der Eigenschaft Type bestimmt und danach mit der entsprechenden Eigenschaft Value... ausgelesen werden.

Argument nach Nummer ermitteln

Die Funktion Plugin.Converter:GetArgByNum() ermittelt ein Argument anhand seiner Position (1..Anzahl der Argumente). Die Position muss im Argument aArgNum übergeben werden.

declare Plugin.Converter:GetArgByNum
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aArgNum           : int;            // Argument number / one-based.
  opt aRetArg       : logic;          // 'Return argument' y/n.
)
: handle;                             // Handle to CteNode object.

Ermitteln der Anzahl der Argumente

Mit Plugin.Converter:GetArgCount() kann die Anzahl der gesetzten Argument ermittelt werden.

declare Plugin.Converter:GetArgCount
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  opt aRetArg       : logic;          // 'Return argument' y/n.
)
: int;

Ermitteln der Länge eines Argumentes

Mit Plugin.Converter:GetArgStrLen() kann die Länge eines gesetzten Argumentes vom Typ _TypeAlpha ermittelt werden. Diese Funktion steht ab API-Version 1.1 zur Verfügung.

declare Plugin.Converter:GetArgStrLen
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument.
  opt aRetArg       : logic;          // 'Return argument' y/n.
)
: int;

Rückgabewerte:

• >= 0: Länge des Inhaltes. Ist das Argument nicht vom Typ _TypeAlpha , wird 0 zurückgegeben.
• _ErrUnavailable: Das Argument mit dem Name aName ist im Kommando aPluginCmd nicht vorhanden.

Argumentwert vom Typ _TypeAlpha ermitteln

Die Funktion Plugin.Converter:GetArgStr() ermittelt den Wert eines Argumentes vom Typ _TypeAlpha. Falls das angegebene Argument (aName) nicht vom Type _TypeAlpha ist, wird der Fehlercode _ErrType zurückgegeben.

declare Plugin.Converter:GetArgStr
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument to retrieve.
  var aValue        : alpha;          // Value of argument (UTF-8).
  opt aRetArg       : logic;          // 'Return argument' y/n. (API-Ver 1.1)
)
: int;

Rückgabewerte:

• _ErrOK: Durchführung erfolgreich.
• _ErrUnavailable: Das Argument mit dem Name aName ist im Kommando aPluginCmd nicht vorhanden.
• _ErrType: Das Argument aName ist nicht vom Typ _TypeAlpha .

Argumentwert eines Base64 kodierten Argumentes vom Typ _TypeAlpha ermitteln

Die Funktion Plugin.Converter:GetArgStrDecB64() ermittelt den Wert eines Argumentes vom Typ _TypeAlpha. Falls das angegebene Argument (aName) nicht vom Type _TypeAlpha ist, wird der Fehlercode _ErrType zurückgegeben. Diese Funktion steht ab API-Version 1.1 zur Verfügung.

declare Plugin.Converter:GetArgStrDecB64
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument to retrieve.
  var aValue        : alpha;          // Value of argument (UTF-8).
  opt aRetArg       : logic;          // 'Return argument' y/n.
)
: int;

Rückgabewerte:

• _ErrOK: Durchführung erfolgreich.
• _ErrUnavailable: Das Argument mit dem Name aName ist im Kommando aPluginCmd nicht vorhanden.
• _ErrType: Das Argument aName ist nicht vom Typ _TypeAlpha .
• _ErrOutOfMemory: Speicheranforderungsfehler.

Argumentwert vom Typ _TypeInt ermitteln

Die Funktion Plugin.Converter:GetArgInt() ermittelt den Wert eines Argumentes vom Typ _TypeInt. Falls das angegebene Argument (aName) nicht vom Type _TypeInt ist, wird der Fehlercode _ErrType zurückgegeben.

declare Plugin.Converter:GetArgInt
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument to retrieve.
  var aValue        : int;            // Value of argument.
  opt aRetArg       : logic;          // 'Return argument' y/n. (API-Ver 1.1)
)
: int;

Rückgabewerte:

• _ErrOK: Durchführung erfolgreich.
• _ErrUnavailable: Das Argument mit dem Name aName ist im Kommando aPluginCmd nicht vorhanden.
• _ErrType: Das Argument aName ist nicht vom Typ _TypeInt .

Argumentwert vom Typ _TypeLogic ermitteln

Die Funktion Plugin.Converter:GetArgLogic() ermittelt den Wert eines Argumentes vom Typ _TypeLogic. Falls das angegebene Argument (aName) nicht vom Type _TypeLogic ist, wird der Fehlercode _ErrType zurückgegeben.

declare Plugin.Converter:GetArgLogic
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument to retrieve.
  var aValue        : logic;          // Value of argument.
  opt aRetArg       : logic;          // 'Return argument' y/n. (API-Ver 1.1)
)
: int;

Rückgabewerte:

• _ErrOK: Durchführung erfolgreich.
• _ErrUnavailable: Das Argument mit dem Name aName ist im Kommando aPluginCmd nicht vorhanden.
• _ErrType: Das Argument aName ist nicht vom Typ _TypeLogic .

String-Argument als Memory-Objekt ermitteln

Die Funktion Plugin.Converter:GetArgMem() ermittelt den Wert eines Argumentes vom Typ _TypeAlpha. Falls das angegebene Argument (aName) nicht vom Type _TypeAlpha ist, wird der Fehlercode _ErrType zurückgegeben. Diese Funktion steht ab API-Version 1.1 zur Verfügung.

declare Plugin.Converter:GetArgMem
(
  aPluginCmd        : handle;         // Handle of plugin command (0 = current).
  aName             : alpha(4096);    // Name of argument to retrieve.
  var aValue        : handle;         // Value of argument as memory content.
  opt aMemCnvMode   : int;            // Convert option for MemCnv.
  opt aRetArg       : logic;          // 'Return argument' y/n.
)
: int;

In aValue muss der Deskriptor eines Memory-Objektes angegeben werden, in welches der Inhalt des Argumentes kopiert wird. Das optionale Argument aMemCnvMode kann eine, der bei MemCnv () zulässigen, Optionen sein. Der Inhalt einer Base64 kodierten Zeichenkette kann z. B. durch Angabe der Option _MemDecBase64 ermittelt werden.

Rückgabewerte:

• _ErrOK: Durchführung erfolgreich.
• _ErrUnavailable: Das Argument mit dem Name aName ist im Kommando aPluginCmd nicht vorhanden.
• _ErrHdlInvalid: Bei aValue handelt es sich nicht um einen gültigen Deskriptor eines Memory-Objektes.
• _ErrType: Das Argument aName ist nicht vom Typ _TypeAlpha .
• _ErrOutOfMemory: Speicheranforderungsfehler.

Kodieren / dekodieren von Kommandos

Kodieren eines Plugin-Kommandos in das Nachrichtenformat

Um eine Nachricht an den Designer zu senden, muss das PluginCommand-Handle zunächst in das Nachrichtenformat (siehe Nachrichtenaustausch) umgewandelt (kodiert) werden. Zum Kodieren steht die Funktion Plugin.Converter:Encode() bereit.

declare Plugin.Converter:Encode
(
  aPluginCmd        : handle;         // (in)  Handle of plugin command (0 = current).
  aOutput           : handle;         // (out) Memory object with encoded content.
)
: int;                                // Result.

Im Argument aPluginCmd wird das zu kodierende PluginCommand-Handle übergeben. Im Argument aOutput muss ein Memory-Objekt übergeben werden, welches den kodierten Nachrichteninhalt aufnimmt. Das Memory-Objekt muss zuvor mit MemAllocate ( _MemAutoSize ) generiert worden sein.

Dekodieren eines Plugin-Kommandos aus dem Nachrichtenformat

Zum Umwandeln einer Nachricht vom Designer in ein PluginCommand-Handle steht die Funktion Plugin.Converter:Decode() bereit. Diese nimmt eine Nachricht (die z. B. durch Plugin.Core:ReceiveLine() ermittelt wurde) und dekodiert diese in ein PluginCommand-Handle.

declare Plugin.Converter:Decode
(
  aInput            : handle;         // (in)     Memory object with encoded content.
  aPluginCmd        : handle;         // (in/out) Handle to decoded plugin command.
)
: int;                                // Result.

aPluginCmd muss ein PluginCommand-Handle sein, dass zuvor mit Plugin.Converter:CreateCmd() angelegt wurde. Bei erfolgreicher Verarbeitung wird der Wert _ErrOk zurückgegeben, ansonsten ein Fehlercode < 0.

Empfangen und dekodieren einer Nachricht

Mit der Funktion Plugin.Converter:ReceiveCmd() kann ein Plugin-Kommando empfangen werden. Die Funktion ruft hierzu Plugin.Core:ReceiveLine() und anschließend Plugin.Converter:Decode() auf.

declare Plugin.Converter:ReceiveCmd
(
  aReceiverType    : int;             // (in)  Type of receiver.
  aReceiver        : int;             // (in)  Job control object / instance id.
  aPluginCmd       : handle;          // (in)  Received plugin command.
  var aInstanceID  : int;             // (out) Regarding Instance ID.
  opt aWaitTimeout : int;             // (in)  Wait for message in milliseconds (0 = no wait).
)
: int;                                // Instance ID or error code.

Die Argumente aReceiverType, aReceiver, aInstanceID und aWaitTimeout haben dieselbe Bedeutung wie unter Plugin.Core:ReceiveLine() beschrieben. Das Plugin-Kommando aPluginCmd muss zuvor mit Plugin.Converter:CreateCmd() generiert werden und wird von der Funktion entsprechend der empfangenen Nachricht dekodiert.

Kodieren und Senden einer Nachricht

Die Funktion Plugin.Converter:SendCmd() wandelt ein PluginCommand-Handle in eine Nachricht um und sendet diese zum Designer.

declare Plugin.Converter:SendCmd
(
  aInstanceID      : int;             // (in) Instance ID.
  aPluginCmd       : handle;          // (in) Plugin command to send.
  opt aWaitTimeout : int;             // (in) > 0 = sync mode (wait time in milli seconds for reply).
  opt aReplyCmd    : handle;
)
: int;

Bei erfolgreicher Verarbeitung wird _ErrOk zurückgegeben, ansonsten ein Wert < 0.