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