src/include/gnunet_sensor_util_lib.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 sensor/sensor_util_lib.c
  23  * @brief senor utilities
  24  * @author Omar Tarabai
  25  */
  26
  27 #ifndef GNUNET_SENSOR_UTIL_LIB_H
  28 #define GNUNET_SENSOR_UTIL_LIB_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 /**
  39  * Structure containing sensor definition
  40  */
  41 struct GNUNET_SENSOR_SensorInfo
  42 {
  43
  44   /**
  45    * The configuration handle
  46    * carrying sensor information
  47    */
  48   struct GNUNET_CONFIGURATION_Handle *cfg;
  49
  50   /**
  51    * Sensor name
  52    */
  53   char *name;
  54
  55   /**
  56    * Path to definition file
  57    */
  58   char *def_file;
  59
  60   /**
  61    * First part of version number
  62    */
  63   uint16_t version_major;
  64
  65   /**
  66    * Second part of version number
  67    */
  68   uint16_t version_minor;
  69
  70   /**
  71    * Sensor description
  72    */
  73   char *description;
  74
  75   /**
  76    * Sensor currently enabled
  77    */
  78   int enabled;
  79
  80   /**
  81    * Category under which the sensor falls (e.g. tcp, datastore)
  82    */
  83   char *category;
  84
  85   /**
  86    * When does the sensor become active
  87    */
  88   struct GNUNET_TIME_Absolute *start_time;
  89
  90   /**
  91    * When does the sensor expire
  92    */
  93   struct GNUNET_TIME_Absolute *end_time;
  94
  95   /**
  96    * Time interval to collect sensor information (e.g. every 1 min)
  97    */
  98   struct GNUNET_TIME_Relative interval;
  99
 100   /**
 101    * Lifetime of an information sample after which it is deleted from storage
 102    * If not supplied, will default to the interval value
 103    */
 104   struct GNUNET_TIME_Relative lifetime;
 105
 106   /**
 107    * A set of required peer capabilities for the sensor to collect meaningful information (e.g. ipv6)
 108    */
 109   char *capabilities;
 110
 111   /**
 112    * Either "gnunet-statistics" or external "process"
 113    */
 114   char *source;
 115
 116   /**
 117    * Name of the GNUnet service that is the source for the gnunet-statistics entry
 118    */
 119   char *gnunet_stat_service;
 120
 121   /**
 122    * Name of the gnunet-statistics entry
 123    */
 124   char *gnunet_stat_name;
 125
 126   /**
 127    * Handle to statistics get request (OR GNUNET_SCHEDULER_NO_TASK)
 128    */
 129   struct GNUNET_STATISTICS_GetHandle *gnunet_stat_get_handle;
 130
 131   /**
 132    * Name of the external process to be executed
 133    */
 134   char *ext_process;
 135
 136   /**
 137    * Arguments to be passed to the external process
 138    */
 139   char *ext_args;
 140
 141   /**
 142    * Handle to the external process
 143    */
 144   struct GNUNET_OS_CommandHandle *ext_cmd;
 145
 146   /**
 147    * Did we already receive a value
 148    * from the currently running external
 149    * proccess ? #GNUNET_YES / #GNUNET_NO
 150    */
 151   int ext_cmd_value_received;
 152
 153   /**
 154    * The output datatype to be expected
 155    */
 156   char *expected_datatype;
 157
 158   /**
 159    * Peer-identity of peer running collection point
 160    */
 161   struct GNUNET_PeerIdentity *collection_point;
 162
 163   /**
 164    * Do we report received sensor values to collection point?
 165    * #GNUNET_YES / #GNUNET_NO
 166    */
 167   int report_values;
 168
 169   /**
 170    * Time interval to send sensor values to collection point (e.g. every 30 mins)
 171    */
 172   struct GNUNET_TIME_Relative value_reporting_interval;
 173
 174   /**
 175    * Do we report anomalies to collection point?
 176    * #GNUNET_YES / #GNUNET_NO
 177    */
 178   int report_anomalies;
 179
 180   /**
 181    * Execution task (OR GNUNET_SCHEDULER_NO_TASK)
 182    */
 183   GNUNET_SCHEDULER_TaskIdentifier execution_task;
 184
 185   /**
 186    * Is the sensor being executed
 187    */
 188   int running;
 189
 190 };
 191
 192 /**
 193  * Anomaly report received and stored by sensor dashboard.
 194  * Sensor name and peer id are not included because they are part of the
 195  * peerstore key.
 196  */
 197 struct GNUNET_SENSOR_DashboardAnomalyEntry
 198 {
 199
 200   /**
 201    * New anomaly status
 202    */
 203   uint16_t anomalous;
 204
 205   /**
 206    * Percentage of neighbors reported the same anomaly
 207    */
 208   float anomalous_neighbors;
 209
 210 };
 211
 212 GNUNET_NETWORK_STRUCT_BEGIN
 213
 214 /**
 215  * Used to communicate brief information about a sensor.
 216  */
 217 struct GNUNET_SENSOR_SensorBriefMessage
 218 {
 219
 220   /**
 221    * GNUNET general message header.
 222    */
 223   struct GNUNET_MessageHeader header;
 224
 225   /**
 226    * Size of sensor name string, allocated at position 0 after this struct.
 227    */
 228   uint16_t name_size;
 229
 230   /**
 231    * First part of sensor version number
 232    */
 233   uint16_t version_major;
 234
 235   /**
 236    * Second part of sensor version number
 237    */
 238   uint16_t version_minor;
 239
 240 };
 241
 242 /**
 243  * Used to communicate full information about a sensor.
 244  */
 245 struct GNUNET_SENSOR_SensorFullMessage
 246 {
 247
 248   /**
 249    * GNUNET general message header.
 250    */
 251   struct GNUNET_MessageHeader header;
 252
 253   /**
 254    * Size of sensor name.
 255    * Name allocated at position 0 after this struct.
 256    */
 257   uint16_t sensorname_size;
 258
 259   /**
 260    * Size of the sensor definition file carrying full sensor information.
 261    * The file content allocated at position 1 after this struct.
 262    */
 263   uint16_t sensorfile_size;
 264
 265   /**
 266    * Name of the file (usually script) associated with this sensor.
 267    * At the moment we only support having one file per sensor.
 268    * The file name is allocated at position 2 after this struct.
 269    */
 270   uint16_t scriptname_size;
 271
 272   /**
 273    * Size of the file (usually script) associated with this sensor.
 274    * The file content is allocated at position 3 after this struct.
 275    */
 276   uint16_t scriptfile_size;
 277
 278 };
 279
 280 /**
 281  * Used to communicate sensor values to
 282  * collection points (SENSORDASHBAORD service)
 283  */
 284     struct GNUNET_SENSOR_ValueMessage
 285 {
 286
 287   /**
 288    * GNUNET general message header
 289    */
 290   struct GNUNET_MessageHeader header;
 291
 292   /**
 293    * Hash of sensor name
 294    */
 295   struct GNUNET_HashCode sensorname_hash;
 296
 297   /**
 298    * First part of sensor version number
 299    */
 300   uint16_t sensorversion_major;
 301
 302   /**
 303    * Second part of sensor version number
 304    */
 305   uint16_t sensorversion_minor;
 306
 307   /**
 308    * Timestamp of recorded reading
 309    */
 310   struct GNUNET_TIME_Absolute timestamp;
 311
 312   /**
 313    * Size of sensor value, allocated at poistion 0 after this struct
 314    */
 315   uint16_t value_size;
 316
 317 };
 318
 319 /**
 320  * Message carrying an anomaly status change report
 321  */
 322 struct GNUNET_SENSOR_AnomalyReportMessage
 323 {
 324
 325   /**
 326    * Message header
 327    */
 328   struct GNUNET_MessageHeader header;
 329
 330   /**
 331    * Hash of sensor name
 332    */
 333   struct GNUNET_HashCode sensorname_hash;
 334
 335   /**
 336    * First part of sensor version number
 337    */
 338   uint16_t sensorversion_major;
 339
 340   /**
 341    * Second part of sensor version name
 342    */
 343   uint16_t sensorversion_minor;
 344
 345   /**
 346    * New anomaly status
 347    */
 348   uint16_t anomalous;
 349
 350   /**
 351    * Percentage of neighbors reported the same anomaly
 352    */
 353   float anomalous_neighbors;
 354
 355 };
 356
 357 GNUNET_NETWORK_STRUCT_END
 358
 359 /**
 360  * Given two version numbers as major and minor, compare them.
 361  *
 362  * @param v1_major First part of first version number
 363  * @param v1_minor Second part of first version number
 364  * @param v2_major First part of second version number
 365  * @param v2_minor Second part of second version number
 366  */
 367     int
 368 GNUNET_SENSOR_version_compare (uint16_t v1_major, uint16_t v1_minor,
 369                                uint16_t v2_major, uint16_t v2_minor);
 370
 371
 372 /**
 373  * Reads sensor definitions from given sensor directory.
 374  *
 375  * @param sensordir Path to sensor directory.
 376  * @return a multihashmap of loaded sensors
 377  */
 378 struct GNUNET_CONTAINER_MultiHashMap *
 379 GNUNET_SENSOR_load_all_sensors (char *sensor_dir);
 380
 381
 382 /**
 383  * Get path to the default directory containing the sensor definition files with
 384  * a trailing directory separator.
 385  *
 386  * @return Default sensor files directory full path
 387  */
 388 char *
 389 GNUNET_SENSOR_get_default_sensor_dir ();
 390
 391
 392 /**
 393  * Destroys a group of sensors in a hashmap and the hashmap itself
 394  *
 395  * @param sensors hashmap containing the sensors
 396  */
 397 void
 398 GNUNET_SENSOR_destroy_sensors (struct GNUNET_CONTAINER_MultiHashMap *sensors);
 399
 400 #if 0                           /* keep Emacsens' auto-indent happy */
 401 {
 402 #endif
 403 #ifdef __cplusplus
 404 }
 405 #endif
 406
 407 /* ifndef GNUNET_SENSOR_UTIL_LIB_H */
 408 #endif
 409 /* end of gnunet_sensor_util_lib.h */