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