include/gammu-statemachine.h

   1 /**
   2  * \file gammu-statemachine.h
   3  * \author Michal Čihař
   4  *
   5  * State machine data.
   6  */
   7 #ifndef __gammu_statemachine_h
   8 #define __gammu_statemachine_h
   9
  10 /**
  11  * \defgroup StateMachine State machine
  12  * Generic state machine layer.
  13  */
  14
  15 #include <gammu-types.h>
  16 #include <gammu-error.h>
  17 #include <gammu-inifile.h>
  18
  19 /**
  20  * Callback function for logging.
  21  *
  22  * \param text Text to be printed, \n will be also sent (as a separate
  23  * message).
  24  */
  25 typedef void (*GSM_Log_Function) (const char *text, void *data);
  26
  27 /**
  28  * Private structure holding information about phone connection. Should
  29  * be allocated by \ref GSM_AllocStateMachine and freed by
  30  * \ref GSM_FreeStateMachine.
  31  *
  32  * \ingroup StateMachine
  33  */
  34 typedef struct _GSM_StateMachine GSM_StateMachine;
  35
  36 #include <gammu-info.h>
  37
  38 /**
  39  * Configuration of state machine.
  40  *
  41  * \ingroup StateMachine
  42  */
  43 typedef struct {
  44         /**
  45          * Model from config file
  46          */
  47         char Model[50];
  48         /**
  49          * Debug level
  50          */
  51         char DebugLevel[50];
  52         /**
  53          * Device name from config file
  54          */
  55         char *Device;
  56         /**
  57          * Connection type as string
  58          */
  59         char *Connection;
  60         /**
  61          * Synchronize time on startup?
  62          */
  63         gboolean SyncTime;
  64         /**
  65          * Lock device ? (Unix)
  66          */
  67         gboolean LockDevice;
  68         /**
  69          * Name of debug file
  70          */
  71         char *DebugFile;
  72         /**
  73          * Display something during start ?
  74          */
  75         gboolean StartInfo;
  76         /**
  77          * Should we use global debug file?
  78          */
  79         gboolean UseGlobalDebugFile;
  80         /**
  81          * Text for reminder calendar entry category in local language
  82          */
  83         char TextReminder[32];
  84         /**
  85          * Text for meeting calendar entry category in local language
  86          */
  87         char TextMeeting[32];
  88         /**
  89          * Text for call calendar entry category in local language
  90          */
  91         char TextCall[32];
  92         /**
  93          * Text for birthday calendar entry category in local language
  94          */
  95         char TextBirthday[32];
  96         /**
  97          * Text for memo calendar entry category in local language
  98          */
  99         char TextMemo[32];
 100         /**
 101          * Phone features override.
 102          */
 103         GSM_Feature PhoneFeatures[GSM_MAX_PHONE_FEATURES + 1];
 104 } GSM_Config;
 105
 106 /**
 107  * Connection types definitions.
 108  */
 109 typedef enum {
 110         GCT_MBUS2 = 1,
 111         GCT_FBUS2,
 112         GCT_FBUS2DLR3,
 113         GCT_DKU2AT,
 114         GCT_DKU2PHONET,
 115         GCT_DKU5FBUS2,
 116         GCT_ARK3116FBUS2,
 117         GCT_FBUS2PL2303,
 118         GCT_FBUS2BLUE,
 119         GCT_FBUS2IRDA,
 120         GCT_PHONETBLUE,
 121         GCT_AT,
 122         GCT_BLUEGNAPBUS,
 123         GCT_IRDAOBEX,
 124         GCT_IRDAGNAPBUS,
 125         GCT_IRDAAT,
 126         GCT_IRDAPHONET,
 127         GCT_BLUEFBUS2,
 128         GCT_BLUEAT,
 129         GCT_BLUEPHONET,
 130         GCT_BLUEOBEX,
 131         GCT_FBUS2USB,
 132         GCT_BLUES60,
 133         GCT_NONE
 134 } GSM_ConnectionType;
 135
 136 /**
 137  * Initiates connection with custom logging callback.
 138  *
 139  * \ingroup StateMachine
 140  *
 141  * \param s State machine data
 142  * \param ReplyNum Number of replies to await (usually 3).
 143  * \param log_function Logging function, see GSM_SetDebugFunction.
 144  * \param user_data User data for logging function, see GSM_SetDebugFunction.
 145  * \return Error code
 146  * \see GSM_SetDebugFunction
 147  */
 148 GSM_Error GSM_InitConnection_Log(GSM_StateMachine * s, int ReplyNum,
 149                                  GSM_Log_Function log_function,
 150                                  void *user_data);
 151
 152 /**
 153  * Initiates connection.
 154  *
 155  * \ingroup StateMachine
 156  *
 157  * \param s State machine data
 158  * \param ReplyNum Number of replies to await (usually 3).
 159  * \return Error code
 160  */
 161 GSM_Error GSM_InitConnection(GSM_StateMachine * s, int ReplyNum);
 162
 163 /**
 164  * Terminates connection.
 165  *
 166  * \ingroup StateMachine
 167  *
 168  * \param s State machine data
 169  * \return Error code
 170  */
 171 GSM_Error GSM_TerminateConnection(GSM_StateMachine * s);
 172
 173 /**
 174  * Aborts current operation.
 175  *
 176  * This is thread safe call to abort any existing operations with the
 177  * phone.
 178  *
 179  * \ingroup StateMachine
 180  *
 181  * \param s State machine data
 182  * \return Error code
 183  */
 184 GSM_Error GSM_AbortOperation(GSM_StateMachine * s);
 185
 186 /**
 187  * Attempts to read data from phone. This can be used for getting
 188  * status of incoming events, which would not be found out without
 189  * polling device.
 190  *
 191  * \ingroup StateMachine
 192  *
 193  * \param s State machine data
 194  * \param waitforreply Whether to wait for some event
 195  * \return Number of read bytes
 196  */
 197 int GSM_ReadDevice(GSM_StateMachine * s, gboolean waitforreply);
 198
 199 /**
 200  * Detects whether state machine is connected.
 201  *
 202  * \ingroup StateMachine
 203  *
 204  * \param s State machine data
 205  * \return Whether phone is connected.
 206  */
 207 gboolean GSM_IsConnected(GSM_StateMachine * s);
 208
 209 /**
 210  * Finds and reads gammu configuration file. The search order depends on
 211  * platform. On POSIX systems it looks for ~/.gammurc and then for
 212  * /etc/gammurc, on Windows for gammurc in Application data folder, then
 213  * in home and last fallback is in current driectory.
 214  *
 215  * \param result Ini file representation
 216  * \param force_config Forcing of custom path instead of autodetected
 217  * one (if NULL, autodetection is performed).
 218  *
 219  * \return Error code
 220  *
 221  * \ingroup StateMachine
 222  */
 223 GSM_Error GSM_FindGammuRC(INI_Section ** result, const char *force_config);
 224
 225 /**
 226  * Processes gammu configuration.
 227  *
 228  * \param cfg_info Ini file representation.
 229  * \param cfg Where to store configuration.
 230  * \param num Number of section to read.
 231  * \return Whether we got valid configuration. Especially check for
 232  * ERR_USING_DEFAULTS.
 233  *
 234  * \ingroup StateMachine
 235  *
 236  * \see GSM_FallbackConfig
 237  */
 238 GSM_Error GSM_ReadConfig(INI_Section * cfg_info, GSM_Config * cfg, int num);
 239
 240 /**
 241  * Gets gammu configuration from state machine. This actually returns
 242  * pointer to internal configuration storage, so you can use it also for
 243  * updating existing settings.
 244  *
 245  * \param s State machine data
 246  * \param num Number of section to read, -1 for currently used.
 247  * \return Pointer to configuration.
 248  *
 249  * \ingroup StateMachine
 250  */
 251 GSM_Config *GSM_GetConfig(GSM_StateMachine * s, int num);
 252
 253 /**
 254  * Gets number of active gammu configurations.
 255  *
 256  * \param s State machine data
 257  * \return Number of sections.
 258  *
 259  * \ingroup StateMachine
 260  */
 261 int GSM_GetConfigNum(const GSM_StateMachine * s);
 262
 263 /**
 264  * Gets number of active gammu configurations.
 265  *
 266  * \param s State machine data
 267  * \param sections Number of sections.
 268  *
 269  * \ingroup StateMachine
 270  */
 271 void GSM_SetConfigNum(GSM_StateMachine * s, int sections);
 272
 273 /**
 274  * Allocates new clean state machine structure. You should free it then
 275  * by \ref GSM_FreeStateMachine.
 276  *
 277  * \return Pointer to state machine structure.
 278  *
 279  * \ingroup StateMachine
 280  */
 281 GSM_StateMachine *GSM_AllocStateMachine(void);
 282
 283 /**
 284  * Frees state machine structure allocated by
 285  * \ref GSM_AllocStateMachine.
 286  *
 287  * \param s Pointer to state machine structure.
 288  *
 289  * \ingroup StateMachine
 290  */
 291 void GSM_FreeStateMachine(GSM_StateMachine * s);
 292
 293 /**
 294  * Gets number of active gammu configurations.
 295  *
 296  * \param s State machine data
 297  * \return Connection type.
 298  *
 299  * \ingroup StateMachine
 300  */
 301 GSM_ConnectionType GSM_GetUsedConnection(GSM_StateMachine * s);
 302
 303 /**
 304  * Installs applet required for configured connection to the phone.
 305  *
 306  * \param s State machine data.
 307  * \param ExtraPath Extra path where to search for installation data.
 308  * \param Minimal Whether to do minimal installation (eg. without support
 309  * libraries), useful for applet updates
 310  * \return Result of operation.
 311  *
 312  * \ingroup StateMachine
 313  */
 314 GSM_Error GSM_Install(GSM_StateMachine *s, const char *ExtraPath, gboolean Minimal);
 315
 316 #endif
 317
 318 /* Editor configuration
 319  * vim: noexpandtab sw=8 ts=8 sts=8 tw=72:
 320  */