src/testbed/testbed_api.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 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.h
  23  * @brief Interface for functions internally exported from testbed_api.c
  24  * @author Sree Harsha Totakura
  25  */
  26
  27 #ifndef TESTBED_API_H
  28 #define TESTBED_API_H
  29
  30 #include "gnunet_testbed_service.h"
  31 #include "testbed.h"
  32
  33 /**
  34  * Enumeration of operations
  35  */
  36 enum OperationType
  37 {
  38     /**
  39      * Peer create operation
  40      */
  41   OP_PEER_CREATE,
  42
  43     /**
  44      * Peer start operation
  45      */
  46   OP_PEER_START,
  47
  48     /**
  49      * Peer stop operation
  50      */
  51   OP_PEER_STOP,
  52
  53     /**
  54      * Peer destroy operation
  55      */
  56   OP_PEER_DESTROY,
  57
  58     /**
  59      * Get peer information operation
  60      */
  61   OP_PEER_INFO,
  62
  63     /**
  64      * Overlay connection operation
  65      */
  66   OP_OVERLAY_CONNECT,
  67
  68     /**
  69      * Forwarded operation
  70      */
  71   OP_FORWARDED,
  72
  73     /**
  74      * Link controllers operation
  75      */
  76   OP_LINK_CONTROLLERS,
  77
  78 };
  79
  80
  81 /**
  82  * Testbed operation structure
  83  */
  84 struct GNUNET_TESTBED_Operation
  85 {
  86   /**
  87    * next pointer for DLL
  88    */
  89   struct GNUNET_TESTBED_Operation *next;
  90
  91   /**
  92    * prev pointer for DLL
  93    */
  94   struct GNUNET_TESTBED_Operation *prev;
  95
  96   /**
  97    * The controller on which this operation operates
  98    */
  99   struct GNUNET_TESTBED_Controller *controller;
 100
 101   /**
 102    * The ID for the operation;
 103    */
 104   uint64_t operation_id;
 105
 106   /**
 107    * The type of operation
 108    */
 109   enum OperationType type;
 110
 111   /**
 112    * Data specific to OperationType
 113    */
 114   void *data;
 115 };
 116
 117
 118 /**
 119  * The message queue for sending messages to the controller service
 120  */
 121 struct MessageQueue;
 122
 123 /**
 124  * Structure for a controller link
 125  */
 126 struct ControllerLink;
 127
 128
 129 /**
 130  * Enumeration of states of OperationContext
 131  */
 132 enum OperationContextState
 133 {
 134     /**
 135      * The initial state where the associated operation has just been created
 136      * and is waiting in the operation queues to be started
 137      */
 138   OPC_STATE_INIT = 0,
 139
 140     /**
 141      * The operation has been started. It may occupy some resources which are to
 142      * be freed if cancelled.
 143      */
 144   OPC_STATE_STARTED,
 145
 146     /**
 147      * The operation has finished. The end results of this operation may occupy
 148      * some resources which are to be freed by operation_done
 149      */
 150   OPC_STATE_FINISHED
 151 };
 152
 153
 154 /**
 155  * Context information for GNUNET_TESTBED_Operation
 156  */
 157 struct OperationContext
 158 {
 159   /**
 160    * next ptr for DLL
 161    */
 162   struct OperationContext *next;
 163
 164   /**
 165    * prev ptr for DLL
 166    */
 167   struct OperationContext *prev;
 168
 169   /**
 170    * The controller to which this operation context belongs to
 171    */
 172   struct GNUNET_TESTBED_Controller *c;
 173
 174   /**
 175    * The operation
 176    */
 177   struct GNUNET_TESTBED_Operation *op;
 178
 179   /**
 180    * Data relevant to the operation
 181    */
 182   void *data;
 183
 184   /**
 185    * The id of the opearation
 186    */
 187   uint64_t id;
 188
 189   /**
 190    * The type of operation
 191    */
 192   enum OperationType type;
 193
 194   /**
 195    * The state of the operation
 196    */
 197   enum OperationContextState state;
 198 };
 199
 200
 201 /**
 202  * Handle to interact with a GNUnet testbed controller.  Each
 203  * controller has at least one master handle which is created when the
 204  * controller is created; this master handle interacts with the
 205  * controller process, destroying it destroys the controller (by
 206  * closing stdin of the controller process).  Additionally,
 207  * controllers can interact with each other (in a P2P fashion); those
 208  * links are established via TCP/IP on the controller's service port.
 209  */
 210 struct GNUNET_TESTBED_Controller
 211 {
 212
 213   /**
 214    * The host where the controller is running
 215    */
 216   struct GNUNET_TESTBED_Host *host;
 217
 218   /**
 219    * The controller callback
 220    */
 221   GNUNET_TESTBED_ControllerCallback cc;
 222
 223   /**
 224    * The closure for controller callback
 225    */
 226   void *cc_cls;
 227
 228   /**
 229    * The configuration to use while connecting to controller
 230    */
 231   struct GNUNET_CONFIGURATION_Handle *cfg;
 232
 233   /**
 234    * The client connection handle to the controller service
 235    */
 236   struct GNUNET_CLIENT_Connection *client;
 237
 238   /**
 239    * The head of the message queue
 240    */
 241   struct MessageQueue *mq_head;
 242
 243   /**
 244    * The tail of the message queue
 245    */
 246   struct MessageQueue *mq_tail;
 247
 248   /**
 249    * The head of the ControllerLink list
 250    */
 251   struct ControllerLink *cl_head;
 252
 253   /**
 254    * The tail of the ControllerLink list
 255    */
 256   struct ControllerLink *cl_tail;
 257
 258   /**
 259    * The client transmit handle
 260    */
 261   struct GNUNET_CLIENT_TransmitHandle *th;
 262
 263   /**
 264    * The host registration handle; NULL if no current registration requests are
 265    * present
 266    */
 267   struct GNUNET_TESTBED_HostRegistrationHandle *rh;
 268
 269   /**
 270    * The head of the opeartion context queue
 271    */
 272   struct OperationContext *ocq_head;
 273
 274   /**
 275    * The tail of the operation context queue
 276    */
 277   struct OperationContext *ocq_tail;
 278
 279   /**
 280    * Operation queue for simultaneous operations
 281    */
 282   struct OperationQueue *opq_parallel_operations;
 283
 284   /**
 285    * Operation queue for simultaneous service connections
 286    */
 287   struct OperationQueue *opq_parallel_service_connections;
 288
 289   /**
 290    * Operation queue for simultaneous topology configuration operations
 291    */
 292   struct OperationQueue *opq_parallel_topology_config_operations;
 293
 294   /**
 295    * The operation id counter. use current value and increment
 296    */
 297   uint64_t operation_counter;
 298
 299   /**
 300    * The controller event mask
 301    */
 302   uint64_t event_mask;
 303
 304   /**
 305    * Did we start the receive loop yet?
 306    */
 307   int in_receive;
 308
 309   /**
 310    * Did we create the host for this?
 311    */
 312   int aux_host;
 313 };
 314
 315
 316 /**
 317  * Queues a message in send queue for sending to the service
 318  *
 319  * @param controller the handle to the controller
 320  * @param msg the message to queue
 321  */
 322 void
 323 GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller,
 324                                struct GNUNET_MessageHeader *msg);
 325
 326
 327 /**
 328  * Compresses given configuration using zlib compress
 329  *
 330  * @param config the serialized configuration
 331  * @param size the size of config
 332  * @param xconfig will be set to the compressed configuration (memory is fresly
 333  *          allocated)
 334  * @return the size of the xconfig
 335  */
 336 size_t
 337 GNUNET_TESTBED_compress_config_ (const char *config, size_t size,
 338                                  char **xconfig);
 339
 340
 341 /**
 342  * Adds an operation to the queue of operations
 343  *
 344  * @param op the operation to add
 345  */
 346 void
 347 GNUNET_TESTBED_operation_add_ (struct GNUNET_TESTBED_Operation *op);
 348
 349
 350 /**
 351  * Creates a helper initialization message. Only for testing.
 352  *
 353  * @param cname the ip address of the controlling host
 354  * @param cfg the configuration that has to used to start the testbed service
 355  *          thru helper
 356  * @return the initialization message
 357  */
 358 struct GNUNET_TESTBED_HelperInit *
 359 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname,
 360                                         const struct GNUNET_CONFIGURATION_Handle
 361                                         *cfg);
 362
 363
 364 /**
 365  * Sends the given message as an operation. The given callback is called when a
 366  * reply for the operation is available.  Call
 367  * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned
 368  * operation context if the cc hasn't been called
 369  *
 370  * @param controller the controller to which the message has to be sent
 371  * @param operation_id the operation id of the message
 372  * @param msg the message to send
 373  * @param cc the callback to call when reply is available
 374  * @param cc_cls the closure for the above callback
 375  * @return the operation context which can be used to cancel the forwarded
 376  *           operation
 377  */
 378 struct OperationContext *
 379 GNUNET_TESTBED_forward_operation_msg_ (struct GNUNET_TESTBED_Controller
 380                                        *controller, uint64_t operation_id,
 381                                        const struct GNUNET_MessageHeader *msg,
 382                                        GNUNET_CLIENT_MessageHandler cc,
 383                                        void *cc_cls);
 384
 385 /**
 386  * Function to cancel an operation created by simply forwarding an operation
 387  * message.
 388  *
 389  * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
 390  */
 391 void
 392 GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc);
 393
 394
 395 /**
 396  * Generates configuration by parsing Peer configuration information reply message
 397  *
 398  * @param msg the peer configuration information message
 399  * @return handle to the parsed configuration
 400  */
 401 struct GNUNET_CONFIGURATION_Handle *
 402 GNUNET_TESTBED_get_config_from_peerinfo_msg_ (const struct
 403                                               GNUNET_TESTBED_PeerConfigurationInformationMessage
 404                                               *msg);
 405
 406
 407 /**
 408  * Checks the integrity of the OpeationFailureEventMessage and if good returns
 409  * the error message it contains.
 410  *
 411  * @param msg the OperationFailureEventMessage
 412  * @return the error message
 413  */
 414 const char *
 415 GNUNET_TESTBED_parse_error_string_ (const struct
 416                                     GNUNET_TESTBED_OperationFailureEventMessage
 417                                     *msg);
 418
 419 #endif
 420 /* end of testbed_api.h */