src/testing/testing_new.c

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file testing/testing_new.c
  23  * @brief convenience API for writing testcases for GNUnet
  24  *        Many testcases need to start and stop a peer/service
  25  *        and this library is supposed to make that easier
  26  *        for TESTCASES.  Normal programs should always
  27  *        use functions from gnunet_{util,arm}_lib.h.  This API is
  28  *        ONLY for writing testcases (or internal use of the testbed).
  29  * @author Christian Grothoff
  30  *
  31  */
  32 #include "platform.h"
  33 #include "gnunet_testing_lib-new.h"
  34
  35
  36 /**
  37  * Handle for a system on which GNUnet peers are executed;
  38  * a system is used for reserving unique paths and ports.
  39  */
  40 struct GNUNET_TESTING_System
  41 {
  42 };
  43
  44
  45 /**
  46  * Handle for a GNUnet peer controlled by testing.
  47  */
  48 struct GNUNET_TESTING_Peer
  49 {
  50 };
  51
  52
  53 /**
  54  * Create a system handle.  There must only be one system
  55  * handle per operating system.
  56  *
  57  * @param tmppath prefix path to use for all service homes
  58  * @param controller hostname of the controlling host,
  59  *        service configurations are modified to allow
  60  *        control connections from this host; can be NULL
  61  * @return handle to this system, NULL on error
  62  */
  63 struct GNUNET_TESTING_System *
  64 GNUNET_TESTING_system_create (const char *tmppath,
  65                               const char *controller)
  66 {
  67   GNUNET_break (0);
  68   return NULL;
  69 }
  70
  71
  72 /**
  73  * Free system resources.
  74  *
  75  * @param system system to be freed
  76  */
  77 void
  78 GNUNET_TESTING_system_destroy (struct GNUNET_TESTING_System *system)
  79 {
  80   GNUNET_break (0);
  81 }
  82
  83
  84 /**
  85  * Testing includes a number of pre-created hostkeys for
  86  * faster peer startup.  This function can be used to
  87  * access the n-th key of those pre-created hostkeys; note
  88  * that these keys are ONLY useful for testing and not
  89  * secure as the private keys are part of the public
  90  * GNUnet source code.
  91  *
  92  * This is primarily a helper function used internally
  93  * by 'GNUNET_TESTING_peer_configure'.
  94  *
  95  * @param key_number desired pre-created hostkey to obtain
  96  * @param filename where to store the hostkey (file will
  97  *        be created, or overwritten if it already exists)
  98  * @param id set to the peer's identity (hash of the public
  99  *        key; can be NULL
 100  * @return GNUNET_SYSERR on error (not enough keys)
 101  */
 102 int
 103 GNUNET_TESTING_hostkey_get (uint32_t key_number,
 104                             const char *filename,
 105                             struct GNUNET_PeerIdentity *id)
 106 {
 107   GNUNET_break (0);
 108   return GNUNET_SYSERR;
 109 }
 110
 111
 112 /**
 113  * Create a new configuration using the given configuration
 114  * as a template; ports and paths will be modified to select
 115  * available ports on the local system.  If we run
 116  * out of "*port" numbers, return SYSERR.
 117  *
 118  * This is primarily a helper function used internally
 119  * by 'GNUNET_TESTING_peer_configure'.
 120  *
 121  * @param system system to use to coordinate resource usage
 122  * @param cfg template configuration to update
 123  * @return GNUNET_OK on success, GNUNET_SYSERR on error
 124  */
 125 int
 126 GNUNET_TESTING_configuration_create (struct GNUNET_TESTING_System *system,
 127                                      struct GNUNET_CONFIGURATION_Handle *cfg);
 128
 129
 130 /**
 131  * Configure a GNUnet peer.  GNUnet must be installed on the local
 132  * system and available in the PATH.
 133  *
 134  * @param system system to use to coordinate resource usage
 135  * @param cfg configuration to use; will be UPDATED (to reflect needed
 136  *            changes in port numbers and paths)
 137  * @param key_number number of the hostkey to use for the peer
 138  * @param id identifier for the daemon, will be set, can be NULL
 139  * @param emsg set to error message (set to NULL on success), can be NULL
 140  * @return handle to the peer, NULL on error
 141  */
 142 struct GNUNET_TESTING_Peer *
 143 GNUNET_TESTING_peer_configure (struct GNUNET_TESTING_System *system,
 144                                struct GNUNET_CONFIGURATION_Handle *cfg,
 145                                uint32_t key_number,
 146                                struct GNUNET_PeerIdentity *id,
 147                                char **emsg)
 148 {
 149   GNUNET_break (0);
 150   return NULL;
 151 }
 152
 153
 154 /**
 155  * Start the peer.
 156  *
 157  * @param peer peer to start
 158  * @return GNUNET_OK on success, GNUNET_SYSERR on error (i.e. peer already running)
 159  */
 160 int
 161 GNUNET_TESTING_peer_start (struct GNUNET_TESTING_Peer *peer)
 162 {
 163   GNUNET_break (0);
 164   return GNUNET_SYSERR;
 165 }
 166
 167
 168 /**
 169  * Stop the peer.
 170  *
 171  * @param peer peer to stop
 172  * @return GNUNET_OK on success, GNUNET_SYSERR on error (i.e. peer not running)
 173  */
 174 int
 175 GNUNET_TESTING_peer_stop (struct GNUNET_TESTING_Peer *peer)
 176 {
 177   GNUNET_break (0);
 178   return GNUNET_SYSERR;
 179 }
 180
 181
 182 /**
 183  * Destroy the peer.  Releases resources locked during peer configuration.
 184  * If the peer is still running, it will be stopped AND a warning will be
 185  * printed (users of the API should stop the peer explicitly first).
 186  *
 187  * @param peer peer to destroy
 188  */
 189 void
 190 GNUNET_TESTING_peer_destroy (struct GNUNET_TESTING_Peer *peer)
 191 {
 192   GNUNET_break (0);
 193 }
 194
 195
 196
 197 /**
 198  * Start a single peer and run a test using the testing library.
 199  * Starts a peer using the given configuration and then invokes the
 200  * given callback.  This function ALSO initializes the scheduler loop
 201  * and should thus be called directly from "main".  The testcase
 202  * should self-terminate by invoking 'GNUNET_SCHEDULER_shutdown'.
 203  *
 204  * @param tmppath path for storing temporary data for the test
 205  * @param cfgfilename name of the configuration file to use;
 206  *         use NULL to only run with defaults
 207  * @param tm main function of the testcase
 208  * @param tm_cls closure for 'tm'
 209  * @return 0 on success, 1 on error
 210  */
 211 int
 212 GNUNET_TESTING_peer_run (const char *tmppath,
 213                          const char *cfgfilename,
 214                          GNUNET_TESTING_TestMain tm,
 215                          void *tm_cls)
 216 {
 217   return GNUNET_TESTING_service_run (tmppath, "arm",
 218                                      cfgfilename, tm, tm_cls);
 219 }
 220
 221
 222
 223 /**
 224  * Start a single service (no ARM, except of course if the given
 225  * service name is 'arm') and run a test using the testing library.
 226  * Starts a service using the given configuration and then invokes the
 227  * given callback.  This function ALSO initializes the scheduler loop
 228  * and should thus be called directly from "main".  The testcase
 229  * should self-terminate by invoking 'GNUNET_SCHEDULER_shutdown'.
 230  *
 231  * This function is useful if the testcase is for a single service
 232  * and if that service doesn't itself depend on other services.
 233  *
 234  * @param tmppath path for storing temporary data for the test
 235  * @param service_name name of the service to run
 236  * @param cfgfilename name of the configuration file to use;
 237  *         use NULL to only run with defaults
 238  * @param tm main function of the testcase
 239  * @param tm_cls closure for 'tm'
 240  * @return 0 on success, 1 on error
 241  */
 242 int
 243 GNUNET_TESTING_service_run (const char *tmppath,
 244                             const char *service_name,
 245                             const char *cfgfilename,
 246                             GNUNET_TESTING_TestMain tm,
 247                             void *tm_cls)
 248 {
 249   GNUNET_break (0);
 250   return 1;
 251 }
 252
 253
 254
 255 /* end of testing_new.c */