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 Programmbi-bliothek f¨ur Windows- und Linux Systeme bereit. Die jeweils aktuelle Basis-Variante steht auf der Produkthomepage im Downloadbereich zum Down-load bereit.
Inhaltsverzeichnis
1 History / Revision 3
2 Einf¨uhrung 4
2.1 Uberblick¨ . . . 4
2.2 Unterst¨utzte Betriebssysteme . . . 4
2.3 Abh¨angigkeiten . . . 5
2.4 Redistributable Code and Sample Code . . . 5
3 API 5 3.1 Uberblick¨ . . . 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
∗
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.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
(Forts.)
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
Tabelle 1: Revisionsbericht
2 Einf¨
uhrung
2.1 ¨Uberblick
GEx-Client API ist eine Programmbibliothek, die zum Schreiben von Scripts und Pro-grammen dient, die ¨uber 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¨ur Anwendungsprogrammierer geeignet. Die GEx-Client API wurde f¨ur folgende Anwendergruppen entwickelt:
Technisch interessierte Anwender Zum Beispiel, Leute aus der IT-Abteilung, die
be-stimmte 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¨ochten.
2.2 Unterst¨utzte Betriebssysteme
Die GEx-Client API l¨auft auf Microsoft Windows (ab XP) und Linux (ab Kernel 2.4.x). Auf 64-bit Systemen k¨onnen 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¨ugung. Auch Bridges zu anderen Program-miersprachen, wie Java, PHP oder Smalltalk k¨onnen damit leicht erstellt werden.
2.3 Abh¨angigkeiten
Neben der C-Runtime existieren Abh¨angigkeiten zu folgenden Bibliotheken:
Boost ab 1.39.0 Aus derBoost-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¨alt1.
Die notwendigen Libraries liegen der Distribution in bin¨arer 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 client.lib • gex client.dll • gex client.so • gex client.h
Redistribution of the open source libraries included with the GExClient API is gover-ned 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 ¨Uberblick
Einen ¨Uberblick, wie die GEx-Client API eingebunden wird, gibt Abbildung1.
Die GEx-Client API besitzt zwei wesentliche Eigenschaften. Die erste Eigenschaft ist der Context. Bevor ein Zugriff auf die gew¨unschte Funktionalit¨at m¨oglich ist, muss
Abbildung 1: Einbinden der GEx-Client API
zun¨achst ein Context erstellt werden. Aus den Beispielprogrammen ist ersichtlich, wie das erfolgt. In der Basis-Variante stellt derContext jeweils nur ein Interface (was einer Verbindung entspricht) zur Verf¨ugung. In der Enterprise-Variante gibt es keine Beschr¨ an-kung.
Die zweite wesentliche Eigenschaft ist das Callback-Interface. Durch die asynchrone Arbeitsweise wird ein flexibler Mechanismus ben¨otigt, um auf die eintretenden Ereignisse zu reagieren. Zun¨achst stellt die GEx-Client API default-Mechanismen zur Verf¨ugung, um z.B. auf Watchdogs oder Abfragen korrekt zu reagieren. Jedes Ereignis kann aber ¨
uber eigene Callback-Routine abgefangen werden, um eine andere Reaktionsweise zu implementieren. Von zentraler Bedeutung ist der Empfang von Daten, der ¨uber die Methodehook_data() abgefangen werden kann (siehe Referenz 3.4.33 auf Seite 20).
3.2 Architektur
Siehe Abbildung2 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-allfolder. It contains two
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
• 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 themakefilecommand should generate the libgex client.so file.
3.4 Functions Reference
3.4.1 sync connect
TCP/IP
1 bool sync connect ( const s t d : : s t r i n g& address , 2 const s t d : : s t r i n g& s e r v i c e ) ;
Listing 1: sync connect
Parameters
address host name
service service name or port
Return Value
true if TCP/IP connect succeeded.
Remarks
(none)
3.4.2 login
control
1 void l o g i n ( const s t d : : s t r i n g& account , 2 const s t d : : s t r i n g& password ,
3 bool scrambled ) ;
Listing 2: sync connect
Parameters
account device name
password password
Return Value
(void)
Remarks
Send login request to server.
3.4.3 control logout response
control
1 void l o g i n ( response type r e a s o n ) ;
Listing 3: sync connect
Parameters
reason Reason for logout. Possible values are 0 (internal error) and 1 (normal logout).
Return Value
(void)
Remarks
To catch this response see section3.4.36 auf Seite 21.
3.4.4 control watchdog response
control
1 void control watchdog response ( ) ;
Listing 4: control watchdog response
Parameters
(none)
Return Value
(void)
Remarks
Response without request get sequence number 0.
3.4.5 control watchdog request
control
1 sequence type
2 control watchdog request ( ) ;
Listing 5: control watchdog request
Parameters
(none)
Return Value
Remarks
The server should send a watchdog response.
3.4.6 transport connection open request
transport
1 sequence type
2 transport connection open request ( const s t d : : s t r i n g& number ) ;
Listing 6: transport connection open request
Parameters
number virtual number to call
Return Value
Sequence number.
Remarks
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
transport
1 sequence type transport connection open request ( ) ;
Listing 7: transport connection close request
Parameters
(none)
Return Value
Sequence number.
Remarks
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
transport
1 sequence type
2 transport push channel open request ( const s t d : : s t r i n g& t a r g e t 3 , const s t d : : s t r i n g& account
4 , const s t d : : s t r i n g& number 5 , const s t d : : s t r i n g& v e r s i o n 6 , const s t d : : s t r i n g& device id 7 , const timespan type ack time out ) ;
Listing 8: transport push channel open request
Parameters
account device name
number phone number
version firmware version
device id device id
ack time out timeout in seconds
Return Value
Sequence number.
Remarks
Place the IP-T command of operationtransport 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
transport
1 sequence type
2 transport push channel close request ( channel id type channel id ) ;
Listing 9: transport push channel close request
Parameters
channel id channel id. Comes with the corresponding transport push channel open
response.
Return Value
Sequence number.
Remarks
Place the IP-T command of operationtransport 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
transport
1 sequence type
2 transport push data transfer request ( channel id type channel number 3 , source id type source id
4 , status type s t a t u s 5 , byte type block number
6 , const gex : : i p t : : push data& data )
Listing 10: transport push data transfer request To send a C-string use the following method:
1 sequence type
2 transport push data transfer request ( channel id type channel number 3 , source id type source id
4 , status type s t a t u s 5 , byte type block number 6 , const s t d : : s t r i n g& s t r )
Listing 11: transport push data transfer request (string) To send a file use this:
1 bool
2 transport push data transfer request ( channel id type channel number 3 , source id type source id
4 , const s t d : : s t r i n g& file name )
Listing 12: transport push data transfer request (file)
Parameters
channel number channel number. Comes with the corresponding transport push
chan-nel open response.
source id source id. Comes with the correspondingtransport push channel open respon-se.
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.
Return Value
Sequence number.
Remarks
Place the IP-T command of operationtransport push transfer request in command queue. The server answers with transport push data transfer response. See3.4.64 auf Seite 32.
3.4.11 app protocol version request
app
1 sequence type app protocol version request ( ) ;
Listing 13: app protocol version request
Parameters
Return Value
Sequence number.
Remarks
See section 3.4.50 auf Seite 27.
3.4.12 app device software version request
app
1 sequence type app device software version request ( ) ;
Listing 14: app device software version request
Parameters
(none)
Return Value
Sequence number.
Remarks
See section 3.4.51 auf Seite 27.
3.4.13 app device identifier request
app
1 sequence type a p p d e v i c e i d e n t i f i e r r e q u e s t ( ) ;
Listing 15: app device identifier request
Parameters
(none)
Return Value
Sequence number.
Remarks
See section 3.4.52 auf Seite 27.
3.4.14 app network status request
app
1 sequence type app network status request ( ) ;
Listing 16: app network status request
Parameters
(none)
Return Value
Sequence number.
Remarks
3.4.15 app ip statistic request
app
1 sequence type a p p i p s t a t i s t i c r e q u e s t ( ) ;
Listing 17: app ip statistic request
Parameters
(none)
Return Value
Sequence number.
Remarks
See section 3.4.54 auf Seite 28.
3.4.16 app device authentification request
app
1 sequence type a p p d e v i c e a u t h e n t i f i c a t i o n r e q u e s t ( ) ;
Listing 18: app device authentification request
Parameters
(none)
Return Value
Sequence number.
Remarks
See section 3.4.55 auf Seite 29.
3.4.17 app device time request
app
1 sequence type app device time request ( ) ;
Listing 19: app device time request
Parameters
(none)
Return Value
Sequence number.
Remarks
3.4.18 app push target namelist request
app
1 sequence type
2 app push target namelist request ( const s t d : : s t r i n g& t a r g e t 3 , const s t d : : s t r i n g& account
4 , const s t d : : s t r i n g& number 5 , const s t d : : s t r i n g& v e r s i o n 6 , const s t d : : s t r i n g& i d ) ;
Listing 20: app push target namelist request
Parameters
target Target name
account Device name
number Virtual phone number
version Software version
id Device identifier
Return Value
Sequence number.
Remarks
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
control
1 sequence type
2 app push target register request ( const s t d : : s t r i n g& t a r g e t 3 , packet size type p a c k e t s i z e
4 , window size type window size ) ;
Listing 21: control push target register request
Parameters
target Target name to register
packet size maximum packet size
window size maximum windows size. Currently 1 is the only valid value.
Return Value
Remarks
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
control
1 sequence type
2 c o nt ro l pu s h t ar ge t d er eg i st e r r equ es t ( const s t d : : s t r i n g& t a r g e t ) ;
Listing 22: control push target deregister request
Parameters
target Target name to deregister
Return Value
Sequence number.
Remarks
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 section3.4.18 auf Seite 15).
3.4.21 is open
status
1 bool is open ( ) const;
Listing 23: is open
Parameters
(none)
Return Value
Determine whether the TCP/IP connection is open.
Remarks (none) 3.4.22 is authorized status 1 bool i s a u t h o r i z e d ( ) const; Listing 24: is authorized Parameters (none)
Return Value
true if client is successful authorized.
Remarks
(none)
3.4.23 is connection open
status
1 bool is connection open ( ) const;
Listing 25: is connection open
Parameters
(none)
Return Value
true if client is part of a circuit switch or a leased line.
Remarks
(none)
3.4.24 get watchdog
status
1 timespan type get watchdog ( ) const;
Listing 26: get watchdog
Parameters
(none)
Return Value
Watchdog time in minutes.
Remarks
A value of zero indicates that no watchdog is running.
3.4.25 start watchdog
status
1 bool start watchdog ( unsigned s e c ) ;
Listing 27: start watchdog
Parameters
sec Duration of watchdog in seconds.
Return Value
Remarks
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
status
1 bool cancel watchdog ( )
Listing 28: cancel watchdog
Parameters
(none)
Return Value
true if if timer was canceled successful
Remarks
Only a running timer should be cancelled. When terminating the application, the wat-chdog timer will be cancelled automatically.
3.4.27 get local ipv4 address
status
1 unsigned long get local ipv4 address ( ) const;
Listing 29: get local ipv4 address
Parameters
(none)
Return Value
Get the address as an unsigned long in host byte order.
Remarks
(none)
3.4.28 get remote ipv4 address
status
1 unsigned long get remote ipv4 address ( ) const;
Listing 30: get remote ipv4 address
Parameters
(none)
Return Value
Get the address as an unsigned long in host byte order.
Remarks
3.4.29 get local port
status
1 unsigned short get local port ( ) const;
Listing 31: get local port
Parameters
(none)
Return Value
Get the port associated with the local endpoint. The port number is always in the host’s byte order.
Remarks
(none)
3.4.30 get remote port
status
1 unsigned short get remote port ( ) const;
Listing 32: get remote port
Parameters
(none)
Return Value
Get the port associated with the remote endpoint. The port number is always in the host’s byte order.
Remarks (none) 3.4.31 exec internal 1 void exec ( ) ; Listing 33: exec Parameters (none) Return Value (none) Remarks
3.4.32 send data
internal
1 void send data ( const char∗ data , 2 s t d : : s i z e t s i z e ) ;
Listing 34: send data
Parameters
data Buffer containing the data to be transmitted.
size Length of the data in the data parameter.
Return Value
(none)
Remarks
Places the specified data in the output queue. Call exec() to transmit this data to the server.
3.4.33 hook data
callback
1 typedef boost : : f u n c t i o n< void( const char∗, s i z e t )> data callback f ; 2 void hook data ( data callback f f ) ;
Listing 35: hook data
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the data received events.
3.4.34 hook 7fff (unknown command response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type , command type )> data callback f ; 2 void hook 7fff ( data callback f f ) ;
Listing 36: hook 7fff
Parameters
f Callback function
Return Value
Remarks
Registers a callback function for the unknown command response events. If an remo-te station receives a command that is not implemenremo-ted, 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
callback
1 typedef boost : : f u n c t i o n< void( byte type 2 , timespan type
3 , const s t d : : s t r i n g& )> c a l l b a c k f ; 4
5 void hook login response ( c a l l b a c k f ) ;
Listing 37: hook login response
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the login response event.
3.4.36 hook 4004 (logout response)
callback
1 typedef boost : : f u n c t i o n< void( byte type 2 , response type )> c a l l b a c k f ; 3 4 void hook 4004 ( c a l l b a c k f ) ; Listing 38: hook 4004 Parameters f Callback function Return Value (none) Remarks
Registers a callback 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.
3.4.37 hook 4005 (push target register response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type
2 , byte type 3 , channel id type )> c a l l b a c k f ; 4 5 void hook 4005 ( c a l l b a c k f ) ; 6 7 // s i g n a t u r e o f c a l l b a c k f u n c t i o n
8 void cont rol push tar get reg ister res ponse ( sequence type seq 9 , byte type r e s p o n s e
10 , channel id type channel number )
Listing 39: hook 4005
Parameters
f Callback function
seq sequence number
response Possible values are 0 (general fault), 1 (OK) or 2 (rejected)
channel number channel number
Return Value
(none)
Remarks
Each target is specified by an unique channel number.
3.4.38 hook 4006 (push target deregister response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type
2 , byte type 3 , channel id type )> c a l l b a c k f ; 4 5 void hook 4006 ( c a l l b a c k f ) ; 6 7 // s i g n a t u r e o f c a l l b a c k f u n c t i o n
8 bool control push target deregister response ( sequence type seq 9 , byte type r e s p o n s e
10 , const s t d : : s t r i n g& target name )
Listing 40: hook 4006
Parameters
f Callback function
seq sequence number
response Possible values are 0 (general fault) or 1 (OK)
Return Value
(none)
Remarks
(none)
3.4.39 hook c005 (register target request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g&
3 , packet size type
4 , window size type )> c a l l b a c k f ; 5 6 void hook c005 ( c a l l b a c k f ) ; Listing 41: hook c005 Parameters f Callback function Return Value (none) Remarks
See section 3.4.19 auf Seite 15.
3.4.40 hook c006 (deregister target request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& )> c a l l b a c k f ; 3 4 void hook c006 ( c a l l b a c k f ) ; Listing 42: hook c006 Parameters f Callback function Return Value (none) Remarks
See section 3.4.20 auf Seite 16.
3.4.41 hook c008 (watchdog request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook c008 ( c a l l b a c k f ) ;
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the watchdog request event.
3.4.42 hook a000 (protocol version request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a000 ( c a l l b a c k f ) ;
Listing 44: hook a000
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for theprotocol version request event. Base implementation answers with protocol version 1, if no other callback function was installed.
3.4.43 hook a001 (software version request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a001 ( c a l l b a c k f ) ;
Listing 45: hook a001
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for thesoftware version request event. Base implementation sends the string1.3
3.4.44 hook a003 (device identifier request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a003 ( c a l l b a c k f ) ;
Listing 46: hook a003
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the device identifier request event.
3.4.45 hook a004 (network status request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a004 ( c a l l b a c k f ) ;
Listing 47: hook a004
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the network status request event.
3.4.46 hook a005 (IP statistic request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a005 ( c a l l b a c k f ) ;
Listing 48: hook a004
Parameters
f Callback function
Return Value
(none)
Remarks
3.4.47 hook a006 (device authentification request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a006 ( c a l l b a c k f ) ;
Listing 49: hook a006
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the device authentification request event. Base imple-mentation answers withunknown command.
3.4.48 hook a007 (device time request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type )> c a l l b a c k f ; 2 void hook a007 ( c a l l b a c k f ) ;
Listing 50: hook a007
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the device time request event. Base implementation sends current system time in UTC.
3.4.49 hook a008 (push target namelist request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& 3 , const s t d : : s t r i n g& 4 , const s t d : : s t r i n g& 5 , const s t d : : s t r i n g& 6 , const s t d : : s t r i n g& )> c a l l b a c k f ; 7
8 void hook a008 ( c a l l b a c k f ) ;
Listing 51: hook a008
Parameters
Return Value
(none)
Remarks
For a formal description of all callback parameters see section 3.4.18 auf Seite 15.
3.4.50 hook 2000 (protocol version response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , byte type )> c a l l b a c k f ; 3 void hook 2000 ( c a l l b a c k f ) ; Listing 52: hook 2000 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the protocol version response event.
3.4.51 hook 2001 (software version response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& )> c a l l b a c k f ; 3 void hook 2001 ( c a l l b a c k f ) ; Listing 53: hook 2001 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the software version response event.
3.4.52 hook 2003 (device identifier response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& )> c a l l b a c k f ;
3 void hook 2003 ( c a l l b a c k f ) ;
Parameters
f Callback function
Return Value
(none)
Remarks
Registers a callback function for the device identifier response event.
3.4.53 hook 2004 (network status response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const network status& )> c a l l b a c k f ; 3 void hook 2004 ( c a l l b a c k f ) ; Listing 55: hook 2004 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the network status response event.
3.4.54 hook 2005 (ip statistic response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , byte type 3 , byte4 type 4 , byte4 type )> c a l l b a c k f ; 5 void hook 2005 ( c a l l b a c k f ) ; Listing 56: hook 2005 Parameters f Callback function Return Value (none) Remarks
3.4.55 hook 2006 (device authentification response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& )> c a l l b a c k f ; 3 void hook 2006 ( c a l l b a c k f ) ; Listing 57: hook 2006 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the device authentification response event.
3.4.56 hook 2007 (device time response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type , byte4 type )> c a l l b a c k f ; 2 void hook 2007 ( c a l l b a c k f ) ; Listing 58: hook 2007 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the device time response event.
3.4.57 hook 9000 (push channel open request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& // t a r g e t name
3 , const s t d : : s t r i n g& // owner account name
4 , const s t d : : s t r i n g& // number
5 , const s t d : : s t r i n g& // v e r s i o n
6 , const s t d : : s t r i n g& // d e v i c e i d
7 , const timespan type // timeout
8 )> c a l l b a c k f ; 9 10 void hook 9000 ( c a l l b a c k f ) ; Listing 59: hook 9000 Parameters f Callback function
Return Value
(none)
Remarks
Registers a callback function for the push channel open request event. For a formal description of the callback parameters see section 3.4.8 auf Seite 10.
3.4.58 hook 9001 (push channel close request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , channel id type // channel i d
3 )> c a l l b a c k f ; 4 5 void hook 9001 ( c a l l b a c k f ) ; Listing 60: hook 9001 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the push channel close request event. For a formal description of the callback parameters see section 3.4.9 auf Seite 11.
3.4.59 hook 9002 (push data transfer request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , channel id type // channel i d
3 , source id type // s o u r c e i d
4 , status type // s t a t u s
5 , byte type // b l o c k number
6 , length type // l e n g t h o f data a r r a y
7 , const byte type∗ // data
8 )> c a l l b a c k f ; 9 void hook 9002 ( c a l l b a c k f ) ; Listing 61: hook 9002 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the push data transfer request event. This method is called, when receiving data from a push target. See section3.4.10 auf Seite 11too. Note
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)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , const s t d : : s t r i n g& )> c a l l b a c k f ; 3 void hook 9003 ( c a l l b a c k f ) ; Listing 62: hook 9003 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for theconnection open request event. See also section ??
auf Seite ??.
3.4.61 hook 9004 (connection close request)
callback
1 typedef boost : : f u n c t i o n< void( sequence type ) > c a l l b a c k f ; 2 void hook 9004 ( c a l l b a c k f ) ; Listing 63: hook 9004 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for theconnection close requestevent. See also section3.4.7 auf Seite 10.
3.4.62 hook 1000 (push channel open response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type
2 , byte type
3 , channel id type 4 , source id type 5 , packet size type 6 , window size type 7 , status type
8 , byte4 type )> c a l l b a c k f ; 9 void hook 1000 ( c a l l b a c k f ) ; Listing 64: hook 1000 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the push channel open response event.
3.4.63 hook 1001 (push channel close response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , channel id type )> c a l l b a c k f ; 3 void hook 1001 ( c a l l b a c k f ) ; Listing 65: hook 1001 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for the push channel close response event.
3.4.64 hook 1002 (push data transfer response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , response type 3 , channel id type 4 , source id type 5 , status type 6 , byte type )> c a l l b a c k f ; 7 void hook 1002 ( c a l l b a c k f ) ; Listing 66: hook 1002 Parameters f Callback function Return Value (none) Remarks
3.4.65 hook 1003 (connection open response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , response type )> c a l l b a c k f ; 3 4 void hook 1003 ( c a l l b a c k f ) ; Listing 67: hook 1003 Parameters f Callback function Return Value (none) Remarks
Registers a callback function for theconnection open response event. Valid values for the response type are 0 (connection establishment failed), 1 (connection successfull establis-hed), 2 (line is busy), 3 (no connection to master) and 4 (remote station unreachable).
3.4.66 hook 1004 (connection close response)
callback
1 typedef boost : : f u n c t i o n< void( sequence type 2 , response type )> c a l l b a c k f ; 3 void hook 1004 ( c a l l b a c k f ) ; Listing 68: hook 1004 Parameters f Callback function Return Value (none) Remarks
Registers a callback 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 / s l a v e / d l l c o n t e x t . h>
4
5 void control login unsecured response ( gex : : byte type 6 , gex : : timespan type watchdog
7 , const s t d : : s t r i n g& ) 8 {
9 s t d : : cout << " watchdog : " << watchdog << s t d : : e n d l ; 10 }
11
12 int main (int argc , char∗ argv [ ] ) 13 {
14 // i n i t i a l i z e l o g g i n g framework
15 turban : : log4cxx base : : c o n f i g ( ) ; 16
17 gex : : i p t : : c o n t e x t ipt context ;
18 gex : : i p t : : i s l a v e∗ c l i e n t = ipt context . g e t s l a v e i n t e r f a c e ( ) ; 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 s t d : : cout << " connected " << s t d : : e n d l ;
22 gex : : i p t : : command traits< 0x4001 >:: c a l l b a c k 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 sec onds f o r answer
29 : : S l e e p ( 4000 ) ; 30 31 s t d : : s t r i n g l i n e ; 32 while( c l i e n t−>i s a u t h o r i z e d ( ) ) 33 { 34 s t d : : cout 35 << "> " 36 << s t d : : f l u s h 37 ; 38 s t d : : g e t l i n e ( s t d : : ci n , l i n e ) ; 39 i f ( l i n e =="q") break; 40 }
41 s t d : : cout << " diconnected - good bye " << s t d : : e n d l ; 42 ipt context . s t o p ( ) ; 43 } 44 45 46 return 0 ; 47 } Listing 69: C++ Interface 3.5.2 C Interface 1
2 #include <gex / gex log . h>
3 #include <gex / s l a v e / d l l c o n t e x t . h>
4
5 extern "C" gex : : i p t : : i context∗ c r e a t e c o n t e x t i n t e r f a c e ( ) ; 6 extern "C" void destroy context ( gex : : i p t : : i context∗ i ) ; 7
8 int main (int argc , char∗ argv [ ] ) 9 {
10 // i n i t i a l i z e l o g g i n g framework
11 turban : : log4cxx base : : c o n f i g ( ) ; 12 t e s t l o g t l ;
13 gex : : i p t : : i context∗ c = : : c r e a t e c o n t e x t i n t e r f a c e ( ) ; 14 gex : : i p t : : i s l a v e∗ i = c−>g e t s l a v e i n t e r f a c e ( ) ; 15 i f ( i−>sync connect ( " localhost ", " 5002 " ) )
16 { 17 s t d : : cout << " connected " << s t d : : e n d l ; 18 i−>l o g i n ( " dev_1000 ", " geheim ", f a l s e ) ; 19 c−>run ( ) ; 20 21 // wait an t e r m i n a t e 22 : : S l e e p ( 10000 ) ; 23 } 24 destroy context ( c ) ; 25 } Listing 70: C Interface
