2 This file is part of GNUnet
3 (C) 2012 Christian Grothoff (and other contributing authors)
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.
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.
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.
22 * @file testbed/testbed_api.h
23 * @brief Interface for functions internally exported from testbed_api.c
24 * @author Sree Harsha Totakura
30 #include "gnunet_testbed_service.h"
34 * Enumeration of operations
39 * Peer create operation
44 * Peer start operation
54 * Peer destroy operation
59 * Get peer information operation
64 * Overlay connection operation
74 * Link controllers operation
79 * Get slave config operation
87 * The message queue for sending messages to the controller service
92 * Structure for a controller link
94 struct ControllerLink;
98 * Enumeration of states of OperationContext
100 enum OperationContextState
103 * The initial state where the associated operation has just been created
104 * and is waiting in the operation queues to be started
109 * The operation has been started. It may occupy some resources which are to
110 * be freed if cancelled.
115 * The operation has finished. The end results of this operation may occupy
116 * some resources which are to be freed by operation_done
123 * Context information for GNUNET_TESTBED_Operation
125 struct OperationContext
130 struct OperationContext *next;
135 struct OperationContext *prev;
138 * The controller to which this operation context belongs to
140 struct GNUNET_TESTBED_Controller *c;
145 struct GNUNET_TESTBED_Operation *op;
148 * The operation closure
153 * Data relevant to the operation
158 * The id of the opearation
163 * The type of operation
165 enum OperationType type;
168 * The state of the operation
170 enum OperationContextState state;
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.
183 struct GNUNET_TESTBED_Controller
187 * The host where the controller is running
189 struct GNUNET_TESTBED_Host *host;
192 * The controller callback
194 GNUNET_TESTBED_ControllerCallback cc;
197 * The closure for controller callback
202 * The configuration to use while connecting to controller
204 struct GNUNET_CONFIGURATION_Handle *cfg;
207 * The client connection handle to the controller service
209 struct GNUNET_CLIENT_Connection *client;
212 * The head of the message queue
214 struct MessageQueue *mq_head;
217 * The tail of the message queue
219 struct MessageQueue *mq_tail;
222 * The head of the ControllerLink list
224 struct ControllerLink *cl_head;
227 * The tail of the ControllerLink list
229 struct ControllerLink *cl_tail;
232 * The client transmit handle
234 struct GNUNET_CLIENT_TransmitHandle *th;
237 * The host registration handle; NULL if no current registration requests are
240 struct GNUNET_TESTBED_HostRegistrationHandle *rh;
243 * The head of the opeartion context queue
245 struct OperationContext *ocq_head;
248 * The tail of the operation context queue
250 struct OperationContext *ocq_tail;
253 * Operation queue for simultaneous operations
255 struct OperationQueue *opq_parallel_operations;
258 * Operation queue for simultaneous service connections
260 struct OperationQueue *opq_parallel_service_connections;
263 * Operation queue for simultaneous topology configuration operations
265 struct OperationQueue *opq_parallel_topology_config_operations;
268 * Operation queue for simultaneous overlay connect operations
270 struct OperationQueue *opq_parallel_overlay_connect_operations;
273 * The operation id counter. use current value and increment
275 uint32_t operation_counter;
278 * The controller event mask
283 * Did we start the receive loop yet?
288 * Did we create the host for this?
295 * Queues a message in send queue for sending to the service
297 * @param controller the handle to the controller
298 * @param msg the message to queue
301 GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller,
302 struct GNUNET_MessageHeader *msg);
306 * Compresses given configuration using zlib compress
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
312 * @return the size of the xconfig
315 GNUNET_TESTBED_compress_config_ (const char *config, size_t size,
320 * Adds an operation to the queue of operations
322 * @param op the operation to add
325 GNUNET_TESTBED_operation_add_ (struct GNUNET_TESTBED_Operation *op);
329 * Creates a helper initialization message. Only for testing.
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
335 * @return the initialization message
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
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
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
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,
366 * Function to cancel an operation created by simply forwarding an operation
369 * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
372 GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc);
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
381 * @param msg the message containing compressed configuration
382 * @return handle to the parsed configuration
384 struct GNUNET_CONFIGURATION_Handle *
385 GNUNET_TESTBED_extract_config_ (const struct GNUNET_MessageHeader *msg);
389 * Checks the integrity of the OpeationFailureEventMessage and if good returns
390 * the error message it contains.
392 * @param msg the OperationFailureEventMessage
393 * @return the error message
396 GNUNET_TESTBED_parse_error_string_ (const struct
397 GNUNET_TESTBED_OperationFailureEventMessage
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.
405 * @param controller the handle to the controller whose operation id has to be incremented
406 * @return the incremented operation id.
409 GNUNET_TESTBED_get_next_op_id (struct GNUNET_TESTBED_Controller *controller);
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
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;
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);
431 * Same as the GNUNET_TESTBED_controller_link_2, but with ids for delegated host
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
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);
458 * Same as the GNUNET_TESTBED_controller_link, but with ids for delegated host
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
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
486 /* end of testbed_api.h */