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 /* ************* Basic functions for starting/stopping/connecting *********** */
  37
  38 /**
  39  * Context for a single peer
  40  */
  41 struct GNUNET_TRANSPORT_TESTING_PeerContext;
  42
  43 /**
  44  * Definition for a transport testing handle
  45  */
  46 struct GNUNET_TRANSPORT_TESTING_Handle;
  47
  48
  49 /**
  50  * Callback when two peers are connected and both have called the connect callback
  51  * to notify clients about a new peer
  52  *
  53  * @param p FIXME: remove ASAP.
  54  * @param cls closure
  55  */
  56 typedef void
  57 (*GNUNET_TRANSPORT_TESTING_StartCallback) (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
  58                                            void *cls);
  59
  60
  61
  62 /**
  63  * Context for a single peer
  64  */
  65 struct GNUNET_TRANSPORT_TESTING_PeerContext
  66 {
  67   /**
  68    * Next element in the DLL
  69    */
  70   struct GNUNET_TRANSPORT_TESTING_PeerContext *next;
  71
  72   /**
  73    * Previous element in the DLL
  74    */
  75   struct GNUNET_TRANSPORT_TESTING_PeerContext *prev;
  76
  77   /**
  78    * Transport testing handle this peer belongs to
  79    */
  80   struct GNUNET_TRANSPORT_TESTING_Handle *tth;
  81
  82   /**
  83    * Peer's configuration
  84    */
  85   struct GNUNET_CONFIGURATION_Handle *cfg;
  86
  87   /**
  88    * Peer's transport service handle
  89    */
  90   struct GNUNET_TRANSPORT_Handle *th;
  91
  92   /**
  93    * Peer's ATS handle.
  94    */
  95   struct GNUNET_ATS_ConnectivityHandle *ats;
  96
  97   /**
  98    * Peer's transport get hello handle to retrieve peer's HELLO message
  99    */
 100   struct GNUNET_TRANSPORT_GetHelloHandle *ghh;
 101
 102   /**
 103    * Peer's testing handle
 104    */
 105   struct GNUNET_TESTING_Peer *peer;
 106
 107   /**
 108    * Peer identity
 109    */
 110   struct GNUNET_PeerIdentity id;
 111
 112   /**
 113    * Handle for the peer's ARM process
 114    */
 115   struct GNUNET_OS_Process *arm_proc;
 116
 117   /**
 118    * Receive callback
 119    */
 120   GNUNET_TRANSPORT_ReceiveCallback rec;
 121
 122   /**
 123    * Notify connect callback
 124    */
 125   GNUNET_TRANSPORT_NotifyConnect nc;
 126
 127   /**
 128    * Notify disconnect callback
 129    */
 130   GNUNET_TRANSPORT_NotifyDisconnect nd;
 131
 132   /**
 133    * Startup completed callback
 134    */
 135   GNUNET_TRANSPORT_TESTING_StartCallback start_cb;
 136
 137   /**
 138    * Peers HELLO Message
 139    */
 140   struct GNUNET_HELLO_Message *hello;
 141
 142   /**
 143    * Closure for the @a nc and @a nd callbacks
 144    */
 145   void *cb_cls;
 146
 147   /**
 148    * Closure for @e start_cb.
 149    */
 150   void *start_cb_cls;
 151
 152   /**
 153    * An unique number to identify the peer
 154    */
 155   unsigned int no;
 156 };
 157
 158
 159 /**
 160  * Handle for a request to connect two peers.
 161  */
 162 struct GNUNET_TRANSPORT_TESTING_ConnectRequest
 163 {
 164   /**
 165    * Kept in a DLL.
 166    */
 167   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *next;
 168
 169   /**
 170    * Kept in a DLL.
 171    */
 172   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *prev;
 173
 174   /**
 175    * Peer we want to connect.
 176    */
 177   struct GNUNET_TRANSPORT_TESTING_PeerContext *p1;
 178
 179   /**
 180    * Peer we want to connect.
 181    */
 182   struct GNUNET_TRANSPORT_TESTING_PeerContext *p2;
 183
 184   /**
 185    * Task by which we accomplish the connection.
 186    */
 187   struct GNUNET_SCHEDULER_Task *tct;
 188
 189   /**
 190    * Handle by which we ask ATS to faciliate the connection.
 191    */
 192   struct GNUNET_ATS_ConnectivitySuggestHandle *ats_sh;
 193
 194   /**
 195    * Handle by which we inform the peer about the HELLO of
 196    * the other peer.
 197    */
 198   struct GNUNET_TRANSPORT_OfferHelloHandle *oh;
 199
 200   /**
 201    * Function to call upon completion.
 202    */
 203   GNUNET_SCHEDULER_TaskCallback cb;
 204
 205   /**
 206    * Closure for @e cb.
 207    */
 208   void *cb_cls;
 209
 210   /**
 211    * Set if peer1 says the connection is up to peer2.
 212    */
 213   int p1_c;
 214
 215   /**
 216    * Set if peer2 says the connection is up to peer1.
 217    */
 218   int p2_c;
 219
 220   /**
 221    * #GNUNET_YES if both @e p1_c and @e p2_c are #GNUNET_YES.
 222    */
 223   int connected;
 224 };
 225
 226
 227 /**
 228  * Information we keep for active transmission jobs.
 229  */
 230 struct TRANSPORT_TESTING_SendJob
 231 {
 232
 233   /**
 234    * Kept in a DLL.
 235    */
 236   struct TRANSPORT_TESTING_SendJob *next;
 237
 238   /**
 239    * Kept in a DLL.
 240    */
 241   struct TRANSPORT_TESTING_SendJob *prev;
 242
 243   /**
 244    * Sender of the message.
 245    */
 246   struct GNUNET_TRANSPORT_TESTING_PeerContext *sender;
 247
 248   /**
 249    * Receiver of the message.
 250    */
 251   struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver;
 252
 253   /**
 254    * Operation handle.
 255    */
 256   struct GNUNET_TRANSPORT_TransmitHandle *th;
 257
 258   /**
 259    * Function to call upon completion.
 260    */
 261   GNUNET_SCHEDULER_TaskCallback cont;
 262
 263   /**
 264    * Closure for @e cont.
 265    */
 266   void *cont_cls;
 267
 268   /**
 269    * Number of the message.
 270    */
 271   uint32_t num;
 272
 273   /**
 274    * Type of message to send.
 275    */
 276   uint16_t mtype;
 277
 278   /**
 279    * Length of the message.
 280    */
 281   uint16_t msize;
 282
 283 };
 284
 285
 286 /**
 287  * Handle for a test run.
 288  */
 289 struct GNUNET_TRANSPORT_TESTING_Handle
 290 {
 291   /**
 292    * Testing library system handle
 293    */
 294   struct GNUNET_TESTING_System *tl_system;
 295
 296   /**
 297    * head DLL of connect contexts
 298    */
 299   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_head;
 300
 301   /**
 302    * head DLL of connect contexts
 303    */
 304   struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_tail;
 305
 306   /**
 307    * Kept in a DLL.
 308    */
 309   struct TRANSPORT_TESTING_SendJob *sj_head;
 310
 311   /**
 312    * Kept in a DLL.
 313    */
 314   struct TRANSPORT_TESTING_SendJob *sj_tail;
 315
 316   /**
 317    * head DLL of peers
 318    */
 319   struct GNUNET_TRANSPORT_TESTING_PeerContext *p_head;
 320
 321   /**
 322    * tail DLL of peers
 323    */
 324   struct GNUNET_TRANSPORT_TESTING_PeerContext *p_tail;
 325 };
 326
 327
 328 /**
 329  * Initialize the transport testing
 330  *
 331  * @return transport testing handle
 332  */
 333 struct GNUNET_TRANSPORT_TESTING_Handle *
 334 GNUNET_TRANSPORT_TESTING_init (void);
 335
 336
 337 /**
 338  * Clean up the transport testing
 339  *
 340  * @param tth transport testing handle
 341  */
 342 void
 343 GNUNET_TRANSPORT_TESTING_done (struct GNUNET_TRANSPORT_TESTING_Handle *tth);
 344
 345
 346 /**
 347  * Start a peer with the given configuration
 348  *
 349  * @param tth the testing handle
 350  * @param cfgname configuration file
 351  * @param peer_id the peer_id
 352  * @param rec receive callback
 353  * @param nc connect callback
 354  * @param nd disconnect callback
 355  * @param cb_cls closure for @a nc and @a nd callback
 356  * @param start_cb start callback
 357  * @param start_cb_cls closure for @a start_cb
 358  * @return the peer context
 359  */
 360 struct GNUNET_TRANSPORT_TESTING_PeerContext *
 361 GNUNET_TRANSPORT_TESTING_start_peer (struct GNUNET_TRANSPORT_TESTING_Handle *tth,
 362                                      const char *cfgname,
 363                                      int peer_id,
 364                                      GNUNET_TRANSPORT_ReceiveCallback rec,
 365                                      GNUNET_TRANSPORT_NotifyConnect nc,
 366                                      GNUNET_TRANSPORT_NotifyDisconnect nd,
 367                                      void *cb_cls,
 368                                      GNUNET_TRANSPORT_TESTING_StartCallback start_cb,
 369                                      void *start_cb_cls);
 370
 371
 372 /**
 373  * Shutdown the given peer
 374  *
 375  * @param p the peer
 376  */
 377 void
 378 GNUNET_TRANSPORT_TESTING_stop_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *pc);
 379
 380
 381 /**
 382  * Stops and restarts the given peer, sleeping (!) for 5s in between.
 383  *
 384  * @param p the peer
 385  * @param restart_cb restart callback
 386  * @param restart_cb_cls callback closure
 387  * @return #GNUNET_OK in success otherwise #GNUNET_SYSERR
 388  */
 389 int
 390 GNUNET_TRANSPORT_TESTING_restart_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
 391                                        GNUNET_TRANSPORT_TESTING_StartCallback restart_cb,
 392                                        void *restart_cb_cls);
 393
 394
 395
 396 /**
 397  * Connect the given peers and call the callback when both peers
 398  * report the inbound connection. Remarks: start_peer's notify_connect
 399  * callback can be called before.
 400  *
 401  * @param p1 peer 1
 402  * @param p2 peer 2
 403  * @param cb the callback to call when both peers notified that they are connected
 404  * @param cls callback cls
 405  * @return a connect request handle
 406  */
 407 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *
 408 GNUNET_TRANSPORT_TESTING_connect_peers (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
 409                                         struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
 410                                         GNUNET_SCHEDULER_TaskCallback cb,
 411                                         void *cls);
 412
 413
 414 /**
 415  * Cancel the request to connect two peers.  You MUST cancel the
 416  * request if you stop the peers before the peers connected
 417  * succesfully.
 418  *
 419  * @param cc a connect request handle
 420  */
 421 void
 422 GNUNET_TRANSPORT_TESTING_connect_peers_cancel (struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
 423
 424
 425 /**
 426  * Function called on matching connect requests.
 427  *
 428  * @param cls closure
 429  * @param cc request matching the query
 430  */
 431 typedef void
 432 (*GNUNET_TRANSPORT_TESTING_ConnectContextCallback)(void *cls,
 433                                                    struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
 434
 435
 436 /**
 437  * Find any connecting context matching the given pair of peers.
 438  *
 439  * @param p1 first peer
 440  * @param p2 second peer
 441  * @param cb function to call
 442  * @param cb_cls closure for @a cb
 443  */
 444 void
 445 GNUNET_TRANSPORT_TESTING_find_connecting_context (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
 446                                                   struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
 447                                                   GNUNET_TRANSPORT_TESTING_ConnectContextCallback cb,
 448                                                   void *cb_cls);
 449
 450
 451 /* ********************** high-level process functions *************** */
 452
 453
 454 /**
 455  * Function called once the peers have been launched and
 456  * connected by #GNUNET_TRANSPORT_TESTING_connect_check().
 457  *
 458  * @param cls closure
 459  * @param num_peers size of the @a p array
 460  * @param p the peers that were launched
 461  */
 462 typedef void
 463 (*GNUNET_TRANSPORT_TESTING_ConnectContinuation)(void *cls,
 464                                                 unsigned int num_peers,
 465                                                 struct GNUNET_TRANSPORT_TESTING_PeerContext *p[]);
 466
 467
 468 /**
 469  * Internal data structure.
 470  */
 471 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList;
 472
 473 /**
 474  * Internal data structure.
 475  */
 476 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext;
 477
 478
 479 /**
 480  * Function called by the transport for each received message.
 481  *
 482  * @param cls closure
 483  * @param receiver receiver of the message
 484  * @param sender sender of the message
 485  * @param message the message
 486  */
 487 typedef void
 488 (*GNUNET_TRANSPORT_TESTING_ReceiveCallback) (void *cls,
 489                                              struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
 490                                              const struct GNUNET_PeerIdentity *sender,
 491                                              const struct GNUNET_MessageHeader *message);
 492
 493
 494 /**
 495  * Function called to notify transport users that another
 496  * peer connected to us.
 497  *
 498  * @param cls closure
 499  * @param me peer experiencing the event
 500  * @param other peer that connected to @a me
 501  */
 502 typedef void
 503 (*GNUNET_TRANSPORT_TESTING_NotifyConnect) (void *cls,
 504                                            struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
 505                                            const struct GNUNET_PeerIdentity *other);
 506
 507
 508 /**
 509  * Function called to notify transport users that another
 510  * peer disconnected from us.
 511  *
 512  * @param cls closure
 513  * @param me peer experiencing the event
 514  * @param other peer that disconnected from @a me
 515  */
 516 typedef void
 517 (*GNUNET_TRANSPORT_TESTING_NotifyDisconnect) (void *cls,
 518                                               struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
 519                                               const struct GNUNET_PeerIdentity *other);
 520
 521
 522 /**
 523  * Closure that must be passed to
 524  * #GNUNET_TRANSPORT_TESTING_connect_check.
 525  */
 526 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext
 527 {
 528
 529   /**
 530    * How should we continue after the connect?
 531    */
 532   GNUNET_SCHEDULER_TaskCallback connect_continuation;
 533
 534   /**
 535    * Closure for @e connect_continuation.
 536    */
 537   void *connect_continuation_cls;
 538
 539   /**
 540    * Which configuration file should we pass to the
 541    * #GNUNET_PROGRAM_run() of the testcase?
 542    */
 543   const char *config_file;
 544
 545   /**
 546    * Receiver argument to give for peers we start.
 547    */
 548   GNUNET_TRANSPORT_TESTING_ReceiveCallback rec;
 549
 550   /**
 551    * Notify connect argument to give for peers we start.
 552    */
 553   GNUNET_TRANSPORT_TESTING_NotifyConnect nc;
 554
 555   /**
 556    * Notify disconnect argument to give for peers we start.
 557    */
 558   GNUNET_TRANSPORT_TESTING_NotifyDisconnect nd;
 559
 560   /**
 561    * Closure for @e rec, @e nc and @e nd.
 562    */
 563   void *cls;
 564
 565   /**
 566    * Custom task to run on shutdown.
 567    */
 568   GNUNET_SCHEDULER_TaskCallback shutdown_task;
 569
 570   /**
 571    * Closure for @e shutdown_task.
 572    */
 573   void *shutdown_task_cls;
 574
 575   /**
 576    * Custom task to run after peers were started but before we try to
 577    * connect them.  If this function is set, we wait ONE second after
 578    * running this function until we continue with connecting the
 579    * peers.
 580    */
 581   GNUNET_SCHEDULER_TaskCallback pre_connect_task;
 582
 583   /**
 584    * Closure for @e shutdown_task.
 585    */
 586   void *pre_connect_task_cls;
 587
 588   /**
 589    * When should the testcase time out?
 590    */
 591   struct GNUNET_TIME_Relative timeout;
 592
 593   /**
 594    * Should we try to create connections in both directions?
 595    */
 596   int bi_directional;
 597
 598   /* ******* fields set by #GNUNET_TRANSPORT_TESTING_connect_check **** */
 599
 600   /**
 601    * Number of peers involved in the test.
 602    */
 603   unsigned int num_peers;
 604
 605   /**
 606    * Configuration files we have, array with @e num_peers entries.
 607    */
 608   char **cfg_files;
 609
 610   /**
 611    * Array with @e num_peers entries.
 612    */
 613   struct GNUNET_TRANSPORT_TESTING_PeerContext **p;
 614
 615   /**
 616    * Name of the plugin.
 617    */
 618   const char *test_plugin;
 619
 620   /**
 621    * Name of the testcase.
 622    */
 623   const char *test_name;
 624
 625   /**
 626    * Configuration object for the testcase.
 627    */
 628   const struct GNUNET_CONFIGURATION_Handle *cfg;
 629
 630   /**
 631    * Main testing handle.
 632    */
 633   struct GNUNET_TRANSPORT_TESTING_Handle *tth;
 634
 635   /**
 636    * Result from the main function, set to #GNUNET_OK on success.
 637    * Clients should set to #GNUNET_SYSERR to indicate test failure.
 638    */
 639   int global_ret;
 640
 641   /**
 642    * Generator for the `num` field in test messages.  Incremented each
 643    * time #GNUNET_TRANSPORT_TESTING_simple_send or
 644    * #GNUNET_TRANSPORT_TESTING_large_send are used to transmit a
 645    * message.
 646    */
 647   uint32_t send_num_gen;
 648
 649   /* ******* internal state, clients should not mess with this **** */
 650
 651   /**
 652    * Task run on timeout.
 653    */
 654   struct GNUNET_SCHEDULER_Task *timeout_task;
 655
 656   /**
 657    * Task run to connect peers.
 658    */
 659   struct GNUNET_SCHEDULER_Task *connect_task;
 660
 661   /**
 662    * Number of peers that have been started.
 663    */
 664   unsigned int started;
 665
 666   /**
 667    * DLL of active connect requests.
 668    */
 669   struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_head;
 670
 671   /**
 672    * DLL of active connect requests.
 673    */
 674   struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_tail;
 675
 676   /**
 677    * Array with @e num_peers entries.
 678    */
 679   struct GNUNET_TRANSPORT_TESTING_InternalPeerContext *ip;
 680
 681 };
 682
 683
 684 /**
 685  * Find peer by peer ID.
 686  *
 687  * @param ccc context to search
 688  * @param peer peer to look for
 689  * @return NULL if @a peer was not found
 690  */
 691 struct GNUNET_TRANSPORT_TESTING_PeerContext *
 692 GNUNET_TRANSPORT_TESTING_find_peer (struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc,
 693                                     const struct GNUNET_PeerIdentity *peer);
 694
 695
 696 /**
 697  * Common implementation of the #GNUNET_TRANSPORT_TESTING_CheckCallback.
 698  * Starts and connects the two peers, then invokes the
 699  * `connect_continuation` from @a cls.  Sets up a timeout to
 700  * abort the test, and a shutdown handler to clean up properly
 701  * on exit.
 702  *
 703  * @param cls closure of type `struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext`
 704  * @param tth_ initialized testing handle
 705  * @param test_plugin_ name of the plugin
 706  * @param test_name_ name of the test
 707  * @param num_peers number of entries in the @a cfg_file array
 708  * @param cfg_files array of names of configuration files for the peers
 709  * @return #GNUNET_SYSERR on error
 710  */
 711 int
 712 GNUNET_TRANSPORT_TESTING_connect_check (void *cls,
 713                                         struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
 714                                         const char *test_plugin_,
 715                                         const char *test_name_,
 716                                         unsigned int num_peers,
 717                                         char *cfg_files[]);
 718
 719
 720 /**
 721  * Main function of a testcase.  Called with the initial setup data
 722  * for the test as derived from the source name and the binary name.
 723  *
 724  * @param cls closure
 725  * @param tth_ initialized testing handle
 726  * @param test_plugin_ name of the plugin
 727  * @param test_name_ name of the test
 728  * @param num_peers number of entries in the @a cfg_file array
 729  * @param cfg_files array of names of configuration files for the peers
 730  * @return #GNUNET_SYSERR on error
 731  */
 732 typedef int
 733 (*GNUNET_TRANSPORT_TESTING_CheckCallback)(void *cls,
 734                                           struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
 735                                           const char *test_plugin_,
 736                                           const char *test_name_,
 737                                           unsigned int num_peers,
 738                                           char *cfg_files[]);
 739
 740
 741 /**
 742  * Setup testcase.  Calls @a check with the data the test needs.
 743  *
 744  * @param argv0 binary name (argv[0])
 745  * @param filename source file name (__FILE__)
 746  * @param num_peers number of peers to start
 747  * @param check main function to run
 748  * @param check_cls closure for @a check
 749  * @return #GNUNET_OK on success
 750  */
 751 int
 752 GNUNET_TRANSPORT_TESTING_main_ (const char *argv0,
 753                                 const char *filename,
 754                                 unsigned int num_peers,
 755                                 GNUNET_TRANSPORT_TESTING_CheckCallback check,
 756                                 void *check_cls);
 757
 758
 759 /**
 760  * Setup testcase.  Calls @a check with the data the test needs.
 761  *
 762  * @param num_peers number of peers to start
 763  * @param check main function to run
 764  * @param check_cls closure for @a check
 765  * @return #GNUNET_OK on success
 766  */
 767 #define GNUNET_TRANSPORT_TESTING_main(num_peers,check,check_cls) \
 768   GNUNET_TRANSPORT_TESTING_main_ (argv[0], __FILE__, num_peers, check, check_cls)
 769
 770 /* ***************** Convenience functions for sending ********* */
 771
 772 // TODO:
 773 // - need to have continuation after send is done!
 774 // - need easy way to specify continuation in case
 775 //   of the scheduler tasks
 776
 777 /**
 778  * Send a test message of type @a mtype and size @a msize from
 779  * peer @a sender to peer @a receiver.  The peers should be
 780  * connected when this function is called.
 781  *
 782  * @param sender the sending peer
 783  * @param receiver the receiving peer
 784  * @param mtype message type to use
 785  * @param msize size of the message, at least `sizeof (struct GNUNET_TRANSPORT_TESTING_TestMessage)`
 786  * @param num unique message number
 787  * @param cont continuation to call after transmission
 788  * @param cont_cls closure for @a cont
 789  * @return #GNUNET_OK if message was queued,
 790  *         #GNUNET_NO if peers are not connected
 791  *         #GNUNET_SYSERR if @a msize is illegal
 792  */
 793 int
 794 GNUNET_TRANSPORT_TESTING_send (struct GNUNET_TRANSPORT_TESTING_PeerContext *sender,
 795                                struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
 796                                uint16_t mtype,
 797                                uint16_t msize,
 798                                uint32_t num,
 799                                GNUNET_SCHEDULER_TaskCallback cont,
 800                                void *cont_cls);
 801
 802
 803 /**
 804  * Message type used by #GNUNET_TRANSPORT_TESTING_simple_send().
 805  */
 806 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE 12345
 807
 808 GNUNET_NETWORK_STRUCT_BEGIN
 809 struct GNUNET_TRANSPORT_TESTING_TestMessage
 810 {
 811   /**
 812    * Type is #GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE.
 813    */
 814   struct GNUNET_MessageHeader header;
 815
 816   /**
 817    * Monotonically increasing counter throughout the test.
 818    */
 819   uint32_t num GNUNET_PACKED;
 820 };
 821 GNUNET_NETWORK_STRUCT_END
 822
 823
 824 /**
 825  * Type of the closure argument to pass to
 826  * #GNUNET_TRANSPORT_TESTING_simple_send() and
 827  * #GNUNET_TRANSPORT_TESTING_large_send().
 828  */
 829 struct GNUNET_TRANSPORT_TESTING_SendClosure
 830 {
 831   /**
 832    * Context for the transmission.
 833    */
 834   struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc;
 835
 836   /**
 837    * Function that returns the desired message size. Overrides
 838    * the message size, can be NULL in which case the message
 839    * size is the default.
 840    */
 841   size_t (*get_size_cb)(unsigned int n);
 842
 843   /**
 844    * Number of messages to be transmitted in a loop.
 845    * Use zero for "forever" (until external shutdown).
 846    */
 847   unsigned int num_messages;
 848
 849   /**
 850    * Function to call after all transmissions, can be NULL.
 851    */
 852   GNUNET_SCHEDULER_TaskCallback cont;
 853
 854   /**
 855    * Closure for @e cont.
 856    */
 857   void *cont_cls;
 858
 859 };
 860
 861
 862 /**
 863  * Task that sends a minimalistic test message from the
 864  * first peer to the second peer.
 865  *
 866  * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
 867  *        which should contain at least two peers, the first two
 868  *        of which should be currently connected
 869  */
 870 void
 871 GNUNET_TRANSPORT_TESTING_simple_send (void *cls);
 872
 873 /**
 874  * Size of a message sent with
 875  * #GNUNET_TRANSPORT_TESTING_large_send().  Big enough
 876  * to usually force defragmentation.
 877  */
 878 #define GNUNET_TRANSPORT_TESTING_LARGE_MESSAGE_SIZE 2600
 879
 880 /**
 881  * Task that sends a large test message from the
 882  * first peer to the second peer.
 883  *
 884  * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
 885  *        which should contain at least two peers, the first two
 886  *        of which should be currently connected
 887  */
 888 void
 889 GNUNET_TRANSPORT_TESTING_large_send (void *cls);
 890
 891
 892 /* ********************** log-only convenience functions ************* */
 893
 894
 895 /**
 896  * Log a connect event.
 897  *
 898  * @param cls NULL
 899  * @param me peer that had the event
 900  * @param other peer that connected.
 901  */
 902 void
 903 GNUNET_TRANSPORT_TESTING_log_connect (void *cls,
 904                                       struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
 905                                       const struct GNUNET_PeerIdentity *other);
 906
 907
 908 /**
 909  * Log a disconnect event.
 910  *
 911  * @param cls NULL
 912  * @param me peer that had the event
 913  * @param other peer that disconnected.
 914  */
 915 void
 916 GNUNET_TRANSPORT_TESTING_log_disconnect (void *cls,
 917                                          struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
 918                                          const struct GNUNET_PeerIdentity *other);
 919
 920
 921
 922 /* ********************** low-level filename functions *************** */
 923
 924
 925 /**
 926  * Extracts the test filename from an absolute file name and removes
 927  * the extension.
 928  *
 929  * @param file absolute file name
 930  * @return resulting test name
 931  */
 932 char *
 933 GNUNET_TRANSPORT_TESTING_get_test_name (const char *file);
 934
 935
 936 /**
 937  * This function takes the filename (e.g. argv[0), removes a "lt-"-prefix and
 938  * if existing ".exe"-prefix and adds the peer-number
 939  *
 940  * @param file filename of the test, e.g. argv[0]
 941  * @param count peer number
 942  * @return configuration name to use
 943  */
 944 char *
 945 GNUNET_TRANSPORT_TESTING_get_config_name (const char *file,
 946                                           int count);
 947
 948
 949 /**
 950  * Extracts the plugin anme from an absolute file name and the test name
 951  * @param file absolute file name
 952  * @param test test name
 953  * @return the plugin name
 954  */
 955 char *
 956 GNUNET_TRANSPORT_TESTING_get_test_plugin_name (const char *executable,
 957                                                const char *testname);
 958
 959
 960 /**
 961  * Extracts the filename from an absolute file name and removes the
 962  * extenstion
 963  *
 964  * @param file absolute file name
 965  * @return the source name
 966  */
 967 char *
 968 GNUNET_TRANSPORT_TESTING_get_test_source_name (const char *file);
 969
 970 #endif
 971 /* end of transport_testing.h */