src/transport/transport-testing.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2006, 2009, 2015, 2016 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file transport-testing.h
  23  * @brief testing lib for transport service
  24  * @author Matthias Wachs
  25  * @author Christian Grothoff
  26  */
  27 #ifndef TRANSPORT_TESTING_H
  28 #define TRANSPORT_TESTING_H
  29 #include "platform.h"
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet_hello_lib.h"
  32 #include "gnunet_transport_service.h"
  33 #include "gnunet_testing_lib.h"
  34
  35
  36 /**
  37  * Context for a single peer
  38  */
  39 struct GNUNET_TRANSPORT_TESTING_PeerContext;
  40
  41 /**
  42  * Definition for a transport testing handle
  43  */
  44 struct GNUNET_TRANSPORT_TESTING_Handle;
  45
  46
  47 /**
  48  * Callback when two peers are connected and both have called the connect callback
  49  * to notify clients about a new peer
  50  */
  51 typedef void
  52 (*GNUNET_TRANSPORT_TESTING_StartCallback) (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
  53                                            void *cls);
  54
  55
  56 /**
  57  * Context for a single peer
  58  */
  59 struct GNUNET_TRANSPORT_TESTING_PeerContext
  60 {
  61   /**
  62    * Next element in the DLL
  63    */
  64   struct GNUNET_TRANSPORT_TESTING_PeerContext *next;
  65
  66   /**
  67    * Previous element in the DLL
  68    */
  69   struct GNUNET_TRANSPORT_TESTING_PeerContext *prev;
  70
  71   /**
  72    * Transport testing handle this peer belongs to
  73    */
  74   struct GNUNET_TRANSPORT_TESTING_Handle *tth;
  75
  76   /**
  77    * Peer's configuration
  78    */
  79   struct GNUNET_CONFIGURATION_Handle *cfg;
  80
  81   /**
  82    * Peer's transport service handle
  83    */
  84   struct GNUNET_TRANSPORT_Handle *th;
  85
  86   /**
  87    * Peer's ATS handle.
  88    */
  89   struct GNUNET_ATS_ConnectivityHandle *ats;
  90
  91   /**
  92    * Peer's transport get hello handle to retrieve peer's HELLO message
  93    */
  94   struct GNUNET_TRANSPORT_GetHelloHandle *ghh;
  95
  96   /**
  97    * Peer's testing handle
  98    */
  99   struct GNUNET_TESTING_Peer *peer;
 100
 101   /**
 102    * Peer identity
 103    */
 104   struct GNUNET_PeerIdentity id;
 105
 106   /**
 107    * Handle for the peer's ARM process
 108    */
 109   struct GNUNET_OS_Process *arm_proc;
 110
 111   /**
 112    * Receive callback
 113    */
 114   GNUNET_TRANSPORT_ReceiveCallback rec;
 115
 116   /**
 117    * Notify connect callback
 118    */
 119   GNUNET_TRANSPORT_NotifyConnect nc;
 120
 121   /**
 122    * Notify disconnect callback
 123    */
 124   GNUNET_TRANSPORT_NotifyDisconnect nd;
 125
 126   /**
 127    * Startup completed callback
 128    */
 129   GNUNET_TRANSPORT_TESTING_StartCallback start_cb;
 130
 131   /**
 132    * Peers HELLO Message
 133    */
 134   struct GNUNET_HELLO_Message *hello;
 135
 136   /**
 137    * Closure for the callbacks
 138    */
 139   void *cb_cls;
 140
 141   /**
 142    * An unique number to identify the peer
 143    */
 144   unsigned int no;
 145 };
 146
 147
 148 /**
 149  * Handle for a request to connect two peers.
 150  */
 151 struct GNUNET_TRANSPORT_TESTING_ConnectRequest
 152 {
 153   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *next;
 154   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *prev;
 155   struct GNUNET_TRANSPORT_TESTING_PeerContext *p1;
 156   struct GNUNET_TRANSPORT_TESTING_PeerContext *p2;
 157   struct GNUNET_SCHEDULER_Task *tct;
 158   struct GNUNET_ATS_ConnectivitySuggestHandle *ats_sh;
 159   struct GNUNET_TRANSPORT_OfferHelloHandle *oh;
 160   GNUNET_SCHEDULER_TaskCallback cb;
 161   void *cb_cls;
 162   int p1_c;
 163   int p2_c;
 164 };
 165
 166
 167 /**
 168  * Handle for a test run.
 169  */
 170 struct GNUNET_TRANSPORT_TESTING_Handle
 171 {
 172   /**
 173    * Testing library system handle
 174    */
 175   struct GNUNET_TESTING_System *tl_system;
 176
 177   /**
 178    * head DLL of connect contexts
 179    */
 180   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_head;
 181
 182   /**
 183    * head DLL of connect contexts
 184    */
 185   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_tail;
 186
 187   /**
 188    * head DLL of peers
 189    */
 190   struct GNUNET_TRANSPORT_TESTING_PeerContext *p_head;
 191
 192   /**
 193    * tail DLL of peers
 194    */
 195   struct GNUNET_TRANSPORT_TESTING_PeerContext *p_tail;
 196 };
 197
 198
 199 /**
 200  * Initialize the transport testing
 201  *
 202  * @return transport testing handle
 203  */
 204 struct GNUNET_TRANSPORT_TESTING_Handle *
 205 GNUNET_TRANSPORT_TESTING_init (void);
 206
 207
 208 /**
 209  * Clean up the transport testing
 210  *
 211  * @param tth transport testing handle
 212  */
 213 void
 214 GNUNET_TRANSPORT_TESTING_done (struct GNUNET_TRANSPORT_TESTING_Handle *tth);
 215
 216
 217 /**
 218  * Start a peer with the given configuration
 219  *
 220  * @param tth the testing handle
 221  * @param cfgname configuration file
 222  * @param peer_id the peer_id
 223  * @param rec receive callback
 224  * @param nc connect callback
 225  * @param nd disconnect callback
 226  * @param start_cb start callback
 227  * @param cb_cls closure for callback
 228  * @return the peer context
 229  */
 230 struct GNUNET_TRANSPORT_TESTING_PeerContext *
 231 GNUNET_TRANSPORT_TESTING_start_peer (struct GNUNET_TRANSPORT_TESTING_Handle *tth,
 232                                      const char *cfgname,
 233                                      int peer_id,
 234                                      GNUNET_TRANSPORT_ReceiveCallback rec,
 235                                      GNUNET_TRANSPORT_NotifyConnect nc,
 236                                      GNUNET_TRANSPORT_NotifyDisconnect nd,
 237                                      GNUNET_TRANSPORT_TESTING_StartCallback start_cb,
 238                                      void *cb_cls);
 239
 240
 241 /**
 242  * Shutdown the given peer
 243  *
 244  * @param p the peer
 245  */
 246 void
 247 GNUNET_TRANSPORT_TESTING_stop_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *pc);
 248
 249
 250 /**
 251  * Stops and restarts the given peer, sleeping (!) for 5s in between.
 252  *
 253  * @param p the peer
 254  * @param restart_cb restart callback
 255  * @param cb_cls callback closure
 256  * @return #GNUNET_OK in success otherwise #GNUNET_SYSERR
 257  */
 258 int
 259 GNUNET_TRANSPORT_TESTING_restart_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
 260                                        GNUNET_TRANSPORT_TESTING_StartCallback restart_cb,
 261                                        void *cb_cls);
 262
 263
 264
 265 /**
 266  * Connect the given peers and call the callback when both peers
 267  * report the inbound connection. Remarks: start_peer's notify_connect
 268  * callback can be called before.
 269  *
 270  * @param p1 peer 1
 271  * @param p2 peer 2
 272  * @param cb the callback to call when both peers notified that they are connected
 273  * @param cls callback cls
 274  * @return a connect request handle
 275  */
 276 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *
 277 GNUNET_TRANSPORT_TESTING_connect_peers (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
 278                                         struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
 279                                         GNUNET_SCHEDULER_TaskCallback cb,
 280                                         void *cls);
 281
 282
 283 /**
 284  * Cancel the request to connect two peers.  You MUST cancel the
 285  * request if you stop the peers before the peers connected
 286  * succesfully.
 287  *
 288  * @param cc a connect request handle
 289  */
 290 void
 291 GNUNET_TRANSPORT_TESTING_connect_peers_cancel (struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
 292
 293 /* ********************** high-level process functions *************** */
 294
 295
 296 /**
 297  * Main function of a testcase.  Called with the initial setup data
 298  * for the test as derived from the source name and the binary name.
 299  *
 300  * @param cls closure
 301  * @param tth initialized testing handle
 302  * @param test_plugin name of the plugin (if available)
 303  * @param num_peers number of entries in the @a cfg_file array
 304  * @param cfg_files array of names of configuration files for the peers
 305  */
 306 typedef void
 307 (*GNUNET_TRANSPORT_TESTING_CheckCallback)(void *cls,
 308                                           struct GNUNET_TRANSPORT_TESTING_Handle *tth,
 309                                           const char *test_plugin,
 310                                           unsigned int num_peers,
 311                                           const char *cfg_files[]);
 312
 313
 314 /**
 315  * Setup testcase.  Calls @a check with the data the test needs.
 316  *
 317  * @param argv0 binary name (argv[0])
 318  * @param filename source file name (__FILE__)
 319  * @param num_peers number of peers to start
 320  * @param check main function to run
 321  * @param check_cls closure for @a check
 322  * @return #GNUNET_OK on success
 323  */
 324 int
 325 GNUNET_TRANSPORT_TESTING_main_ (const char *argv0,
 326                                 const char *filename,
 327                                 unsigned int num_peers,
 328                                 GNUNET_TRANSPORT_TESTING_CheckCallback check,
 329                                 void *check_cls);
 330
 331
 332 /**
 333  * Setup testcase.  Calls @a check with the data the test needs.
 334  *
 335  * @param num_peers number of peers to start
 336  * @param check main function to run
 337  * @param check_cls closure for @a check
 338  * @return #GNUNET_OK on success
 339  */
 340 #define GNUNET_TRANSPORT_TESTING_main(num_peers,check,check_cls) \
 341   GNUNET_TRANSPORT_TESTING_main_ (argv[0], __FILE__, num_peers, check, check_cls)
 342
 343
 344 /* ********************** low-level filename functions *************** */
 345
 346
 347 /**
 348  * Extracts the test filename from an absolute file name and removes
 349  * the extension.
 350  *
 351  * @param file absolute file name
 352  * @return resulting test name
 353  */
 354 char *
 355 GNUNET_TRANSPORT_TESTING_get_test_name (const char *file);
 356
 357
 358 /**
 359  * This function takes the filename (e.g. argv[0), removes a "lt-"-prefix and
 360  * if existing ".exe"-prefix and adds the peer-number
 361  *
 362  * @param file filename of the test, e.g. argv[0]
 363  * @param count peer number
 364  * @return configuration name to use
 365  */
 366 char *
 367 GNUNET_TRANSPORT_TESTING_get_config_name (const char *file,
 368                                           int count);
 369
 370
 371 /**
 372  * Extracts the plugin anme from an absolute file name and the test name
 373  * @param file absolute file name
 374  * @param test test name
 375  * @return the plugin name
 376  */
 377 char *
 378 GNUNET_TRANSPORT_TESTING_get_test_plugin_name (const char *executable,
 379                                                const char *testname);
 380
 381
 382 /**
 383  * Extracts the filename from an absolute file name and removes the
 384  * extenstion
 385  *
 386  * @param file absolute file name
 387  * @return the source name
 388  */
 389 char *
 390 GNUNET_TRANSPORT_TESTING_get_test_source_name (const char *file);
 391
 392 #endif
 393 /* end of transport_testing.h */