Dipl.-Ing. Hardo Naumann Nienburger Str. 14 31552 Rodenberg Spezifikation ipChart Fernsteuerprotokoll (ipChart remote control protocol: ipChart-RCP) Ver 0.123 0. Zweck von ipChart-RCP Über ipChart-RCP können an ipChart alle nötigen Einstellungen zur Verbindungssteuerung durch eine übergeordnete Steuer-Software vorgenommen werden. So kann das mühsame Einstellen aller notwendigen Verbindungen für eine volle Vermaschung vieler Teilnehmer z.B. durch eine Konferenzmanagement-SW erleichtert werden. ipChart kann auf diese Weise lückenlos in eine komplexe CSCW-Umgebung integriert werden und parallel zu anderen Werkzeugen (shared application, audio, video, ...) genutzt werden. (CSCW = computer supported cooperative work). 1. Hinweise zur Syntax dieses Dokuments <-- markiert einen Befehl (<-- ist nicht Bestandteil des Befehls!) --> markiert eine Meldung von ipChart (--> ist nicht Bestandteil der Meldung!) # markiert einen Platzhalter für einen numerischen Parameter, zulässige Zeichen für numerische Parameter: '0'..'9' und '-' * markiert einen Platzhalter für einen alphanumerischen Parameter 2. Aufruf und Test von ipChart Damit eine Instanz von ipChart über IP ferngesteuert werden kann, muss sie mit dem Parameter rcp#### gestartet werden. Dabei ist #### die Port-Nummer, auf der ipChart auf Befehle 'lauscht'. Für eine Steuerung über Telnet (Standard-IP-Port 23) lautet der Aufruf z.B.: ipChart.exe rcp23 Zum Test der Fernsteuerfunktionen von ipChart können dann einfach z.B. über einen Telnet-Client alle Befehle ausprobiert und die Reaktionen in der ipChart-GUI verfolgt werden. Damit ipChart mit Telnet gesteuert werden kann, sind folgende Einstellung im Telnet-Terminal nötig: - NTLM aus - LOCAL_ECHO an - ANSI-Mode Wahlweise kann ipChart auch per Registry-Eintrag dazu gebracht werden, ein Echo an der RCP-Schnittstelle zu erzeugen (als direktes Feedback der RCP-Verbindung). Dann muss am Telnet-Terminal LOCAL_ECHO ausgeschaltet werden. Als Hinweis auf die Fernbedienbarkeit wird nach Aufruf mit Parameter rcp#### in der Titelzeile der Connections-GUI von ipChart "RCP####" angezeigt. ipChart kann auch mehrfach auf einem PC gestartet werden. Aber bei jedem Aufruf mit dem Parameter rcp muss dann eine andere Portnummer angegeben werden, da nicht zwei Instanzen auf dem gleichen Port kommunizieren können. 3. Allgemeine Hinweise Alle Zeichen in der RCP-Kommunikation werden entsprechen dem ASCII-Code codiert. Alle ipChart-RCP-Befehle und Antworten werden mit CRLF (chr(13);chr(10)) abgeschlossen. IP-Adressen werden stets in der Form ###.###.###.### angegeben. 'mco' (=max. connections) ist die Anzahl der max. gleichzeitig möglichen Verbindungen. Es sind z.Zt. max. 7 Verbindungen gleichzeitig möglich (kann bei Bedarf leicht erweitert werden). 'cindex' (=connection-index) ist die ipChart-interne Nummer des Sockets [1...mco]. Der Socket mit cindex = 0 wird immer für das Annehmen von Anrufen freigehalten. In der Zeile cindex wird in der Connections-GUI von ipChart der Status des Sockets angezeigt. Wichtiger Hinweis beim Betrieb von mehreren Instanzen von ipChart auf einem PC: Es dürfen nicht mehrere Instanzen von ipChart auf dem gleichen PC am gleichen Port 'lauschen'. Deshalb unbedingt vor lis jeweils mit lpo einen eigenen Port je Instanz einstellen. Wenn je PC nur max. eine Instanz verwendet wird, dann können alle auf einen gemeinsamen Sende- und Empfangsport eingestellt werden. Das reduziert die notwendigen Einstellungen erheblich: Es müssen dann nur noch nacheinander mit rip die IP-Adressen der gewünschten Partner eingestellt werden und jeweils mit con die Verbindungen geschaltet werden. Vorher müssen natürlich alle Teilnehmer mit lis auf Empfangsbereitschaft gestellt worden sein. Die Registry-Einträge von ipChart liegen unter HKEY_CURRENT_USER/Software/VB and VBA.../ipChart/Default (können ggf. vor einem Start von ipChart von der aufrufenden Software voreingestellt werden, um gleich mit einer bestimmten Einstellung zu beginnen). 4. ipChart-RCP Protokollspezifikation 4.1. Zulässige Befehle und die synchronen Reaktionen von ipChart darauf: Logon: <--lon -->ipChart #.##.## Rückgabewert: Versionsnummer von ipChart Logoff: (hat z.Zt. keine Funktion, kann weggelassen werden) <--lof -->lof Alive?: Einfacher Test, ob die Gegenseite noch 'lebt'. <--ali -->ali Maximum count of connections abfragen: <--mco -->mco### Rückgabewert: max. Anzahl Verbindungen, die ipChart noch öffnen kann Remote IP-Adresse setzen: <--rip###.###.###.### Parameter: IP-adresse -->rip Remote Port setzen: <--rpo##### Parameter: Port-Nummer -->rpo Local Port setzen: <--lpo##### Parameter: Port-Nummer -->lpo Locale IP-Adresse abfragen: <--lip -->lip###.###.###.### Rückgabewert: lokale IP-Adresse Listen: ipChart ist damit auf dem eingestellten lpo empfangsbereit <--lis -->lis Connect: ipChart versucht einen Verbindungsaufbau zu rip:rpo <--con -->con Disconnect: Verbindung mit index ## beenden <--dis## -->dis## Parameter: cindex Statusabfrage <--sts## -->sts##>#:###.###.###.###:##### Parameter: cindex>WinsockStatusNr:IpAdress:Port Hinweise zu sts: 1. Falls der angefragte Socket nicht instanziiert ist, endet die Antwort bereits hinter dem '>' mit CRLF. 2. Falls keine Verbindung besteht, sind IP-Adresse leer und Port = 0. 3. Bedeutung der WinsockStatusNr: 0 closed 1 open 2 listening 3 connection pending 4 resolving host 5 host resolved 6 connecting 7 connected 8 closing 9 error Connection dialog x-position: Setzt x-Koordinate des ipChart Connection-Dialogs. Indem z.B. x auf -10000 gesetzt wird, wird der Dialog unsichtbar für den Anwender! <--cdx#### Parameter: x-Koordinate -->cdx ipChart beenden: <--end -->end Remote Protocol Error: <--unbekannter Befehl oder unzulässige oder fehlende Parameter -->rpe ********* Rückgabewert: Echo des Befehls, der nicht interpretiert werden konnte 4.2. Mögliche asynchrone Meldungen von ipChart Call received from ... Diese ipChart-Instanz hat von der Gegenstelle einen Anruf angenommen. -->crf##>###.###.###.###:##### Rückgabewerte: cindex>rip:rpo Call accepted from ... Die Gegenstelle hat den Anruf von dieser ipChart-Instanz angenommen. -->caf##>###.###.###.###:##### Rückgabewerte: cindex>rip:rpo Connection closed -->ccl## Rückgabewert: cindex Call not executed: Der con-Befehl konnte nicht ausgeführt werden, weil ein Fehler aufgetreten ist (z.B. die Maximalzahl Verbindungen erreicht ist): -->cne Call not accepted: Es ist ein Anruf eingegangen, konnte aber nicht angenommen werden, z.B. weil die Maximalzahl Verbindungen erreicht ist: -->cna WinsockError -->wse##>********** Rückgabewerte: cindex>Fehlermeldungstext von Winsock Programm wurde durch User oder Fehler beendet -->end Es ist nicht sicher, dass es ipChart im Fehlerfall noch schafft, ein 'end' zu senden. Deshalb ggf. mit ali testen, ob ipChart noch läuft. --------------eof--------------------------