src/testbed/testbed_api_peers.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008--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 testbed/testbed_api_peers.h
  23  * @brief internal API to access the 'peers' subsystem
  24  * @author Christian Grothoff
  25  */
  26 #ifndef NEW_TESTING_API_PEERS_H
  27 #define NEW_TESTING_API_PEERS_H
  28
  29 #include "gnunet_testbed_service.h"
  30 #include "gnunet_helper_lib.h"
  31
  32
  33 /**
  34  * Enumeration of possible states a peer could be in
  35  */
  36 enum PeerState
  37   {
  38     /**
  39      * State to signify that this peer is invalid
  40      */
  41     PS_INVALID,
  42
  43     /**
  44      * The peer has been created
  45      */
  46     PS_CREATED,
  47
  48     /**
  49      * The peer is running
  50      */
  51     PS_STARTED,
  52
  53     /**
  54      * The peer is stopped
  55      */
  56     PS_STOPPED,
  57   };
  58
  59
  60 /**
  61  * A peer controlled by the testing framework.  A peer runs
  62  * at a particular host.
  63  */
  64 struct GNUNET_TESTBED_Peer
  65 {
  66   /**
  67    * Our controller context (not necessarily the controller
  68    * that is responsible for starting/running the peer!).
  69    */
  70   struct GNUNET_TESTBED_Controller *controller;
  71
  72   /**
  73    * Which host does this peer run on?
  74    */
  75   struct GNUNET_TESTBED_Host *host;
  76
  77   /**
  78    * Globally unique ID of the peer.
  79    */
  80   uint32_t unique_id;
  81
  82   /**
  83    * Peer's state
  84    */
  85   enum PeerState state;
  86 };
  87
  88
  89 /**
  90  * Data for the OperationType OP_PEER_CREATE
  91  */
  92 struct PeerCreateData
  93 {
  94   /**
  95    * The host where the peer has to be created
  96    */
  97   struct GNUNET_TESTBED_Host *host;
  98
  99   /**
 100    * The template configuration of the peer
 101    */
 102   const struct GNUNET_CONFIGURATION_Handle *cfg;
 103
 104   /**
 105    * The call back to call when we receive peer create success message
 106    */
 107   GNUNET_TESTBED_PeerCreateCallback cb;
 108
 109   /**
 110    * The closure for the above callback
 111    */
 112   void *cls;
 113
 114   /**
 115    * The peer structure to return when we get success message
 116    */
 117   struct GNUNET_TESTBED_Peer *peer;
 118
 119 };
 120
 121
 122 /**
 123  * Data for the OperationType OP_PEER_DESTROY;
 124  */
 125 struct PeerDestroyData
 126 {
 127   /**
 128    * The peer structure
 129    */
 130   struct GNUNET_TESTBED_Peer *peer;
 131
 132   //PEERDESTROYDATA
 133 };
 134
 135
 136 /**
 137  * Data for the OperationType OP_PEER_INFO
 138  */
 139 struct PeerInfoData
 140 {
 141   /**
 142    * The peer whose information has been requested
 143    */
 144   struct GNUNET_TESTBED_Peer *peer;
 145
 146   /**
 147    * The type of peer information requested
 148    */
 149   enum GNUNET_TESTBED_PeerInformationType pit;
 150 };
 151
 152
 153 /**
 154  * Data for the OperationType OP_PEER_INFO
 155  */
 156 struct PeerInfoData2
 157 {
 158   /**
 159    * The type of peer information requested
 160    */
 161   enum GNUNET_TESTBED_PeerInformationType pit;
 162
 163   /**
 164    * The data from reply
 165    */
 166   union
 167   {
 168     /**
 169      * Configuration handle
 170      */
 171     struct GNUNET_CONFIGURATION_Handle *cfg;
 172
 173     /**
 174      * Peer Identity
 175      */
 176     struct GNUNET_PeerIdentity *peer_identity;
 177   } details;
 178 };
 179
 180
 181 /**
 182  * Data structure for OperationType OP_OVERLAY_CONNECT
 183  */
 184 struct OverlayConnectData
 185 {
 186   /**
 187    * Peer A to connect to peer B
 188    */
 189   struct GNUNET_TESTBED_Peer *p1;
 190
 191   /**
 192    * Peer B
 193    */
 194   struct GNUNET_TESTBED_Peer *p2;
 195
 196 };
 197
 198
 199
 200 /**
 201  * Create the given peer at the specified host using the given
 202  * controller.  If the given controller is not running on the target
 203  * host, it should find or create a controller at the target host and
 204  * delegate creating the peer.  Explicit delegation paths can be setup
 205  * using 'GNUNET_TESTBED_controller_link'.  If no explicit delegation
 206  * path exists, a direct link with a subordinate controller is setup
 207  * for the first delegated peer to a particular host; the subordinate
 208  * controller is then destroyed once the last peer that was delegated
 209  * to the remote host is stopped.  This function is used in particular
 210  * if some other controller has already assigned a unique ID to the
 211  * peer.
 212  *
 213  * Creating the peer only creates the handle to manipulate and further
 214  * configure the peer; use "GNUNET_TESTBED_peer_start" and
 215  * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
 216  * processes.
 217  *
 218  * Note that the given configuration will be adjusted by the
 219  * controller to avoid port/path conflicts with other peers.
 220  * The "final" configuration can be obtained using
 221  * 'GNUNET_TESTBED_peer_get_information'.
 222  *
 223  * @param unique_id unique ID for this peer
 224  * @param controller controller process to use
 225  * @param host host to run the peer on
 226  * @param cfg configuration to use for the peer
 227  * @param cb the callback to call when the peer has been created
 228  * @param cls the closure to the above callback
 229  * @return the operation handle
 230  */
 231 struct GNUNET_TESTBED_Operation *
 232 GNUNET_TESTBED_peer_create_with_id_ (uint32_t unique_id,
 233                                      struct GNUNET_TESTBED_Controller *controller,
 234                                      struct GNUNET_TESTBED_Host *host,
 235                                      const struct GNUNET_CONFIGURATION_Handle *cfg,
 236                                      GNUNET_TESTBED_PeerCreateCallback cb,
 237                                      void *cls);
 238
 239
 240
 241 #endif
 242 /* end of testbed_api_peers.h */