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