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_OS_Process *process;
  43
  44   /**
  45    * Pipe connecting to stdin of the process.
  46    */
  47   struct GNUNET_DISK_PipeHandle *cpipe_in;
  48
  49   /**
  50    * Pipe from the stdout of the process.
  51    */
  52   struct GNUNET_DISK_PipeHandle *cpipe_out;
  53
  54   /**
  55    * The port number for ssh; used for helpers starting ssh
  56    */
  57   char *port;
  58
  59   /**
  60    * The ssh destination string; used for helpers starting ssh
  61    */
  62   char *dst;
  63 };
  64
  65
  66 /**
  67  * Lookup a host by ID.
  68  *
  69  * @param id global host ID assigned to the host; 0 is
  70  *        reserved to always mean 'localhost'
  71  * @return handle to the host, NULL on error
  72  */
  73 struct GNUNET_TESTBED_Host *
  74 GNUNET_TESTBED_host_lookup_by_id_ (uint32_t id);
  75
  76
  77 /**
  78  * Create a host by ID; given this host handle, we could not
  79  * run peers at the host, but we can talk about the host
  80  * internally.
  81  *
  82  * @param id global host ID assigned to the host; 0 is
  83  *        reserved to always mean 'localhost'
  84  * @return handle to the host, NULL on error
  85  */
  86 struct GNUNET_TESTBED_Host *
  87 GNUNET_TESTBED_host_create_by_id_ (uint32_t id);
  88
  89
  90 /**
  91  * Obtain a host's unique global ID.
  92  *
  93  * @param host handle to the host, NULL means 'localhost'
  94  * @return id global host ID assigned to the host (0 is
  95  *         'localhost', but then obviously not globally unique)
  96  */
  97 uint32_t
  98 GNUNET_TESTBED_host_get_id_ (const struct GNUNET_TESTBED_Host *host);
  99
 100
 101 /**
 102  * Obtain the host's hostname.
 103  *
 104  * @param host handle to the host, NULL means 'localhost'
 105  * @return hostname of the host
 106  */
 107 const char *
 108 GNUNET_TESTBED_host_get_hostname_ (const struct GNUNET_TESTBED_Host *host);
 109
 110
 111 /**
 112  * Obtain the host's username
 113  *
 114  * @param host handle to the host, NULL means 'localhost'
 115  * @return username to login to the host
 116  */
 117 const char *
 118 GNUNET_TESTBED_host_get_username_ (const struct GNUNET_TESTBED_Host *host);
 119
 120
 121 /**
 122  * Obtain the host's ssh port
 123  *
 124  * @param host handle to the host, NULL means 'localhost'
 125  * @return username to login to the host
 126  */
 127 uint16_t
 128 GNUNET_TESTBED_host_get_ssh_port_ (const struct GNUNET_TESTBED_Host *host);
 129
 130
 131 /**
 132  * Opaque wrapper around GNUNET_HELPER_Handle
 133  */
 134 struct GNUNET_TESTBED_HelperHandle;
 135
 136
 137 /**
 138  * Run a given helper process at the given host.  Communication
 139  * with the helper will be via GNUnet messages on stdin/stdout.
 140  * Runs the process via 'ssh' at the specified host, or locally.
 141  * Essentially an SSH-wrapper around the 'gnunet_helper_lib.h' API.
 142  *
 143  * @param host host to use, use "NULL" for localhost
 144  * @param binary_argv binary name and command-line arguments to give to the binary
 145  * @return handle to terminate the command, NULL on error
 146  */
 147 struct GNUNET_TESTBED_HelperHandle *
 148 GNUNET_TESTBED_host_run_ (const struct GNUNET_TESTBED_Host *host,
 149                           char *const binary_argv[]);
 150
 151
 152 /**
 153  * Stops a helper in the HelperHandle using GNUNET_HELPER_stop
 154  *
 155  * @param handle the handle returned from GNUNET_TESTBED_host_start_
 156  */
 157 void
 158 GNUNET_TESTBED_host_stop_ (struct GNUNET_TESTBED_HelperHandle *handle);
 159
 160
 161 /**
 162  * Marks a host as registered with a controller
 163  *
 164  * @param host the host to mark
 165  * @param controller the controller at which this host is registered
 166  */
 167 void
 168 GNUNET_TESTBED_mark_host_registered_at_ (struct GNUNET_TESTBED_Host *host,
 169                                          const struct GNUNET_TESTBED_Controller
 170                                          *controller);
 171
 172
 173 /**
 174  * Checks whether a host has been registered with the given controller
 175  *
 176  * @param host the host to check
 177  * @param controller the controller at which host's registration is checked
 178  * @return GNUNET_YES if registered; GNUNET_NO if not
 179  */
 180 int
 181 GNUNET_TESTBED_is_host_registered_ (const struct GNUNET_TESTBED_Host *host,
 182                                     const struct GNUNET_TESTBED_Controller
 183                                          *controller);
 184
 185
 186 /**
 187  * Creates a helper initialization message. Only for testing.
 188  *
 189  * @param cname the ip address of the controlling host
 190  * @param cfg the configuration that has to used to start the testbed service
 191  *          thru helper
 192  * @return the initialization message
 193  */
 194 struct GNUNET_TESTBED_HelperInit *
 195 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname,
 196                                          const struct GNUNET_CONFIGURATION_Handle *cfg);
 197
 198
 199
 200 #endif
 201 /* end of testbed_api_hosts.h */