Das GEx Client Application Interface (API) solostec 31. Oktober 2009 Zur Entwicklung von Client-Komponenten, die auf dem IP-T Protokoll nach E DIN 43863-4 basieren, stellt die solostec gmbh eine Programmbibliothek für Windows- und Linux Systeme bereit. Die jeweils aktuelle Basis- Variante steht auf der Produkthomepage im Downloadbereich zum Download bereit. Inhaltsverzeichnis 1 History / Revision 3 2 Einführung 4 2.1 Überblick.................................... 4 2.2 Unterstützte Betriebssysteme......................... 4 2.3 Abhängigkeiten................................. 5 2.4 Redistributable Code and Sample Code................... 5 3 API 5 3.1 Überblick.................................... 5 3.2 Architektur................................... 6 3.3 Compiling.................................... 6 3.3.1 Compiling on Windows........................ 6 3.3.2 Compiling on Linux.......................... 8 3.4 Functions Reference.............................. 8 3.4.1 sync connect.............................. 8 3.4.2 login................................... 8 3.4.3 control logout response....................... 9 3.4.4 control watchdog response...................... 9 3.4.5 control watchdog request...................... 9 3.4.6 transport connection open request................. 10 solostec gmbh, Stülower Weg 58a, 18209 Bad Doberan, Tel +49 (0)38203 733-500, solostec.de
Inhaltsverzeichnis Inhaltsverzeichnis 3.4.7 transport connection close request................. 10 3.4.8 transport push channel open request............... 10 3.4.9 transport push channel close request............... 11 3.4.10 transport push data transfer request............... 11 3.4.11 app protocol version request.................... 12 3.4.12 app device software version request............... 13 3.4.13 app device identifier request.................... 13 3.4.14 app network status request..................... 13 3.4.15 app ip statistic request....................... 14 3.4.16 app device authentification request................ 14 3.4.17 app device time request...................... 14 3.4.18 app push target namelist request................. 15 3.4.19 control push target register request............... 15 3.4.20 control push target deregister request.............. 16 3.4.21 is open................................. 16 3.4.22 is authorized.............................. 16 3.4.23 is connection open.......................... 17 3.4.24 get watchdog............................. 17 3.4.25 start watchdog............................. 17 3.4.26 cancel watchdog............................ 18 3.4.27 get local ipv4 address........................ 18 3.4.28 get remote ipv4 address...................... 18 3.4.29 get local port............................. 19 3.4.30 get remote port............................ 19 3.4.31 exec................................... 19 3.4.32 send data............................... 20 3.4.33 hook data............................... 20 3.4.34 hook 7fff (unknown command response).............. 20 3.4.35 hook login response......................... 21 3.4.36 hook 4004 (logout response)..................... 21 3.4.37 hook 4005 (push target register response).............. 22 3.4.38 hook 4006 (push target deregister response)............ 22 3.4.39 hook c005 (register target request)................. 23 3.4.40 hook c006 (deregister target request)................ 23 3.4.41 hook c008 (watchdog request).................... 23 3.4.42 hook a000 (protocol version request)................ 24 3.4.43 hook a001 (software version request)................ 24 3.4.44 hook a003 (device identifier request)................ 25 3.4.45 hook a004 (network status request)................. 25 3.4.46 hook a005 (IP statistic request)................... 25 3.4.47 hook a006 (device authentification request)............. 26 3.4.48 hook a007 (device time request)................... 26 3.4.49 hook a008 (push target namelist request).............. 26 3.4.50 hook 2000 (protocol version response)................ 27 2
1 HISTORY / REVISION 3.4.51 hook 2001 (software version response)................ 27 3.4.52 hook 2003 (device identifier response)................ 27 3.4.53 hook 2004 (network status response)................ 28 3.4.54 hook 2005 (ip statistic response)................... 28 3.4.55 hook 2006 (device authentification response)............ 29 3.4.56 hook 2007 (device time response).................. 29 3.4.57 hook 9000 (push channel open request)............... 29 3.4.58 hook 9001 (push channel close request)............... 30 3.4.59 hook 9002 (push data transfer request)............... 30 3.4.60 hook 9003 (connection open request)................ 31 3.4.61 hook 9004 (connection close request)................ 31 3.4.62 hook 1000 (push channel open response).............. 31 3.4.63 hook 1001 (push channel close response).............. 32 3.4.64 hook 1002 (push data transfer response).............. 32 3.4.65 hook 1003 (connection open response)............... 33 3.4.66 hook 1004 (connection close response)................ 33 3.5 Samples..................................... 33 3.5.1 C++ Interface............................. 33 3.5.2 C Interface............................... 34 1 History / Revision Date Author Chapter Remark 2009-SEP-07 sol 3.4.43 auf Seite 24 supplemented - previous versions didn t send a response. sol 3.4.8 auf Seite 10 added sol 3.4.9 auf Seite 11 added sol 3.4.10 auf Seite 11 added sol 3.4.64 auf Seite 32 added sol 3.4.59 auf Seite 30 added sol 3.4.25 auf Seite 17 added 2009-OCT-28 sol 2.3 auf Seite 5 Some additional hints. sol 3.3.2 auf Seite 8 removed sol 3.4.34 auf Seite 20 new sol 3.4.36 auf Seite 21 new sol 3.4.18 auf Seite 15 new sol 3.4.19 auf Seite 15 new sol 3.4.20 auf Seite 16 new sol 3.4.37 auf Seite 22 new Fortsetzung folgende Seite Tabelle 1: Revisionsbericht 3
2 EINFÜHRUNG Date Author Chapter Remark sol 3.4.38 auf Seite 22 new sol 3.4.39 auf Seite 23 new sol 3.4.40 auf Seite 23 new sol 3.4.42 auf Seite 24 new sol 3.4.43 auf Seite 24 fixed sol 3.4.48 auf Seite 26 new sol 3.4.49 auf Seite 26 new sol 3.4.57 auf Seite 29 new sol 3.4.58 auf Seite 30 new sol 3.4.59 auf Seite 30 fixed sol 3.4.66 auf Seite 33 fixed 2009-OCT-29 sol 3.4.5 auf Seite 9 new (Forts.) Tabelle 1: Revisionsbericht 2 Einführung 2.1 Überblick GEx-Client API ist eine Programmbibliothek, die zum Schreiben von Scripts und Programmen dient, die über das IP-T Protokoll (nach E DIN 43863-4) kommunizieren. Die API bietet ein high-level Interface und ist sowohl zum Schreiben von Scripten wie auch für Anwendungsprogrammierer geeignet. Die GEx-Client API wurde für folgende Anwendergruppen entwickelt: Technisch interessierte Anwender Zum Beispiel, Leute aus der IT-Abteilung, die bestimmte in-house Tools erstellen. Entwickler Software- und Hardwareanbieter, die Produkte anbieten, in denen das IP-T Protokoll zum Einsatz kommt. Partner Softwareanbieter, die den GEx-Server in ihre Produkte integrieren möchten. 2.2 Unterstützte Betriebssysteme Die GEx-Client API läuft auf Microsoft Windows (ab XP) und Linux (ab Kernel 2.4.x). Auf 64-bit Systemen können sie im Emulationsmodus betrieben werden. Dies sollte aber vorher ausgiebig getestet werden. Die Bibliothek kann statisch oder dynamisch gebunden werden. Die notwendigen Include-Dateien (C/C++) stehen zur Verfügung. Auch Bridges zu anderen Programmiersprachen, wie Java, PHP oder Smalltalk können damit leicht erstellt werden. 4
2.3 Abhängigkeiten 3 API 2.3 Abhängigkeiten Neben der C-Runtime existieren Abhängigkeiten zu folgenden Bibliotheken: Boost ab 1.39.0 Aus der Boost-Library werden die Module System Date-Time und Program-Options verwendet. log4cxx ab 0.10.0 Das Logging Framework kann optional eingesetzt werden. Die GEx- Client API wird auch in einer Version bereitgestellt, die keine Verweise auf log4cxx enthält 1. Die notwendigen Libraries liegen der Distribution in binärer Form bei. 2.4 Redistributable Code and Sample Code As noted in the End User License Agreement, the GEx-Client API allows you to build and distribute your own applications. To facilitate this, the following files are designated as redistributable for the purpose of that agreement: gex gex gex gex client.lib client.dll client.so client.h Redistribution of the open source libraries included with the GExClient API is governed by their respective open source license agreements. The GExClient API also includes sample code, which you can use as a starting point for your own programs. Code is delivered in the Samples directory. A Makefile is provided for Linux, and an solution file for Windows. 3 API 3.1 Überblick Einen Überblick, wie die GEx-Client API eingebunden wird, gibt Abbildung 1. Die GEx-Client API besitzt zwei wesentliche Eigenschaften. Die erste Eigenschaft ist der Context. Bevor ein Zugriff auf die gewünschte Funktionalität möglich ist, muss 1 Beim Verwenden der Quellcodeversion, wird der Compilerschalter GEX_NO_LOOGING gesetzt. 5
3.2 Architektur 3 API Abbildung 1: Einbinden der GEx-Client API zunächst ein Context erstellt werden. Aus den Beispielprogrammen ist ersichtlich, wie das erfolgt. In der Basis-Variante stellt der Context jeweils nur ein Interface (was einer Verbindung entspricht) zur Verfügung. In der Enterprise-Variante gibt es keine Beschränkung. Die zweite wesentliche Eigenschaft ist das Callback-Interface. Durch die asynchrone Arbeitsweise wird ein flexibler Mechanismus benötigt, um auf die eintretenden Ereignisse zu reagieren. Zunächst stellt die GEx-Client API default-mechanismen zur Verfügung, um z.b. auf Watchdogs oder Abfragen korrekt zu reagieren. Jedes Ereignis kann aber über eigene Callback-Routine abgefangen werden, um eine andere Reaktionsweise zu implementieren. Von zentraler Bedeutung ist der Empfang von Daten, der über die Methode hook_data() abgefangen werden kann (siehe Referenz 3.4.33 auf Seite 20). 3.2 Architektur Siehe Abbildung 2 auf Seite 7. 3.3 Compiling 3.3.1 Compiling on Windows To use the library, you need Visual Studio 2008 (Visual C release 9.0) or later. To compile the code on Windows using the wrapper library, use the following procedure. A solution file is in the gex_api\projects\win32\vc9.0\gex-all folder. It contains two 6
3.3 Compiling 3 API Abbildung 2: Der Datenfluss in der Anwendung projects. The gex api project generates the API DLL as Debug or Release version. The gex sim project is a sample how the API DLL could be used. 1. Add the header file to an include statement in your source code: #include <dll context.h>... program code here... 2. Compile for, and link with, the multithreaded version of the C runtime library. You must use the non-debug version (/MT). 3. Compile code to link with these files: kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib 7
odbccp32.lib log4cxx.lib gexclient.lib 3.3.2 Compiling on Linux To compile the shared library on a Linux OS it s a good start to use the makefile you find in the gex api/debug path. Since some path names are absolut, it is necessary to modify these details. If the C++ compiler is present and all required libraries available a simple call of the makefile command should generate the libgex client.so file. 3.4 Functions Reference 3.4.1 sync connect 1 bool sync connect ( const std : : s t r i n g& address, 2 const std : : s t r i n g& s e r v i c e ) ; Listing 1: sync connect TCP/IP address host name service service name or port true if TCP/IP connect succeeded. 3.4.2 login 1 void l o g i n ( const std : : s t r i n g& account, 2 const std : : s t r i n g& password, 3 bool scrambled ) ; Listing 2: sync connect control account device name password password scrambled if true all communication will be scrambled 8
(void) Send login request to server. 3.4.3 control logout response 1 void l o g i n ( response type reason ) ; Listing 3: sync connect control reason Reason for logout. Possible values are 0 (internal error) and 1 (normal logout). (void) To catch this response see section 3.4.36 auf Seite 21. 3.4.4 control watchdog response 1 void control watchdog response () ; Listing 4: control watchdog response control (void) Response without request get sequence number 0. 3.4.5 control watchdog request 1 sequence type 2 control watchdog request ( ) ; Listing 5: control watchdog request control Sequence number. 9
The server should send a watchdog response. 3.4.6 transport connection open request 1 sequence type 2 transport connection open request ( const std : : s t r i n g& number ) ; Listing 6: transport connection open request transport number virtual number to call Sequence number. Place the IP-T command of operation transport connection open request in command queue. See also section 3.4.65 auf Seite 33. 3.4.7 transport connection close request 1 sequence type transport connection open request () ; Listing 7: transport connection close request transport Sequence number. Place the IP-T command of operation transport connection close request in command queue. See also section 3.4.66 auf Seite 33. 3.4.8 transport push channel open request 1 sequence type 2 transport push channel open request ( const std : : s t r i n g& target 3, const std : : s t r i n g& account 4, const std : : s t r i n g& number 5, const std : : s t r i n g& version 6, const std : : s t r i n g& device id 7, const timespan type ack time out ) ; Listing 8: transport push channel open request transport target target name 10
account device name number phone number version firmware version device id device id ack time out timeout in seconds Sequence number. Place the IP-T command of operation transport push channel open request in command queue. The server answers with transport push channel open response. See 3.4.62 auf Seite 31. 3.4.9 transport push channel close request 1 sequence type 2 transport push channel close request ( channel id type channel id ) ; Listing 9: transport push channel close request transport channel id channel id. Comes with the corresponding transport push channel open response. Sequence number. Place the IP-T command of operation transport push channel close request in command queue. The server answers with transport push channel close response. See 3.4.63 auf Seite 32. 3.4.10 transport push data transfer request 1 sequence type 2 transport push data transfer request ( channel id type channel number 3, source id type source id 4, status type status 5, byte type block number 6, const gex : : ipt : : push data& data ) Listing 10: transport push data transfer request transport To send a C-string use the following method: 11
1 sequence type 2 transport push data transfer request ( channel id type channel number 3, source id type source id 4, status type status 5, byte type block number 6, const std : : s t r i n g& s t r ) To send a file use this: Listing 11: transport push data transfer request (string) 1 bool 2 transport push data transfer request ( channel id type channel number 3, source id type source id 4, const std : : s t r i n g& file name ) Listing 12: transport push data transfer request (file) channel number channel number. Comes with the corresponding transport push channel open response. source id source id. Comes with the corresponding transport push channel open response. status unused. Null in every case. block number data block number. The sender is responsible for strictly increasing values. data binary data. There is an upper limit of 64k. str ASCII data. The terminating NULL of the C-string will be not transmitted. file name file name. Sequence number. Place the IP-T command of operation transport push transfer request in command queue. The server answers with transport push data transfer response. See 3.4.64 auf Seite 32. 3.4.11 app protocol version request 1 sequence type app protocol version request ( ) ; Listing 13: app protocol version request app 12
Sequence number. See section 3.4.50 auf Seite 27. 3.4.12 app device software version request 1 sequence type app device software version request () ; Listing 14: app device software version request app Sequence number. See section 3.4.51 auf Seite 27. 3.4.13 app device identifier request 1 sequence type app device identifier request ( ) ; Listing 15: app device identifier request app Sequence number. See section 3.4.52 auf Seite 27. 3.4.14 app network status request 1 sequence type app network status request ( ) ; Listing 16: app network status request app Sequence number. See section 3.4.53 auf Seite 28. 13
3.4.15 app ip statistic request 1 sequence type app ip statistic request () ; Listing 17: app ip statistic request app Sequence number. See section 3.4.54 auf Seite 28. 3.4.16 app device authentification request 1 sequence type app device authentification request () ; Listing 18: app device authentification request app Sequence number. See section 3.4.55 auf Seite 29. 3.4.17 app device time request 1 sequence type app device time request () ; Listing 19: app device time request app Sequence number. See section 3.4.56 auf Seite 29. 14
3.4.18 app push target namelist request 1 sequence type 2 app push target namelist request ( const std : : s t r i n g& target 3, const std : : s t r i n g& account 4, const std : : s t r i n g& number 5, const std : : s t r i n g& version 6, const std : : s t r i n g& id ) ; Listing 20: app push target namelist request app target Target name account Device name number Virtual phone number version Software version id Device identifier Sequence number. All specified parameters are interpreted as stem for search values. That is if one value is matching, if it s equal up to the given length. So an empty search value matchs all records. 3.4.19 control push target register request 1 sequence type 2 app push target register request ( const std : : s t r i n g& target 3, packet size type packet size 4, window size type window size ) ; Listing 21: control push target register request control target Target name to register packet window size maximum packet size size maximum windows size. Currently 1 is the only valid value. Sequence number. 15
Each client can register one or multiple targets. The only requirement is that all targets of on one client have different names. Otherwise different clients is allowed to register targets with the same name. 3.4.20 control push target deregister request 1 sequence type 2 control push target deregister request ( const std : : s t r i n g& target ) ; Listing 22: control push target deregister request control target Target name to deregister Sequence number. One client can deregister only one target at once. The specified name must be matching over the full length. This behaviour differs from app push target namelist request() (see section 3.4.18 auf Seite 15). 3.4.21 is open 1 bool is open ( ) const ; Listing 23: is open status Determine whether the TCP/IP connection is open. 3.4.22 is authorized 1 bool is authorized () const ; Listing 24: is authorized status 16
true if client is successful authorized. 3.4.23 is connection open 1 bool is connection open ( ) const ; Listing 25: is connection open status true if client is part of a circuit switch or a leased line. 3.4.24 get watchdog 1 timespan type get watchdog () const ; Listing 26: get watchdog status Watchdog time in minutes. A value of zero indicates that no watchdog is running. 3.4.25 start watchdog 1 bool start watchdog ( unsigned sec ) ; Listing 27: start watchdog status sec Duration of watchdog in seconds. true if start of watchdog timer was successful 17
A watchdog timer should at least 3 seconds shorter than the received watchdog duration. The login response default handler starts the timer automatically shortened by 12 seconds. 3.4.26 cancel watchdog 1 bool cancel watchdog () Listing 28: cancel watchdog status true if if timer was canceled successful Only a running timer should be cancelled. When terminating the application, the watchdog timer will be cancelled automatically. 3.4.27 get local ipv4 address 1 unsigned long get local ipv4 address ( ) const ; Listing 29: get local ipv4 address status Get the address as an unsigned long in host byte order. 3.4.28 get remote ipv4 address 1 unsigned long get remote ipv4 address () const ; Listing 30: get remote ipv4 address status Get the address as an unsigned long in host byte order. 18
3.4.29 get local port 1 unsigned short get local port () const ; Listing 31: get local port status Get the port associated with the local endpoint. The port number is always in the host s byte order. 3.4.30 get remote port 1 unsigned short get remote port () const ; Listing 32: get remote port status Get the port associated with the remote endpoint. The port number is always in the host s byte order. 3.4.31 exec 1 void exec ( ) ; Listing 33: exec internal Runs the internal p2 processor to execute all outstanding commands. 19
3.4.32 send data 1 void send data ( const char data, 2 std : : size t s i z e ) ; Listing 34: send data internal data Buffer containing the data to be transmitted. size Length of the data in the data parameter. Places the specified data in the output queue. Call exec() to transmit this data to the server. 3.4.33 hook data 1 typedef boost : : function< void( const char, size t )> data f ; 2 void hook data( data f f ) ; Listing 35: hook data Registers a function for the data received events. 3.4.34 hook 7fff (unknown command response), command type )> data f ; 2 void hook 7fff ( data f f ) ; Listing 36: hook 7fff 20
Registers a function for the unknown command response events. If an remote station receives a command that is not implemented, it should send the unknown command response. This response conatain the received sequence number the the code (command type) of the unknown command. 3.4.35 hook login response 1 typedef boost : : function< void( byte type 2, timespan type 3, const std : : s t r i n g& )> f ; 4 5 void hook login response ( f ) ; Listing 37: hook login response Registers a function for the login response event. 3.4.36 hook 4004 (logout response) 1 typedef boost : : function< void( byte type 2, response type )> f ; 3 4 void hook 4004( f ) ; Listing 38: hook 4004 Registers a function for the logout response event. Note that there is nothing like logout request. If a client want to logout it send a logout response and the server will close related connection, targets and channels. It s good practice to use an explicit logout. On the other hand a simple close of TCP/IP sockets works great too. 21
3.4.37 hook 4005 (push target register response) 2, byte type 3, channel id type )> f ; 4 5 void hook 4005( f ) ; 6 7 // signature of function 8 void control push target register response ( sequence type seq 9, byte type response 10, channel id type channel number ) Listing 39: hook 4005 seq sequence number response Possible values are 0 (general fault), 1 (OK) or 2 (rejected) channel number channel number Each target is specified by an unique channel number. 3.4.38 hook 4006 (push target deregister response) 2, byte type 3, channel id type )> f ; 4 5 void hook 4006( f ) ; 6 7 // signature of function 8 bool control push target deregister response ( sequence type seq 9, byte type response 10, const std : : s t r i n g& target name ) Listing 40: hook 4006 seq sequence number response Possible values are 0 (general fault) or 1 (OK) target name target name 22
3.4.39 hook c005 (register target request) 2, const std : : s t r i n g& 3, packet size type 4, window size type )> f ; 5 6 void hook c005( f ) ; Listing 41: hook c005 See section 3.4.19 auf Seite 15. 3.4.40 hook c006 (deregister target request) 2, const std : : s t r i n g& )> f ; 3 4 void hook c006( f ) ; Listing 42: hook c006 See section 3.4.20 auf Seite 16. 3.4.41 hook c008 (watchdog request) )> f ; 2 void hook c008( f ) ; Listing 43: hook c008 23
Registers a function for the watchdog request event. 3.4.42 hook a000 (protocol version request) )> f ; 2 void hook a000( f ) ; Listing 44: hook a000 Registers a function for the protocol version request event. Base implementation answers with protocol version 1, if no other function was installed. 3.4.43 hook a001 (software version request) )> f ; 2 void hook a001( f ) ; Listing 45: hook a001 Registers a function for the software version request event. Base implementation sends the string 1.3 24
3.4.44 hook a003 (device identifier request) )> f ; 2 void hook a003( f ) ; Listing 46: hook a003 Registers a function for the device identifier request event. 3.4.45 hook a004 (network status request) )> f ; 2 void hook a004( f ) ; Listing 47: hook a004 Registers a function for the network status request event. 3.4.46 hook a005 (IP statistic request) )> f ; 2 void hook a005( f ) ; Listing 48: hook a004 Registers a function for the ip statistic request event. 25
3.4.47 hook a006 (device authentification request) )> f ; 2 void hook a006( f ) ; Listing 49: hook a006 Registers a function for the device authentification request event. Base implementation answers with unknown command. 3.4.48 hook a007 (device time request) )> f ; 2 void hook a007( f ) ; Listing 50: hook a007 Registers a function for the device time request event. Base implementation sends current system time in UTC. 3.4.49 hook a008 (push target namelist request) 2, const std : : s t r i n g& 3, const std : : s t r i n g& 4, const std : : s t r i n g& 5, const std : : s t r i n g& 6, const std : : s t r i n g& )> f ; 7 8 void hook a008( f ) ; Listing 51: hook a008 26
For a formal description of all parameters see section 3.4.18 auf Seite 15. 3.4.50 hook 2000 (protocol version response) 2, byte type )> f ; 3 void hook 2000( f ) ; Listing 52: hook 2000 Registers a function for the protocol version response event. 3.4.51 hook 2001 (software version response) 2, const std : : s t r i n g& )> f ; 3 void hook 2001( f ) ; Listing 53: hook 2001 Registers a function for the software version response event. 3.4.52 hook 2003 (device identifier response) 2, const std : : s t r i n g& )> f ; 3 void hook 2003( f ) ; Listing 54: hook 2003 27
Registers a function for the device identifier response event. 3.4.53 hook 2004 (network status response) 2, const network status& )> f ; 3 void hook 2004( f ) ; Listing 55: hook 2004 Registers a function for the network status response event. 3.4.54 hook 2005 (ip statistic response) 2, byte type 3, byte4 type 4, byte4 type )> f ; 5 void hook 2005( f ) ; Listing 56: hook 2005 Registers a function for the ip statistic response event. 28
3.4.55 hook 2006 (device authentification response) 2, const std : : s t r i n g& )> f ; 3 void hook 2006( f ) ; Listing 57: hook 2006 Registers a function for the device authentification response event. 3.4.56 hook 2007 (device time response), byte4 type )> f ; 2 void hook 2007( f ) ; Listing 58: hook 2007 Registers a function for the device time response event. 3.4.57 hook 9000 (push channel open request) 2, const std : : s t r i n g& // target name 3, const std : : s t r i n g& // owner account name 4, const std : : s t r i n g& // number 5, const std : : s t r i n g& // version 6, const std : : s t r i n g& // device id 7, const timespan type // timeout 8 )> f ; 9 10 void hook 9000( f ) ; Listing 59: hook 9000 29
Registers a function for the push channel open request event. For a formal description of the parameters see section 3.4.8 auf Seite 10. 3.4.58 hook 9001 (push channel close request) 2, channel id type // channel id 3 )> f ; 4 5 void hook 9001( f ) ; Listing 60: hook 9001 Registers a function for the push channel close request event. For a formal description of the parameters see section 3.4.9 auf Seite 11. 3.4.59 hook 9002 (push data transfer request) 2, channel id type // channel id 3, source id type // source id 4, status type // status 5, byte type // block number 6, length type // length of data array 7, const byte type // data 8 )> f ; 9 void hook 9002( f ) ; Listing 61: hook 9002 Registers a function for the push data transfer request event. This method is called, when receiving data from a push target. See section 3.4.10 auf Seite 11 too. Note 30
that the data pointer cannot be stored for later use. It will will be corrupted after leaving the scope of this method. It s highly recommented to make a copy of the data here. 3.4.60 hook 9003 (connection open request) 2, const std : : s t r i n g& )> f ; 3 void hook 9003( f ) ; Listing 62: hook 9003 Registers a function for the connection open request event. See also section?? auf Seite??. 3.4.61 hook 9004 (connection close request) ) > f ; 2 void hook 9004( f ) ; Listing 63: hook 9004 Registers a function for the connection close request event. See also section 3.4.7 auf Seite 10. 3.4.62 hook 1000 (push channel open response) 2, byte type 3, channel id type 4, source id type 5, packet size type 6, window size type 7, status type 31
8, byte4 type )> f ; 9 void hook 1000( f ) ; Listing 64: hook 1000 Registers a function for the push channel open response event. 3.4.63 hook 1001 (push channel close response) 2, channel id type )> f ; 3 void hook 1001( f ) ; Listing 65: hook 1001 Registers a function for the push channel close response event. 3.4.64 hook 1002 (push data transfer response) 2, response type 3, channel id type 4, source id type 5, status type 6, byte type )> f ; 7 void hook 1002( f ) ; Listing 66: hook 1002 Registers a function for the push data transfer response event. 32
3.5 Samples 3 API 3.4.65 hook 1003 (connection open response) 2, response type )> f ; 3 4 void hook 1003( f ) ; Listing 67: hook 1003 Registers a function for the connection open response event. Valid values for the response type are 0 (connection establishment failed), 1 (connection successfull established), 2 (line is busy), 3 (no connection to master) and 4 (remote station unreachable). 3.4.66 hook 1004 (connection close response) 2, response type )> f ; 3 void hook 1004( f ) ; Listing 68: hook 1004 Registers a function for the connection close response event. Valid values for the response type are 1 (success) or 2 (forbidden). The forbidden is typical for leased lines, since it s not possible to close a leased line from client side. 3.5 Samples 3.5.1 C++ Interface 1 2 #include <gex/gex log. h> 3 #include <gex/ slave / dll context. h> 4 5 void control login unsecured response ( gex : : byte type 6, gex : : timespan type watchdog 33
3.5 Samples 3 API 7, const std : : s t r i n g& ) 8 { 9 std : : cout << "watchdog: " << watchdog << std : : endl ; 10 } 11 12 int main( int argc, char argv [ ] ) 13 { 14 // i n i t i a l i z e logging framework 15 turban : : log4cxx base : : config () ; 16 17 gex : : i p t : : context ipt context ; 18 gex : : i p t : : i slave c l i e n t = ipt context. get slave interface () ; 19 i f (( c l i e n t!= NULL) && c l i e n t >sync connect ( "127.0.0.1", "5002" ) ) 20 { 21 std : : cout << "connected" << std : : endl ; 22 gex : : i pt : : command traits< 0x4001 >:: f cb = control login unsecured response ; 23 c l i e n t >hook login response ( cb ) ; 24 25 c l i e n t >l o g i n ( "dev_1000", "geheim", true ) ; 26 ipt context. run () ; 27 28 // wait 4 seconds f o r answer 29 : : Sleep ( 4000 ) ; 30 31 std : : s t r i n g l i n e ; 32 while ( c l i e n t >is authorized () ) 33 { 34 std : : cout 35 << "> " 36 << std : : f l u s h 37 ; 38 std : : g e t l i n e ( std : : cin, l i n e ) ; 39 i f ( l i n e == "q" ) break ; 40 } 41 std : : cout << "diconnected - good bye" << std : : endl ; 42 ipt context. stop () ; 43 } 44 45 46 return 0; 47 } 3.5.2 C Interface Listing 69: C++ Interface 1 2 #include <gex/gex log. h> 3 #include <gex/ slave / dll context. h> 4 5 extern "C" gex : : ipt : : i context create context interface ( ) ; 6 extern "C" void destroy context ( gex : : ipt : : i context i ) ; 7 8 int main( int argc, char argv [ ] ) 9 { 10 // i n i t i a l i z e logging framework 11 turban : : log4cxx base : : config () ; 12 test log t l ; 13 gex : : i p t : : i context c = : : create context interface ( ) ; 14 gex : : i p t : : i slave i = c >get slave interface () ; 15 i f ( i >sync connect ( "localhost", "5002" ) ) 34
3.5 Samples 3 API 16 { 17 std : : cout << "connected" << std : : endl ; 18 i >l o g i n ( "dev_1000", "geheim", false ) ; 19 c >run ( ) ; 20 21 // wait an terminate 22 : : Sleep ( 10000 ) ; 23 } 24 destroy context ( c ) ; 25 } Listing 70: C Interface 35