CXI-Basis-Programmierreferenz / Noch zu dokumentieren /
Kommunikationsschnittstelle / EasyRPC (Header)
#ifndef CXIR_H
#define CXIR_H
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// ******************* KURZBESCHREIBUNG VON EASYRPC **********************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
//
// EINLEITUNG:
// EasyRPC ist eine sehr einfach zu verwendende Schnittstelle für
// rechnerübergreifende Funktionsaufrufe. Sie setzt auf das CXI-
// Basissystem auf, erfordert jedoch keinerlei spezielles Wissen
// darüber.
//
// Jede Funktion, die global (d.h. über Rechnergrenzen hinweg) auf-
// rufbar sein soll, wird unter einem eindeutigen Namen beim EasyRPC
// registriert. Ab diesem Zeitpunkt kann sie von jedem beliebigen
// Rechner des CXI-Systems aufgerufen werden.
//
// Der Rechner, auf dem sich die registrierte Funktion befindet, wird
// im Folgenden als Server, der Aufrufer als Client bezeichnet.
//
// Für die Arbeit mit EasyRPC werden folgende Dateien benötigt:
// - CXIR.H Header für die Client- und Serverseite
// - CXIRxAPI.LIB Import Library (x = W (Windows), O (OS/2))
// - CXIRxAPI.DLL Dynamic Link Library (x = W (Windows), O (OS/2))
//
//
// ALLE EASYRPC-FUNKTIONEN IM ÜBERBLICK:
// 1. GLOBAL
// - ERPCIsReady -- Testen ob EasyRPC verfügbar ist
// - ERPCLoad -- EasyRPC Laden
// - ERPCStart -- Neue Version von ERPCLoad (mit Systemname)
// - ERPCOpen -- Neue Version von ERPCLoad (mit Option)
// - ERPCClose -- EasyRPC beenden
// - ERPCShutDown -- EasyRPC beenden
// - ERPCGetServerName -- Ermittelt den Servernamen
// - ERPCGetLocalName -- Ermittelt des eigenen Namens
// - ERPCSetLocalName -- Ermittelt des eigenen Namens
// - ERPCGetSecondaryError -- Liefert den secondary-Error (oder Null)
// - ERPCSetTraceLevel -- Einstellen des Tracelevels
//
// 1. CLIENT
// - ERPCSndRequest -- Senden eines EasyRPC-Requests zum Server
// - ERPCRcvResponse -- Empfangen einer oder mehrerer Antworten
// - ERPCQuerySize -- Größe der nächsten Antwort abfragen
// - ERPCDeleteHandle -- Löschen des Request-Handles
//
// 2. SERVER
// - ERPCRegisterFunc -- Registrieren einer EasyRPC-Funktion
// - ERPCDeRegisterFunc -- Deregistrieren einer EasyRPC-Funktion
// - ERPCAnswer -- Senden einer Antwort zum Client
//
//
// VORGEHENSWEISE BEI DER PROGRAMMIERUNG:
// 1. Schreiben Sie für die Serverseite eine Funktion, die dem folgenden
// Prototyp entspricht:
// - uint f(const char *from, void *in, uint inlen);
//
// Erklärung der Parameter:
// - from Absenderangabe (wird für die Rückantwort benötigt)
// - in Beliebige vom Client gelieferte Eingabe
// - inlen Länge der vom Client gelieferten Eingabe
//
// Rückgabewert:
// Die Funktion muß bei fehlerfreier Ausführung 0 und ansonsten einen
// Wert zwischen 1 und 32767 zurückgeben. Im Fehlerfall wird automatisch
// vom EasyRPC eine Antwort mit dem Rückgabewert der Funktion an den
// Client gesendet. Dies gilt auch bei internen Fehlern, bei denen der
// Client einen negativen Rückgabewert erhält.
//
// Beispiel:
// uint TestFunc(const char *from, void *in, uint inlen)
// {
// printf("%s", in); // Inhalt von 'in' ist Benutzersache
// char tmp[100];
// while(gets(tmp)) // Beliebig viele Antworten senden
// ERPCAnswer(from, tmp, strlen(tmp)+1, ERPC_DATANOTCOMPLETE);
// ERPCAnswer(from, "ENDE", 5, ERPC_DATACOMPLETE);
// return 0;
// }
//
// 2. Registrieren Sie Ihre EasyRPC-Funktion mit 'ERPCRegisterFunc()'.
// Beispiel:
// #include "cxir.h"
// ...
// ERPCRegisterFunc("TESTFUNC", TestFunc);
//
// 3. Verwenden Sie zum Aufruf der registrierten Funktion (auf dem Client),
// die Funktion ERPCSndRequest() wenn Sie eine oder mehrere Antworten
// erwarten oder ERPCPostRequest() wenn keine Antwort erfolgen soll.
//
// Antworten können auf zwei Arten empfangen werden. Entweder indem von
// EasyRPC eine Callback-Funktion aufgerufen wird (kann bei ERPCSndRequest()
// angegeben werden) oder durch explizites Auslesen mit der Funktion
// ERPCRcvResponse().
#include "cxib.h"
extern "C" {
#define ERPC_MINERROR -29999
#define ERPC_MAXERROR -28000
typedef unsigned int uint;
typedef unsigned long ulong;
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// *************************** GLOBAL ************************************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
#define ERPC_TRCNO 1 // Kein Trace
#define ERPC_TRCERR 2 // nur Fehler
#define ERPC_TRCALL 3 // alles
CXIDECL32 int CXIGLOBALFUNC32 ERPCIsReady();
CXIDECL32 int CXIGLOBALFUNC32 ERPCLoad(const char *path = 0);
CXIDECL32 int CXIGLOBALFUNC32 ERPCStart(const char *systemname = 0, const char *path = 0);
CXIDECL32 int CXIGLOBALFUNC32 ERPCShutDown();
CXIDECL32 int CXIGLOBALFUNC32 ERPCOpen(const char *systemname = 0, const char *path = 0, ulong opt = 0);
CXIDECL32 int CXIGLOBALFUNC32 ERPCClose(ulong opt = 0);
CXIDECL32 int CXIGLOBALFUNC32 ERPCGetServerName(char *Name, int Size);
CXIDECL32 int CXIGLOBALFUNC32 ERPCGetLocalName(char *Name, int Size);
CXIDECL32 int CXIGLOBALFUNC32 ERPCSetLocalName(char *Name);
CXIDECL32 int CXIGLOBALFUNC32 ERPCGetProcessName(char *Name, int Size);
CXIDECL32 int CXIGLOBALFUNC32 ERPCSetProcessName(char *Name);
CXIDECL32 int CXIGLOBALFUNC32 ERPCGetSecondaryError();
CXIDECL32 int CXIGLOBALFUNC32 ERPCClientCount();
CXIDECL32 int CXIGLOBALFUNC32 ERPCGetVersionString(char *buffer, int len);
//void *CXIGLOBALFUNC ERPCMemAlloc(uint Size);
//CXIDECL32 int CXIGLOBALFUNC32 ERPCMemFree(void *p);
//CXIDECL32 int CXIGLOBALFUNC32 ERPCSetTraceLevel(int TraceLevel); // 0 (nur Fehler) oder 1 (alles)
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// *************************** CLIENT ************************************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
#define ERPC_DATACOMPLETE 0
#define ERPC_DATANOTCOMPLETE -1
#define ERPC_TIMEOUT -2
struct _ERPCHandle;
typedef _ERPCHandle *ERPCHandle;
typedef uint (CXIGLOBALFUNC *ERPCClientFunc) (void *out, uint outlen, int rc, void *cargo);
//CXIDECL32 int CXIGLOBALFUNC32 ERPCRegister(const char *name, ERPCClientFunc f = 0, void *cargo = 0);
CXIDECL32 int CXIGLOBALFUNC32 ERPCSndRequest(ERPCHandle *h, const char *to, void *in, uint inlen, ERPCClientFunc f = 0, void *cargo = 0, uint sec = 60);
CXIDECL32 int CXIGLOBALFUNC32 ERPCPostRequest(const char *to, void *in, uint inlen);
CXIDECL32 int CXIGLOBALFUNC32 ERPCQuerySize(ERPCHandle h);
CXIDECL32 int CXIGLOBALFUNC32 ERPCRcvResponse(ERPCHandle h, void *out, uint *outlen, uint sec = 60);
CXIDECL32 int CXIGLOBALFUNC32 ERPCDeleteHandle(ERPCHandle h);
CXIDECL32 int CXIGLOBALFUNC32 ERPCDisable(ERPCHandle h);
CXIDECL32 int CXIGLOBALFUNC32 ERPCEnable(ERPCHandle h);
CXIDECL32 int CXIGLOBALFUNC32 ERPCDelayedEnable(ERPCHandle h, uint msec = 300);
CXIDECL32 int CXIGLOBALFUNC32 ERPCGlobalEnable();
CXIDECL32 int CXIGLOBALFUNC32 ERPCGlobalDisable();
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// *************************** SERVER ************************************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
typedef uint (CXIGLOBALFUNC *ERPCServerFunc) (const char *from, void *in, uint inlen);
CXIDECL32 int CXIGLOBALFUNC32 ERPCRegisterFunc(const char *name, ERPCServerFunc f);
CXIDECL32 int CXIGLOBALFUNC32 ERPCDeRegisterFunc(const char *name);
CXIDECL32 int CXIGLOBALFUNC32 ERPCAnswer(const char *from, void *out, uint outlen, int complete = ERPC_DATACOMPLETE, int rc = 0);
// *************************************************************************
// WICHTIG:
//
// Liefert die registrierte Funktion nach ihrem Aufruf einen Wert ungleich
// Null zurück, so wird vom EasyRPC automatisch eine Fehlerantwort mit
// diesem Rückgabewert an den Client zurückgesendet. Ansonsten ist es die
// Aufgabe der Anwendung Antworten, mit ERPCAnswer(), an den Client zu
// senden.
// Dabei können beliebig viele Antworten sowohl innerhalb der EasyRPC-
// Funktion, als auch außerhalb versendet werden. Der Parameter 'from'
// verliert nach dem Beenden der EasyRPC-Funktion NICHT seine Gültigkeit.
//
// Werden mehrere Antworten mittels ERPCAnswer() an den Client zurück-
// gesendet, so muß der Parameter 'complete' bei allen Aufrufen, außer
// dem letzten, auf ERPC_DATANOTCOMPLETE (-1) gesetzt werden.
// *************************************************************************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// ************************* FEHLERNUMMERN *******************************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// GLOBAL
// ======
// ERPCIsReady:
// 00000 EasyRPC ist nicht verfügbar
// ERPCLoad:
#define cxiErrorERPCLoadNoIniFile1 -28100
#define cxiErrorERPCLoadNoIniFile2 -28101
#define cxiErrorERPCLoadExeNotFound -28102
#define cxiErrorERPCLoadExeFail1 -28103
#define cxiErrorERPCLoadExeFail2 -28104
#define cxiErrorERPCLoadDllNotFound -28105
#define cxiErrorERPCLoadDllFail1 -28106
#define cxiErrorERPCLoadDllFail2 -28107
#define cxiErrorERPCLoadDllInit -28108
#define cxiErrorERPCLoadTimeout -28109
// ERPCShutDown:
#define cxiErrorERPCShutDownSend -28120 // Fehler beim Senden an @EasyRPC
// ERPCGetServerName:
#define cxiErrorERPCGetServerNoName -28140 // Parameterfehler
// ERPCGetLocalName:
#define cxiErrorERPCGetLocalNameWrongPrm -28160 // Parameterfehler
// ERPCSetLocalName:
#define cxiErrorERPCSetLocalNameWrongPrm -28180 // Parameterfehler
#define cxiErrorERPCSetLocalNameNoServer -28181 // Kein Server verfügbar
// ERPCGetProcessName:
#define cxiErrorERPCGetProcessNameWrongPrm -28200 // Parameterfehler
// ERPCSetProcessName:
#define cxiErrorERPCSetProcessNameWrongPrm -28220 // Parameterfehler
// CLIENT
// ======
// ERPCSndRequest:
#define cxiErrorERPCSndRequestNullHandle -28000 // Handle ist null
#define cxiErrorERPCSndRequestNoMem -28001 // Kein Speicher mehr
#define cxiErrorERPCSndRequestTarget -28002 // Zielangabe ist fehlerhaft <Zielangabe>
#define cxiErrorERPCSndRequestNullData -28003 // Zeiger auf Daten ist null
#define cxiErrorERPCSndRequestLength -28004 // Länge der Daten ist null
#define cxiErrorERPCSndRequestCopy -28005 // Fehler <rc> beim Kopieren der Daten
#define cxiErrorERPCSndRequestNoMem2 -28006 // Kein Speicher mehr
#define cxiErrorERPCSndRequestReceiver -28007 // Fehlerstatus <rc> des Empfängerknotens
#define cxiErrorERPCSndRequestSend -28008 // Fehler <rc> beim Senden an <Zielangabe>
// ERPCRcvResponse:
#define cxiErrorERPCRcvResponseBadState -28020 // Aufruf trotz Fehlerstatus (<rc>)
#define cxiErrorERPCRcvResponseNullData -28021 // Zeiger auf Daten ist null
#define cxiErrorERPCRcvResponseLength -28022 // Zeiger auf Längenfeld ist null
#define cxiErrorERPCRcvResponseBlockSize -28023 // Angegebene Blocklänge ist null
#define cxiErrorERPCRcvResponseReceive -28024 // Fehler <rc> beim Empfangen
#define cxiErrorERPCRcvResponseCopy -28025 // Fehler <rc> beim Kopieren der Daten (Länge=<Datenlänge>)
#define cxiErrorERPCRcvResponseCbfNoCargo -28026 // Cargo ist null
#define cxiErrorERPCRcvResponseCbfNoFunc -28027 // Keine Callback-Funktion
#define cxiErrorERPCRcvResponseNoConnect -28028 // Keine Verbindung zur Gegenseite
// -00001 Es sind weitere Daten verfügbar
// -00002 Keine Daten innerhalb von <Anzahl Sekunden> Sek. empfangen
// ERPCQuerySize:
#define cxiErrorERPCQuerySizeBadState -28040 // Aufruf trotz Fehlerstatus (<rc>)
#define cxiErrorERPCQuerySizeBlockSize -28041 // Fehler <rc> beim Ermitteln der Blockgröße
// ERPCPostRequest:
#define cxiErrorERPCPostRequestNullData -28060 // Zeiger auf Daten ist null
#define cxiErrorERPCPostRequestLength -28061 // Länge der Daten ist null
#define cxiErrorERPCPostRequestCopy -28062 // Fehler <rc> beim Kopieren der Daten
#define cxiErrorERPCPostRequestSend -28063 // Fehler <rc> beim Senden an <Zielangabe>
#define cxiErrorERPCPostRequestNoShell -28064 // CXI-Shell ist nicht aktiv
// ERPCDisableCbf:
#define cxiErrorERPCDisableCbfBadState -28070 // Aufruf trotz Fehlerstatus (<rc>)
// ERPCEnableCbf:
#define cxiErrorERPCEnableCbfBadState -28080 // Aufruf trotz Fehlerstatus (<rc>)
// SERVER
// ======
// ERPCServer:
#define cxiErrorERPCServerWrongPrm -29000 // Funktionsname oder Funktionszeiger Fehlerhaft
#define cxiErrorERPCServerInternal -29001 // Interner Fehler
#define cxiErrorERPCServerNullPtr -29002 // Funktionszeiger ist null
#define cxiErrorERPCServerCbfCall -29003 // Ergebnis <rc> von EasyRPC-Funktionsaufruf
// ERPCRegisterFunc:
#define cxiErrorERPCRegisterFuncDupFunc -29020 // Funktion <Funktionsname> ist bereits registriert
#define cxiErrorERPCRegisterFuncNoMem -29021 // Kein Speicher mehr
#define cxiErrorERPCRegisterFuncBadState -29022 // Fehlerstatus des EasyRPC-Servers
#define cxiErrorERPCRegisterFuncNoMem2 -29023 // Kein Speicher mehr
// ERPCDeRegisterFunc:
#define cxiErrorERPCDeRegisterFuncNoFunc -29040 // Es sind keine Funktionen registriert
#define cxiErrorERPCDeRegisterFuncParam -29041 // Parameterfehler (Name = (null))
#define cxiErrorERPCDeRegisterFuncName -29042 // Parameterfehler (Name ist leer)
#define cxiErrorERPCDeRegisterFuncNoReg -29043 // Funktion <Funktionsname> ist nicht registriert
// ERPCAnswer:
#define cxiErrorERPCAnswerNullTarget -29060 // Parameterfehler (Zielangabe ist null)
#define cxiErrorERPCAnswerEmptyTarget -29061 // Parameterfehler (Zielangabe ist leer)
#define cxiErrorERPCAnswerCopy -29062 // Fehler <rc> beim Kopieren der Daten
#define cxiErrorERPCAnswerSend -29063 // Fehler beim Senden an <Client>
// ERPCGetVersionString:
#define cxiErrorERPCGetVersionString -29080 // Fehler beim Abfragen der Versionsnummern
// cxiConvertToText:
#define cxiErrorConvertToText -29100 // Basisfehlernummer
// cxiConvertFromText:
#define cxiErrorConvertFromText -29120 // Basisfehlernummer
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
// ********************* ALLGEMEINE TOOLFUNKTIONEN ***********************
// ***********************************************************************
// ***********************************************************************
// ***********************************************************************
CXIDECL32 int CXIGLOBALFUNC32 cxiChangeLogFile();
CXIDECL32 int CXIGLOBALFUNC32 cxiLastLogName(char *Name, int Size);
CXIDECL32 int CXIGLOBALFUNC32 cxiSetLogLevel(int Level);
CXIDECL32 int CXIGLOBALFUNC32 cxiGetLogLevel();
// Werte für Options:
#define C2T_CSYNTAX 1 // Entspricht /CSX (C-String Syntax)
#define C2T_CID 2 // Entspricht /CID (CID-Format)
#define C2T_NOTYPE 4 // Entspricht /NTP (No Type; keine Typangabe)
#define C2T_NOSTRING 8 // Entspricht /NST (No String)
#define C2T_NOBLANK 16 // Entspricht /NBL (No blanks)
#define C2T_NOQUOT 32 // Entspricht /NQM (No quotation marks)
#define C2T_INI 64 // Entspricht /INI (INI-Format erzeugen)
CXIDECL32 int CXIGLOBALFUNC32 cxiConvertToText(const char *ScrDatei,
const char *DstDatei,
const char *KeyWord = 0,
ulong Options = 0,
int *SecErr = 0,
char *ErrStr = 0,
int ErrStrLen = 0);
// Werte für Options:
#define T2C_CSYNTAX 1 // Entspricht /CSX (C-String Syntax)
#define T2C_CID 2 // Entspricht /CID (CID-Format)
#define T2C_UPDATE 4 // Entspricht /UPD (Textdatei in CXI-Datei einarbeiten)
CXIDECL32 int CXIGLOBALFUNC32 cxiConvertFromText(const char *SrcDatei,
const char *DstDatei,
const char *KeyWord = 0,
ulong Options = 0,
int *SecErr = 0,
char *ErrStr = 0,
int ErrStrLen = 0);
}
#endif