src/include/gnunet_sensor_service.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C)
   4
   5       GNUnet is free software: you can redistribute it and/or modify it
   6       under the terms of the GNU General Public License as published
   7       by the Free Software Foundation, either version 3 of the License,
   8       or (at your 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       Affero General Public License for more details.
  14  */
  15
  16 /**
  17  * @author Omar Tarabai
  18  *
  19  * @file
  20  * API to the sensor service
  21  *
  22  * @defgroup sensor  Sensor service
  23  *
  24  * @{
  25  */
  26
  27 #ifndef GNUNET_SENSOR_SERVICE_H
  28 #define GNUNET_SENSOR_SERVICE_H
  29
  30 #include "gnunet_common.h"
  31 #include "gnunet_util_lib.h"
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41
  42 /**
  43  * Handle to the sensor service.
  44  */
  45 struct GNUNET_SENSOR_Handle;
  46
  47 /**
  48  * Context for an iteration request.
  49  */
  50 struct GNUNET_SENSOR_IterateContext;
  51
  52 /**
  53  * Context of a force anomaly request
  54  */
  55 struct GNUNET_SENSOR_ForceAnomalyContext;
  56
  57 /**
  58  * Structure containing brief info about sensor
  59  */
  60 struct SensorInfoShort
  61 {
  62
  63   /*
  64    * Sensor name
  65    */
  66   char *name;
  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
  85 /**
  86  * Sensor iterate request callback.
  87  *
  88  * @param cls closure
  89  * @param sensor Brief sensor information
  90  * @param error message
  91  */
  92 typedef void (*GNUNET_SENSOR_SensorIterateCB) (void *cls,
  93                                                 const struct SensorInfoShort *
  94                                                 sensor, const char *err_msg);
  95
  96
  97 /**
  98  * Continuation called with a status result.
  99  *
 100  * @param cls closure
 101  * @param emsg error message, NULL on success
 102  */
 103 typedef void (*GNUNET_SENSOR_Continuation) (void *cls, const char *emsg);
 104
 105
 106 /**
 107  * Disconnect from the sensor service
 108  *
 109  * @param h handle to disconnect
 110  */
 111 void
 112 GNUNET_SENSOR_disconnect (struct GNUNET_SENSOR_Handle *h);
 113
 114
 115 /**
 116  * Connect to the sensor service.
 117  *
 118  * @return NULL on error
 119  */
 120 struct GNUNET_SENSOR_Handle *
 121 GNUNET_SENSOR_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 122
 123
 124 /**
 125  * Cancel an iteration request.
 126  * This should be called before the iterate callback is called with a NULL value.
 127  *
 128  * @param ic context of the iterator to cancel
 129  */
 130 void
 131 GNUNET_SENSOR_iterate_cancel (struct GNUNET_SENSOR_IterateContext
 132                                      *ic);
 133
 134
 135 /**
 136  * Get one or all sensors loaded by the sensor service.
 137  * The callback will be called with each sensor received and once with a NULL
 138  * value to signal end of iteration.
 139  *
 140  * @param h Handle to SENSOR service
 141  * @param timeout how long to wait until timing out
 142  * @param sensorname Name of the required sensor, NULL to get all
 143  * @param callback the function to call for each sensor
 144  * @param callback_cls closure for callback
 145  * @return iterator context
 146  */
 147 struct GNUNET_SENSOR_IterateContext *
 148 GNUNET_SENSOR_iterate (struct GNUNET_SENSOR_Handle *h,
 149                                struct GNUNET_TIME_Relative timeout,
 150                                const char *sensor_name,
 151                                GNUNET_SENSOR_SensorIterateCB callback,
 152                                void *callback_cls);
 153
 154
 155 /**
 156  * Cancel a force anomaly request.
 157  *
 158  * @param fa Force anomaly context returned by GNUNET_SENSOR_force_anomaly()
 159  */
 160 void
 161 GNUNET_SENSOR_force_anomaly_cancel (struct GNUNET_SENSOR_ForceAnomalyContext
 162                                     *fa);
 163
 164
 165 /**
 166  * Force an anomaly status change on a given sensor. If the sensor reporting
 167  * module is running, this will trigger the usual reporting logic, therefore,
 168  * please only use this in a test environment.
 169  *
 170  * Also, if the sensor analysis module is running, it might conflict and cause
 171  * undefined behaviour if it detects a real anomaly.
 172  *
 173  * @param h Service handle
 174  * @param sensor_name Sensor name to set the anomaly status
 175  * @param anomalous The desired status: #GNUNET_YES / #GNUNET_NO
 176  * @param cont Continuation function to be called after the request is sent
 177  * @param cont_cls Closure for cont
 178  */
 179 struct GNUNET_SENSOR_ForceAnomalyContext *
 180 GNUNET_SENSOR_force_anomaly (struct GNUNET_SENSOR_Handle *h, char *sensor_name,
 181                              int anomalous, GNUNET_SENSOR_Continuation cont,
 182                              void *cont_cls);
 183
 184
 185 #if 0                           /* keep Emacsens' auto-indent happy */
 186 {
 187 #endif
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192 #endif
 193
 194 /** @} */  /* end of group */