src/include/gnunet_sensor_service.h

   1 /*
   2       This file is part of GNUnet
   3       (C)
   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 include/gnunet_sensor_service.h
  23  * @brief API to the sensor service
  24  * @author Omar Tarabai
  25  */
  26 #ifndef GNUNET_SENSOR_SERVICE_H
  27 #define GNUNET_SENSOR_SERVICE_H
  28
  29 #include "platform.h"
  30 #include "gnunet_util_lib.h"
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40
  41 /**
  42  * Handle to the sensor service.
  43  */
  44 struct GNUNET_SENSOR_Handle;
  45
  46 /**
  47  * Structure containing sensor definition
  48  */
  49 struct SensorInfo
  50 {
  51
  52   /**
  53    * The configuration handle
  54    * carrying sensor information
  55    */
  56   struct GNUNET_CONFIGURATION_Handle *cfg;
  57
  58   /*
  59    * Sensor name
  60    */
  61   char *name;
  62
  63   /*
  64    * Path to definition file
  65    */
  66   char *def_file;
  67
  68   /*
  69    * First part of version number
  70    */
  71   uint16_t version_major;
  72
  73   /*
  74    * Second part of version number
  75    */
  76   uint16_t version_minor;
  77
  78   /*
  79    * Sensor description
  80    */
  81   char *description;
  82
  83   /*
  84    * Sensor currently enabled
  85    */
  86   int enabled;
  87
  88   /*
  89    * Category under which the sensor falls (e.g. tcp, datastore)
  90    */
  91   char *category;
  92
  93   /*
  94    * When does the sensor become active
  95    */
  96   struct GNUNET_TIME_Absolute *start_time;
  97
  98   /*
  99    * When does the sensor expire
 100    */
 101   struct GNUNET_TIME_Absolute *end_time;
 102
 103   /*
 104    * Time interval to collect sensor information (e.g. every 1 min)
 105    */
 106   struct GNUNET_TIME_Relative interval;
 107
 108   /*
 109    * Lifetime of an information sample after which it is deleted from storage
 110    * If not supplied, will default to the interval value
 111    */
 112   struct GNUNET_TIME_Relative lifetime;
 113
 114   /*
 115    * A set of required peer capabilities for the sensor to collect meaningful information (e.g. ipv6)
 116    */
 117   char *capabilities;
 118
 119   /*
 120    * Either "gnunet-statistics" or external "process"
 121    */
 122   char *source;
 123
 124   /*
 125    * Name of the GNUnet service that is the source for the gnunet-statistics entry
 126    */
 127   char *gnunet_stat_service;
 128
 129   /*
 130    * Name of the gnunet-statistics entry
 131    */
 132   char *gnunet_stat_name;
 133
 134   /**
 135    * Handle to statistics get request (OR GNUNET_SCHEDULER_NO_TASK)
 136    */
 137   struct GNUNET_STATISTICS_GetHandle *gnunet_stat_get_handle;
 138
 139   /*
 140    * Name of the external process to be executed
 141    */
 142   char *ext_process;
 143
 144   /*
 145    * Arguments to be passed to the external process
 146    */
 147   char *ext_args;
 148
 149   /*
 150    * Handle to the external process
 151    */
 152   struct GNUNET_OS_CommandHandle *ext_cmd;
 153
 154   /*
 155    * Did we already receive a value
 156    * from the currently running external
 157    * proccess ? #GNUNET_YES / #GNUNET_NO
 158    */
 159   int ext_cmd_value_received;
 160
 161   /*
 162    * The output datatype to be expected
 163    */
 164   char *expected_datatype;
 165
 166   /*
 167    * Peer-identity of peer running collection point
 168    */
 169   struct GNUNET_PeerIdentity *collection_point;
 170
 171   /*
 172    * Time interval to send sensor information to collection point (e.g. every 30 mins)
 173    */
 174   struct GNUNET_TIME_Relative collection_interval;
 175
 176   /*
 177    * Flag specifying if value is to be communicated to the p2p network
 178    */
 179   int p2p_report;
 180
 181   /*
 182    * Time interval to communicate value to the p2p network
 183    */
 184   struct GNUNET_TIME_Relative p2p_interval;
 185
 186   /*
 187    * Execution task (OR GNUNET_SCHEDULER_NO_TASK)
 188    */
 189   GNUNET_SCHEDULER_TaskIdentifier execution_task;
 190
 191   /*
 192    * Is the sensor being executed
 193    */
 194   int running;
 195
 196 };
 197
 198 /**
 199  * Structure containing brief info about sensor
 200  */
 201 struct SensorInfoShort
 202 {
 203
 204   /*
 205    * Sensor name
 206    */
 207   char *name;
 208
 209   /*
 210    * First part of version number
 211    */
 212   uint16_t version_major;
 213
 214   /*
 215    * Second part of version number
 216    */
 217   uint16_t version_minor;
 218
 219   /*
 220    * Sensor description
 221    */
 222   char *description;
 223
 224 };
 225
 226 /**
 227  * Type of an iterator over sensor definitions.
 228  *
 229  * @param cls closure
 230  * @param hello hello message for the peer (can be NULL)
 231  * @param error message
 232  */
 233 typedef void (*GNUNET_SENSOR_SensorIteratorCB) (void *cls,
 234                                              const struct SensorInfoShort *sensor,
 235                                              const char *err_msg);
 236
 237 /**
 238  * Continuation called with a status result.
 239  *
 240  * @param cls closure
 241  * @param emsg error message, NULL on success
 242  */
 243 typedef void (*GNUNET_SENSOR_Continuation)(void *cls,
 244                const char *emsg);
 245
 246 /**
 247  * Connect to the sensor service.
 248  *
 249  * @return NULL on error
 250  */
 251 struct GNUNET_SENSOR_Handle *
 252 GNUNET_SENSOR_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 253
 254 /**
 255  * Disconnect from the sensor service
 256  *
 257  * @param h handle to disconnect
 258  */
 259 void
 260 GNUNET_SENSOR_disconnect(struct GNUNET_SENSOR_Handle *h);
 261
 262 /**
 263  * Client asking to iterate all available sensors
 264  *
 265  * @param h Handle to SENSOR service
 266  * @param timeout how long to wait until timing out
 267  * @param sensorname information on one sensor only, can be NULL to get all
 268  * @param sensorname_len length of the sensorname parameter
 269  * @param callback the method to call for each sensor
 270  * @param callback_cls closure for callback
 271  * @return iterator context
 272  */
 273 struct GNUNET_SENSOR_SensorIteratorContext *
 274 GNUNET_SENSOR_iterate_sensors (struct GNUNET_SENSOR_Handle *h,
 275     struct GNUNET_TIME_Relative timeout,
 276     const char* sensorname, size_t sensorname_len,
 277     GNUNET_SENSOR_SensorIteratorCB callback, void *callback_cls);
 278
 279 #if 0                           /* keep Emacsens' auto-indent happy */
 280 {
 281 #endif
 282 #ifdef __cplusplus
 283 }
 284 #endif
 285
 286 #endif