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    * Get slave config operation
  80    */
  81   OP_GET_SLAVE_CONFIG
  82
  83 };
  84
  85
  86 /**
  87  * The message queue for sending messages to the controller service
  88  */
  89 struct MessageQueue;
  90
  91 /**
  92  * Structure for a controller link
  93  */
  94 struct ControllerLink;
  95
  96
  97 /**
  98  * Enumeration of states of OperationContext
  99  */
 100 enum OperationContextState
 101 {
 102     /**
 103      * The initial state where the associated operation has just been created
 104      * and is waiting in the operation queues to be started
 105      */
 106   OPC_STATE_INIT = 0,
 107
 108     /**
 109      * The operation has been started. It may occupy some resources which are to
 110      * be freed if cancelled.
 111      */
 112   OPC_STATE_STARTED,
 113
 114     /**
 115      * The operation has finished. The end results of this operation may occupy
 116      * some resources which are to be freed by operation_done
 117      */
 118   OPC_STATE_FINISHED
 119 };
 120
 121
 122 /**
 123  * Context information for GNUNET_TESTBED_Operation
 124  */
 125 struct OperationContext
 126 {
 127   /**
 128    * next ptr for DLL
 129    */
 130   struct OperationContext *next;
 131
 132   /**
 133    * prev ptr for DLL
 134    */
 135   struct OperationContext *prev;
 136
 137   /**
 138    * The controller to which this operation context belongs to
 139    */
 140   struct GNUNET_TESTBED_Controller *c;
 141
 142   /**
 143    * The operation
 144    */
 145   struct GNUNET_TESTBED_Operation *op;
 146
 147   /**
 148    * The operation closure
 149    */
 150   void *op_cls;
 151
 152   /**
 153    * Data relevant to the operation
 154    */
 155   void *data;
 156
 157   /**
 158    * The id of the opearation
 159    */
 160   uint64_t id;
 161
 162   /**
 163    * The type of operation
 164    */
 165   enum OperationType type;
 166
 167   /**
 168    * The state of the operation
 169    */
 170   enum OperationContextState state;
 171 };
 172
 173
 174 /**
 175  * Handle to interact with a GNUnet testbed controller.  Each
 176  * controller has at least one master handle which is created when the
 177  * controller is created; this master handle interacts with the
 178  * controller process, destroying it destroys the controller (by
 179  * closing stdin of the controller process).  Additionally,
 180  * controllers can interact with each other (in a P2P fashion); those
 181  * links are established via TCP/IP on the controller's service port.
 182  */
 183 struct GNUNET_TESTBED_Controller
 184 {
 185
 186   /**
 187    * The host where the controller is running
 188    */
 189   struct GNUNET_TESTBED_Host *host;
 190
 191   /**
 192    * The controller callback
 193    */
 194   GNUNET_TESTBED_ControllerCallback cc;
 195
 196   /**
 197    * The closure for controller callback
 198    */
 199   void *cc_cls;
 200
 201   /**
 202    * The configuration to use while connecting to controller
 203    */
 204   struct GNUNET_CONFIGURATION_Handle *cfg;
 205
 206   /**
 207    * The client connection handle to the controller service
 208    */
 209   struct GNUNET_CLIENT_Connection *client;
 210
 211   /**
 212    * The head of the message queue
 213    */
 214   struct MessageQueue *mq_head;
 215
 216   /**
 217    * The tail of the message queue
 218    */
 219   struct MessageQueue *mq_tail;
 220
 221   /**
 222    * The head of the ControllerLink list
 223    */
 224   struct ControllerLink *cl_head;
 225
 226   /**
 227    * The tail of the ControllerLink list
 228    */
 229   struct ControllerLink *cl_tail;
 230
 231   /**
 232    * The client transmit handle
 233    */
 234   struct GNUNET_CLIENT_TransmitHandle *th;
 235
 236   /**
 237    * The host registration handle; NULL if no current registration requests are
 238    * present
 239    */
 240   struct GNUNET_TESTBED_HostRegistrationHandle *rh;
 241
 242   /**
 243    * The head of the opeartion context queue
 244    */
 245   struct OperationContext *ocq_head;
 246
 247   /**
 248    * The tail of the operation context queue
 249    */
 250   struct OperationContext *ocq_tail;
 251
 252   /**
 253    * Operation queue for simultaneous operations
 254    */
 255   struct OperationQueue *opq_parallel_operations;
 256
 257   /**
 258    * Operation queue for simultaneous service connections
 259    */
 260   struct OperationQueue *opq_parallel_service_connections;
 261
 262   /**
 263    * Operation queue for simultaneous topology configuration operations
 264    */
 265   struct OperationQueue *opq_parallel_topology_config_operations;
 266
 267   /**
 268    * Operation queue for simultaneous overlay connect operations
 269    */
 270   struct OperationQueue *opq_parallel_overlay_connect_operations;
 271
 272   /**
 273    * The operation id counter. use current value and increment
 274    */
 275   uint32_t operation_counter;
 276
 277   /**
 278    * The controller event mask
 279    */
 280   uint64_t event_mask;
 281
 282   /**
 283    * Did we start the receive loop yet?
 284    */
 285   int in_receive;
 286
 287   /**
 288    * Did we create the host for this?
 289    */
 290   int aux_host;
 291 };
 292
 293
 294 /**
 295  * Queues a message in send queue for sending to the service
 296  *
 297  * @param controller the handle to the controller
 298  * @param msg the message to queue
 299  */
 300 void
 301 GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller,
 302                                struct GNUNET_MessageHeader *msg);
 303
 304
 305 /**
 306  * Compresses given configuration using zlib compress
 307  *
 308  * @param config the serialized configuration
 309  * @param size the size of config
 310  * @param xconfig will be set to the compressed configuration (memory is fresly
 311  *          allocated)
 312  * @return the size of the xconfig
 313  */
 314 size_t
 315 GNUNET_TESTBED_compress_config_ (const char *config, size_t size,
 316                                  char **xconfig);
 317
 318
 319 /**
 320  * Adds an operation to the queue of operations
 321  *
 322  * @param op the operation to add
 323  */
 324 void
 325 GNUNET_TESTBED_operation_add_ (struct GNUNET_TESTBED_Operation *op);
 326
 327
 328 /**
 329  * Creates a helper initialization message. Only for testing.
 330  *
 331  * @param cname the ip address of the controlling host
 332  * @param hostname the hostname of the destination this message is intended for
 333  * @param cfg the configuration that has to used to start the testbed service
 334  *          thru helper
 335  * @return the initialization message
 336  */
 337 struct GNUNET_TESTBED_HelperInit *
 338 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname,
 339                                         const char *hostname,
 340                                         const struct GNUNET_CONFIGURATION_Handle
 341                                         *cfg);
 342
 343
 344 /**
 345  * Sends the given message as an operation. The given callback is called when a
 346  * reply for the operation is available.  Call
 347  * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned
 348  * operation context if the cc hasn't been called
 349  *
 350  * @param controller the controller to which the message has to be sent
 351  * @param operation_id the operation id of the message
 352  * @param msg the message to send
 353  * @param cc the callback to call when reply is available
 354  * @param cc_cls the closure for the above callback
 355  * @return the operation context which can be used to cancel the forwarded
 356  *           operation
 357  */
 358 struct OperationContext *
 359 GNUNET_TESTBED_forward_operation_msg_ (struct GNUNET_TESTBED_Controller
 360                                        *controller, uint64_t operation_id,
 361                                        const struct GNUNET_MessageHeader *msg,
 362                                        GNUNET_CLIENT_MessageHandler cc,
 363                                        void *cc_cls);
 364
 365 /**
 366  * Function to cancel an operation created by simply forwarding an operation
 367  * message.
 368  *
 369  * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
 370  */
 371 void
 372 GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc);
 373
 374
 375 /**
 376  * Generates configuration by uncompressing configuration in given message. The
 377  * given message should be of the following types:
 378  * GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG,
 379  * GNUNET_MESSAGE_TYPE_TESTBED_SLAVECONFIG
 380  *
 381  * @param msg the message containing compressed configuration
 382  * @return handle to the parsed configuration
 383  */
 384 struct GNUNET_CONFIGURATION_Handle *
 385 GNUNET_TESTBED_extract_config_ (const struct GNUNET_MessageHeader *msg);
 386
 387
 388 /**
 389  * Checks the integrity of the OpeationFailureEventMessage and if good returns
 390  * the error message it contains.
 391  *
 392  * @param msg the OperationFailureEventMessage
 393  * @return the error message
 394  */
 395 const char *
 396 GNUNET_TESTBED_parse_error_string_ (const struct
 397                                     GNUNET_TESTBED_OperationFailureEventMessage
 398                                     *msg);
 399
 400
 401 /**
 402  * Function to return the operation id for a controller. The operation id is
 403  * created from the controllers host id and its internal operation counter.
 404  *
 405  * @param controller the handle to the controller whose operation id has to be incremented
 406  * @return the incremented operation id.
 407  */
 408 uint64_t
 409 GNUNET_TESTBED_get_next_op_id (struct GNUNET_TESTBED_Controller *controller);
 410
 411
 412 /**
 413  * Like GNUNET_TESTBED_get_slave_config(), however without the host registration
 414  * check. Another difference is that this function takes the id of the slave
 415  * host.
 416  *
 417  * @param op_cls the closure for the operation
 418  * @param master the handle to master controller
 419  * @param slave_host_id id of the host where the slave controller is running to
 420  *          the slave_host should remain valid until this operation is cancelled
 421  *          or marked as finished
 422  * @return the operation handle;
 423  */
 424 struct GNUNET_TESTBED_Operation *
 425 GNUNET_TESTBED_get_slave_config_ (void *op_cls,
 426                                   struct GNUNET_TESTBED_Controller *master,
 427                                   uint32_t slave_host_id);
 428
 429
 430 /**
 431  * Same as the GNUNET_TESTBED_controller_link_2, but with ids for delegated host
 432  * and slave host
 433  *
 434  * @param op_cls the operation closure for the event which is generated to
 435  *          signal success or failure of this operation
 436  * @param master handle to the master controller who creates the association
 437  * @param delegated_host_id id of the host to which requests should be delegated
 438  * @param slave_host_id id of the host which is used to run the slave controller
 439  * @param sxcfg serialized and compressed configuration
 440  * @param sxcfg_size the size sxcfg
 441  * @param scfg_size the size of uncompressed serialized configuration
 442  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 443  *          be started by the slave controller; GNUNET_NO if the slave
 444  *          controller has to connect to the already started delegated
 445  *          controller via TCP/IP
 446  * @return the operation handle
 447  */
 448 struct GNUNET_TESTBED_Operation *
 449 GNUNET_TESTBED_controller_link_2_ (void *op_cls,
 450                                    struct GNUNET_TESTBED_Controller *master,
 451                                    uint32_t delegated_host_id,
 452                                    uint32_t slave_host_id,
 453                                    const char *sxcfg, size_t sxcfg_size,
 454                                    size_t scfg_size, int is_subordinate);
 455
 456
 457 /**
 458  * Same as the GNUNET_TESTBED_controller_link, but with ids for delegated host
 459  * and slave host
 460  *
 461  * @param op_cls the operation closure for the event which is generated to
 462  *          signal success or failure of this operation
 463  * @param master handle to the master controller who creates the association
 464  * @param delegated_host_id id of the host to which requests should be
 465  *          delegated; cannot be NULL
 466  * @param slave_host_id id of the host which should connect to controller
 467  *          running on delegated host ; use NULL to make the master controller
 468  *          connect to the delegated host
 469  * @param slave_cfg configuration to use for the slave controller
 470  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 471  *          be started by the slave controller; GNUNET_NO if the slave
 472  *          controller has to connect to the already started delegated
 473  *          controller via TCP/IP
 474  * @return the operation handle
 475  */
 476 struct GNUNET_TESTBED_Operation *
 477 GNUNET_TESTBED_controller_link_ (void *op_cls,
 478                                 struct GNUNET_TESTBED_Controller *master,
 479                                 uint32_t delegated_host_id,
 480                                 uint32_t slave_host_id,
 481                                 const struct GNUNET_CONFIGURATION_Handle
 482                                 *slave_cfg,
 483                                  int is_subordinate);
 484
 485 #endif
 486 /* end of testbed_api.h */