gatchat/gatchat.h

   1 /*
   2  *
   3  *  AT chat library with GLib integration
   4  *
   5  *  Copyright (C) 2008-2011  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 #include "gatutil.h"
  32 #include "gatio.h"
  33
  34 struct _GAtChat;
  35
  36 typedef struct _GAtChat GAtChat;
  37
  38 typedef void (*GAtResultFunc)(gboolean success, GAtResult *result,
  39                                 gpointer user_data);
  40 typedef void (*GAtNotifyFunc)(GAtResult *result, gpointer user_data);
  41
  42 enum _GAtChatTerminator {
  43         G_AT_CHAT_TERMINATOR_OK,
  44         G_AT_CHAT_TERMINATOR_ERROR,
  45         G_AT_CHAT_TERMINATOR_NO_DIALTONE,
  46         G_AT_CHAT_TERMINATOR_BUSY,
  47         G_AT_CHAT_TERMINATOR_NO_CARRIER,
  48         G_AT_CHAT_TERMINATOR_CONNECT,
  49         G_AT_CHAT_TERMINATOR_NO_ANSWER,
  50         G_AT_CHAT_TERMINATOR_CMS_ERROR,
  51         G_AT_CHAT_TERMINATOR_CME_ERROR,
  52         G_AT_CHAT_TERMINATOR_EXT_ERROR,
  53 };
  54
  55 typedef enum _GAtChatTerminator GAtChatTerminator;
  56
  57 GAtChat *g_at_chat_new(GIOChannel *channel, GAtSyntax *syntax);
  58 GAtChat *g_at_chat_new_blocking(GIOChannel *channel, GAtSyntax *syntax);
  59
  60 GIOChannel *g_at_chat_get_channel(GAtChat *chat);
  61 GAtIO *g_at_chat_get_io(GAtChat *chat);
  62
  63 GAtChat *g_at_chat_ref(GAtChat *chat);
  64 void g_at_chat_unref(GAtChat *chat);
  65
  66 GAtChat *g_at_chat_clone(GAtChat *chat);
  67
  68 GAtChat *g_at_chat_set_slave(GAtChat *chat, GAtChat *slave);
  69 GAtChat *g_at_chat_get_slave(GAtChat *chat);
  70
  71 void g_at_chat_suspend(GAtChat *chat);
  72 void g_at_chat_resume(GAtChat *chat);
  73
  74 gboolean g_at_chat_set_disconnect_function(GAtChat *chat,
  75                         GAtDisconnectFunc disconnect, gpointer user_data);
  76
  77 /*!
  78  * If the function is not NULL, then on every read/write from the GIOChannel
  79  * provided to GAtChat the logging function will be called with the
  80  * input/output string and user data
  81  */
  82 gboolean g_at_chat_set_debug(GAtChat *chat,
  83                                 GAtDebugFunc func, gpointer user_data);
  84
  85 /*!
  86  * Queue an AT command for execution.  The command contents are given
  87  * in cmd.  Once the command executes, the callback function given by
  88  * func is called with user provided data in user_data.
  89  *
  90  * Returns an id of the queued command which can be canceled using
  91  * g_at_chat_cancel.  If an error occurred, an id of 0 is returned.
  92  *
  93  * This function can be used in three ways:
  94  *      - Send a simple command such as g_at_chat_send(p, "AT+CGMI?", ...
  95  *
  96  *      - Send a compound command: g_at_chat_send(p, "AT+CMD1;+CMD2", ...
  97  *
  98  *      - Send a command requiring a prompt.  The command up to '\r' is sent
  99  *        after which time a '> ' prompt is expected from the modem.  Further
 100  *        contents of the command are sent until a '\r' or end of string is
 101  *        encountered.  If end of string is encountered, the Ctrl-Z character
 102  *        is sent automatically.  There is no need to include the Ctrl-Z
 103  *        by the caller.
 104  *
 105  * The valid_resp field can be used to send an array of strings which will
 106  * be accepted as a valid response for this command.  This is treated as a
 107  * simple prefix match.  If a response line comes in from the modem and it
 108  * does not match any of the prefixes in valid_resp, it is treated as an
 109  * unsolicited notification.  If valid_resp is NULL, then all response
 110  * lines after command submission and final response line are treated as
 111  * part of the command response.  This can be used to get around broken
 112  * modems which send unsolicited notifications during command processing.
 113  */
 114 guint g_at_chat_send(GAtChat *chat, const char *cmd,
 115                                 const char **valid_resp, GAtResultFunc func,
 116                                 gpointer user_data, GDestroyNotify notify);
 117
 118 /*!
 119  * Same as the above command, except that the caller wishes to receive the
 120  * intermediate responses immediately through the GAtNotifyFunc callback.
 121  * The final response will still be sent to GAtResultFunc callback.  The
 122  * final GAtResult will not contain any lines from the intermediate responses.
 123  * This is useful for listing commands such as CPBR.
 124  */
 125 guint g_at_chat_send_listing(GAtChat *chat, const char *cmd,
 126                                 const char **valid_resp,
 127                                 GAtNotifyFunc listing, GAtResultFunc func,
 128                                 gpointer user_data, GDestroyNotify notify);
 129
 130 /*!
 131  * Same as g_at_chat_send_listing except every response line in valid_resp
 132  * is expected to be followed by a PDU.  The listing function will be called
 133  * with the intermediate response and the following PDU line.
 134  *
 135  * This is useful for PDU listing commands like the +CMGL
 136  */
 137 guint g_at_chat_send_pdu_listing(GAtChat *chat, const char *cmd,
 138                                 const char **valid_resp,
 139                                 GAtNotifyFunc listing, GAtResultFunc func,
 140                                 gpointer user_data, GDestroyNotify notify);
 141
 142 /*!
 143  * Same as g_at_chat_send except parser will know to expect short prompt syntax
 144  * used with +CPOS.
 145  */
 146 guint g_at_chat_send_and_expect_short_prompt(GAtChat *chat, const char *cmd,
 147                                 const char **valid_resp, GAtResultFunc func,
 148                                 gpointer user_data, GDestroyNotify notify);
 149
 150 gboolean g_at_chat_cancel(GAtChat *chat, guint id);
 151 gboolean g_at_chat_cancel_all(GAtChat *chat);
 152
 153 guint g_at_chat_register(GAtChat *chat, const char *prefix,
 154                                 GAtNotifyFunc func, gboolean expect_pdu,
 155                                 gpointer user_data, GDestroyNotify notify);
 156
 157 gboolean g_at_chat_unregister(GAtChat *chat, guint id);
 158 gboolean g_at_chat_unregister_all(GAtChat *chat);
 159
 160 gboolean g_at_chat_set_wakeup_command(GAtChat *chat, const char *cmd,
 161                                         guint timeout, guint msec);
 162
 163 void g_at_chat_add_terminator(GAtChat *chat, char *terminator,
 164                                 int len, gboolean success);
 165 void g_at_chat_blacklist_terminator(GAtChat *chat,
 166                                                 GAtChatTerminator terminator);
 167
 168 #ifdef __cplusplus
 169 }
 170 #endif
 171
 172 #endif /* __GATCHAT_H */