gatchat/gatchat.h

   1 /*
   2  *
   3  *  AT chat library with GLib integration
   4  *
   5  *  Copyright (C) 2008-2009  Intel Corporation. All rights reserved.
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License version 2 as
   9  *  published by the Free Software Foundation.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19  *
  20  */
  21
  22 #ifndef __GATCHAT_H
  23 #define __GATCHAT_H
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 #include "gatresult.h"
  30 #include "gatsyntax.h"
  31
  32 struct _GAtChat;
  33
  34 typedef struct _GAtChat GAtChat;
  35
  36 typedef void (*GAtResultFunc)(gboolean success, GAtResult *result,
  37                                 gpointer user_data);
  38 typedef void (*GAtNotifyFunc)(GAtResult *result, gpointer user_data);
  39 typedef void (*GAtDisconnectFunc)(gpointer user_data);
  40 typedef void (*GAtDebugFunc)(const char *str, gpointer user_data);
  41
  42 GAtChat *g_at_chat_new(GIOChannel *channel, GAtSyntax *syntax);
  43
  44 GIOChannel *g_at_chat_get_channel(GAtChat *chat);
  45
  46 GAtChat *g_at_chat_ref(GAtChat *chat);
  47 void g_at_chat_unref(GAtChat *chat);
  48
  49 gboolean g_at_chat_shutdown(GAtChat *chat);
  50
  51 gboolean g_at_chat_set_syntax(GAtChat *chat, GAtSyntax *syntax);
  52
  53 gboolean g_at_chat_set_disconnect_function(GAtChat *chat,
  54                         GAtDisconnectFunc disconnect, gpointer user_data);
  55
  56 /*!
  57  * If the function is not NULL, then on every read/write from the GIOChannel
  58  * provided to GAtChat the logging function will be called with the
  59  * input/output string and user data
  60  */
  61 gboolean g_at_chat_set_debug(GAtChat *chat, GAtDebugFunc func, gpointer user);
  62
  63 /*!
  64  * Queue an AT command for execution.  The command contents are given
  65  * in cmd.  Once the command executes, the callback function given by
  66  * func is called with user provided data in user_data.
  67  *
  68  * Returns an id of the queued command which can be canceled using
  69  * g_at_chat_cancel.  If an error occurred, an id of 0 is returned.
  70  *
  71  * This function can be used in three ways:
  72  *      - Send a simple command such as g_at_chat_send(p, "AT+CGMI?", ...
  73  *
  74  *      - Send a compound command: g_at_chat_send(p, "AT+CMD1;+CMD2", ...
  75  *
  76  *      - Send a command requiring a prompt.  The command up to '\r' is sent
  77  *        after which time a '> ' prompt is expected from the modem.  Further
  78  *        contents of the command are sent until a '\r' or end of string is
  79  *        encountered.  If end of string is encountered, the Ctrl-Z character
  80  *        is sent automatically.  There is no need to include the Ctrl-Z
  81  *        by the caller.
  82  *
  83  * The valid_resp field can be used to send an array of strings which will
  84  * be accepted as a valid response for this command.  This is treated as a
  85  * simple prefix match.  If a response line comes in from the modem and it
  86  * does not match any of the prefixes in valid_resp, it is treated as an
  87  * unsolicited notification.  If valid_resp is NULL, then all response
  88  * lines after command submission and final response line are treated as
  89  * part of the command response.  This can be used to get around broken
  90  * modems which send unsolicited notifications during command processing.
  91  */
  92 guint g_at_chat_send(GAtChat *chat, const char *cmd,
  93                                 const char **valid_resp, GAtResultFunc func,
  94                                 gpointer user_data, GDestroyNotify notify);
  95
  96 /*!
  97  * Same as the above command, except that the caller wishes to receive the
  98  * intermediate responses immediately through the GAtNotifyFunc callback.
  99  * The final response will still be sent to GAtResultFunc callback.  The
 100  * final GAtResult will not contain any lines from the intermediate responses.
 101  * This is useful for listing commands such as CPBR.
 102  */
 103 guint g_at_chat_send_listing(GAtChat *chat, const char *cmd,
 104                                 const char **valid_resp,
 105                                 GAtNotifyFunc listing, GAtResultFunc func,
 106                                 gpointer user_data, GDestroyNotify notify);
 107
 108 /*!
 109  * Same as g_at_chat_send_listing except every response line in valid_resp
 110  * is expected to be followed by a PDU.  The listing function will be called
 111  * with the intermediate response and the following PDU line.
 112  *
 113  * This is useful for PDU listing commands like the +CMGL
 114  */
 115 guint g_at_chat_send_pdu_listing(GAtChat *chat, const char *cmd,
 116                                 const char **valid_resp,
 117                                 GAtNotifyFunc listing, GAtResultFunc func,
 118                                 gpointer user_data, GDestroyNotify notify);
 119
 120 gboolean g_at_chat_cancel(GAtChat *chat, guint id);
 121 gboolean g_at_chat_cancel_all(GAtChat *chat);
 122
 123 guint g_at_chat_register(GAtChat *chat, const char *prefix,
 124                                 GAtNotifyFunc func, gboolean expect_pdu,
 125                                 gpointer user_data, GDestroyNotify notify);
 126
 127 gboolean g_at_chat_unregister(GAtChat *chat, guint id);
 128
 129 gboolean g_at_chat_set_wakeup_command(GAtChat *chat, const char *cmd,
 130                                         guint timeout, guint msec);
 131
 132 void g_at_chat_add_terminator(GAtChat *chat, char *terminator,
 133                                 int len, gboolean success);
 134
 135
 136 #ifdef __cplusplus
 137 }
 138 #endif
 139
 140 #endif /* __GATCHAT_H */