src/testbed/testbed_api_hosts.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008--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_hosts.h
  23  * @brief internal API to access the 'hosts' subsystem
  24  * @author Christian Grothoff
  25  */
  26
  27 #ifndef NEW_TESTING_API_HOSTS_H
  28 #define NEW_TESTING_API_HOSTS_H
  29
  30 #include "gnunet_testbed_service.h"
  31 #include "testbed_helper.h"
  32
  33
  34 /**
  35  * Wrapper around
  36  */
  37 struct GNUNET_TESTBED_HelperHandle
  38 {
  39   /**
  40    * The process handle
  41    */
  42   struct GNUNET_HELPER_Handle *helper;
  43
  44   /**
  45    * The send handle for the helper
  46    */
  47   struct GNUNET_HELPER_SendHandle *helper_shandle;
  48
  49   /**
  50    * The port number for ssh; used for helpers starting ssh
  51    */
  52   char *port;
  53
  54   /**
  55    * The ssh destination string; used for helpers starting ssh
  56    */
  57   char *dst;
  58
  59   /**
  60    * The helper exception callback
  61    */
  62   GNUNET_HELPER_ExceptionCallback exp_cb;
  63
  64   /**
  65    * The closure for exp_cb
  66    */
  67   void *exp_cb_cls;
  68
  69   /**
  70    * Is the helper stopped?
  71    */
  72   int is_stopped;
  73 };
  74
  75
  76 /**
  77  * Lookup a host by ID.
  78  *
  79  * @param id global host ID assigned to the host; 0 is
  80  *        reserved to always mean 'localhost'
  81  * @return handle to the host, NULL on error
  82  */
  83 struct GNUNET_TESTBED_Host *
  84 GNUNET_TESTBED_host_lookup_by_id_ (uint32_t id);
  85
  86
  87 /**
  88  * Create a host by ID; given this host handle, we could not
  89  * run peers at the host, but we can talk about the host
  90  * internally.
  91  *
  92  * @param id global host ID assigned to the host; 0 is
  93  *        reserved to always mean 'localhost'
  94  * @return handle to the host, NULL on error
  95  */
  96 struct GNUNET_TESTBED_Host *
  97 GNUNET_TESTBED_host_create_by_id_ (uint32_t id);
  98
  99
 100 /**
 101  * Obtain a host's unique global ID.
 102  *
 103  * @param host handle to the host, NULL means 'localhost'
 104  * @return id global host ID assigned to the host (0 is
 105  *         'localhost', but then obviously not globally unique)
 106  */
 107 uint32_t
 108 GNUNET_TESTBED_host_get_id_ (const struct GNUNET_TESTBED_Host *host);
 109
 110
 111 /**
 112  * Obtain the host's hostname.
 113  *
 114  * @param host handle to the host, NULL means 'localhost'
 115  * @return hostname of the host
 116  */
 117 const char *
 118 GNUNET_TESTBED_host_get_hostname_ (const struct GNUNET_TESTBED_Host *host);
 119
 120
 121 /**
 122  * Obtain the host's username
 123  *
 124  * @param host handle to the host, NULL means 'localhost'
 125  * @return username to login to the host
 126  */
 127 const char *
 128 GNUNET_TESTBED_host_get_username_ (const struct GNUNET_TESTBED_Host *host);
 129
 130
 131 /**
 132  * Obtain the host's ssh port
 133  *
 134  * @param host handle to the host, NULL means 'localhost'
 135  * @return username to login to the host
 136  */
 137 uint16_t
 138 GNUNET_TESTBED_host_get_ssh_port_ (const struct GNUNET_TESTBED_Host *host);
 139
 140
 141 /**
 142  * Opaque wrapper around GNUNET_HELPER_Handle
 143  */
 144 struct GNUNET_TESTBED_HelperHandle;
 145
 146
 147 /**
 148  * Run a given helper process at the given host.  Communication
 149  * with the helper will be via GNUnet messages on stdin/stdout.
 150  * Runs the process via 'ssh' at the specified host, or locally.
 151  * Essentially an SSH-wrapper around the 'gnunet_helper_lib.h' API.
 152  *
 153  * @param controller_ip the ip address of the controller. Will be set as TRUSTED
 154  *          host when starting testbed controller at host
 155  * @param host host to use, use "NULL" for localhost
 156  * @param binary_argv binary name and command-line arguments to give to the
 157  *          binary
 158  * @param cfg template configuration to use for the remote controller; the
 159  *          remote controller will be started with a slightly modified
 160  *          configuration (port numbers, unix domain sockets and service home
 161  *          values are changed as per TESTING library on the remote host)
 162  * @param cb the callback to run when helper process dies; cannot be NULL
 163  * @param cb_cls the closure for the above callback
 164  * @return handle to terminate the command, NULL on error
 165  */
 166 struct GNUNET_TESTBED_HelperHandle *
 167 GNUNET_TESTBED_host_run_ (const char *controller_ip,
 168                           const struct GNUNET_TESTBED_Host *host,
 169                           const struct GNUNET_CONFIGURATION_Handle *cfg,
 170                           GNUNET_HELPER_ExceptionCallback cb,
 171                           void *cb_cls);
 172
 173
 174 /**
 175  * Stops a helper in the HelperHandle using GNUNET_HELPER_stop
 176  *
 177  * @param handle the handle returned from GNUNET_TESTBED_host_start_
 178  */
 179 void
 180 GNUNET_TESTBED_host_stop_ (struct GNUNET_TESTBED_HelperHandle *handle);
 181
 182
 183 /**
 184  * Marks a host as registered with a controller
 185  *
 186  * @param host the host to mark
 187  * @param controller the controller at which this host is registered
 188  */
 189 void
 190 GNUNET_TESTBED_mark_host_registered_at_ (struct GNUNET_TESTBED_Host *host,
 191                                          const struct GNUNET_TESTBED_Controller
 192                                          *controller);
 193
 194
 195 /**
 196  * Checks whether a host has been registered with the given controller
 197  *
 198  * @param host the host to check
 199  * @param controller the controller at which host's registration is checked
 200  * @return GNUNET_YES if registered; GNUNET_NO if not
 201  */
 202 int
 203 GNUNET_TESTBED_is_host_registered_ (const struct GNUNET_TESTBED_Host *host,
 204                                     const struct GNUNET_TESTBED_Controller
 205                                          *controller);
 206
 207
 208 /**
 209  * Creates a helper initialization message. Only for testing.
 210  *
 211  * @param cname the ip address of the controlling host
 212  * @param cfg the configuration that has to used to start the testbed service
 213  *          thru helper
 214  * @return the initialization message
 215  */
 216 struct GNUNET_TESTBED_HelperInit *
 217 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname,
 218                                         const struct GNUNET_CONFIGURATION_Handle *cfg);
 219
 220
 221
 222 #endif
 223 /* end of testbed_api_hosts.h */