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