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