include/asterisk/smdi.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 2005-2008, Digium, Inc.
   5  *
   6  * Matthew A. Nicholson <mnicholson@digium.com>
   7  * Russell Bryant <russell@digium.com>
   8  *
   9  * See http://www.asterisk.org for more information about
  10  * the Asterisk project. Please do not directly contact
  11  * any of the maintainers of this project for assistance;
  12  * the project provides a web site, mailing lists and IRC
  13  * channels for your use.
  14  *
  15  * This program is free software, distributed under the terms of
  16  * the GNU General Public License Version 2. See the LICENSE file
  17  * at the top of the source tree.
  18  */
  19
  20 /*!
  21  * \file
  22  * \brief SMDI support for Asterisk.
  23  * \author Matthew A. Nicholson <mnicholson@digium.com>
  24  * \author Russell Bryant <russell@digium.com>
  25  */
  26
  27
  28 /* C is simply a ego booster for those who want to do objects the hard way. */
  29
  30
  31 #ifndef ASTERISK_SMDI_H
  32 #define ASTERISK_SMDI_H
  33
  34 #include <termios.h>
  35 #include <time.h>
  36
  37 #include "asterisk/config.h"
  38 #include "asterisk/module.h"
  39 #include "asterisk/astobj.h"
  40 #include "asterisk/optional_api.h"
  41
  42 #define SMDI_MESG_DESK_NUM_LEN 3
  43 #define SMDI_MESG_DESK_TERM_LEN 4
  44 #define SMDI_MWI_FAIL_CAUSE_LEN 3
  45 #define SMDI_MAX_STATION_NUM_LEN 10
  46 #define SMDI_MAX_FILENAME_LEN 256
  47
  48 /*!
  49  * \brief An SMDI message waiting indicator message.
  50  *
  51  * The ast_smdi_mwi_message structure contains the parsed out parts of an smdi
  52  * message.  Each ast_smdi_interface structure has a message queue consisting
  53  * ast_smdi_mwi_message structures.
  54  */
  55 struct ast_smdi_mwi_message {
  56         ASTOBJ_COMPONENTS(struct ast_smdi_mwi_message);
  57         char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];              /* forwarding station number */
  58         char cause[SMDI_MWI_FAIL_CAUSE_LEN + 1];                /* the type of failure */
  59         struct timeval timestamp;                               /* a timestamp for the message */
  60 };
  61
  62 /*!
  63  * \brief An SMDI message desk message.
  64  *
  65  * The ast_smdi_md_message structure contains the parsed out parts of an smdi
  66  * message.  Each ast_smdi_interface structure has a message queue consisting
  67  * ast_smdi_md_message structures.
  68  */
  69 struct ast_smdi_md_message {
  70         ASTOBJ_COMPONENTS(struct ast_smdi_md_message);
  71         char mesg_desk_num[SMDI_MESG_DESK_NUM_LEN + 1];         /* message desk number */
  72         char mesg_desk_term[SMDI_MESG_DESK_TERM_LEN + 1];       /* message desk terminal */
  73         char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];              /* forwarding station number */
  74         char calling_st[SMDI_MAX_STATION_NUM_LEN + 1];          /* calling station number */
  75         char type;                                              /* the type of the call */
  76         struct timeval timestamp;                               /* a timestamp for the message */
  77 };
  78
  79 /*!
  80  * \brief SMDI interface structure.
  81  *
  82  * The ast_smdi_interface structure holds information on a serial port that
  83  * should be monitored for SMDI activity.  The structure contains a message
  84  * queue of messages that have been received on the interface.
  85  */
  86 struct ast_smdi_interface;
  87
  88 AST_OPTIONAL_API(void, ast_smdi_interface_unref,
  89                  (struct ast_smdi_interface *iface),
  90                  { return; });
  91
  92 /*!
  93  * \brief Get the next SMDI message from the queue.
  94  * \param iface a pointer to the interface to use.
  95  *
  96  * This function pulls the first unexpired message from the SMDI message queue
  97  * on the specified interface.  It will purge all expired SMDI messages before
  98  * returning.
  99  *
 100  * \return the next SMDI message, or NULL if there were no pending messages.
 101  */
 102 AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_pop,
 103                  (struct ast_smdi_interface *iface),
 104                  { return NULL; });
 105
 106 /*!
 107  * \brief Get the next SMDI message from the queue.
 108  * \param iface a pointer to the interface to use.
 109  * \param timeout the time to wait before returning in milliseconds.
 110  *
 111  * This function pulls a message from the SMDI message queue on the specified
 112  * interface.  If no message is available this function will wait the specified
 113  * amount of time before returning.
 114  *
 115  * \return the next SMDI message, or NULL if there were no pending messages and
 116  * the timeout has expired.
 117  */
 118 AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_wait,
 119                  (struct ast_smdi_interface *iface, int timeout),
 120                  { return NULL; });
 121
 122 /*!
 123  * \brief Put an SMDI message back in the front of the queue.
 124  * \param iface a pointer to the interface to use.
 125  * \param msg a pointer to the message to use.
 126  *
 127  * This function puts a message back in the front of the specified queue.  It
 128  * should be used if a message was popped but is not going to be processed for
 129  * some reason, and the message needs to be returned to the queue.
 130  */
 131 AST_OPTIONAL_API(void, ast_smdi_md_message_putback,
 132                  (struct ast_smdi_interface *iface, struct ast_smdi_md_message *msg),
 133                  { return; });
 134
 135 /*!
 136  * \brief Get the next SMDI message from the queue.
 137  * \param iface a pointer to the interface to use.
 138  *
 139  * This function pulls the first unexpired message from the SMDI message queue
 140  * on the specified interface.  It will purge all expired SMDI messages before
 141  * returning.
 142  *
 143  * \return the next SMDI message, or NULL if there were no pending messages.
 144  */
 145 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_pop,
 146                  (struct ast_smdi_interface *iface),
 147                  { return NULL; });
 148
 149 /*!
 150  * \brief Get the next SMDI message from the queue.
 151  * \param iface a pointer to the interface to use.
 152  * \param timeout the time to wait before returning in milliseconds.
 153  *
 154  * This function pulls a message from the SMDI message queue on the specified
 155  * interface.  If no message is available this function will wait the specified
 156  * amount of time before returning.
 157  *
 158  * \return the next SMDI message, or NULL if there were no pending messages and
 159  * the timeout has expired.
 160  */
 161 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait,
 162                  (struct ast_smdi_interface *iface, int timeout),
 163                  { return NULL; });
 164
 165 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait_station,
 166                  (struct ast_smdi_interface *iface, int timeout, const char *station),
 167                  { return NULL; });
 168
 169 /*!
 170  * \brief Put an SMDI message back in the front of the queue.
 171  * \param iface a pointer to the interface to use.
 172  * \param msg a pointer to the message to use.
 173  *
 174  * This function puts a message back in the front of the specified queue.  It
 175  * should be used if a message was popped but is not going to be processed for
 176  * some reason, and the message needs to be returned to the queue.
 177  */
 178 AST_OPTIONAL_API(void, ast_smdi_mwi_message_putback,
 179                  (struct ast_smdi_interface *iface, struct ast_smdi_mwi_message *msg),
 180                  { return; });
 181
 182 /*!
 183  * \brief Find an SMDI interface with the specified name.
 184  * \param iface_name the name/port of the interface to search for.
 185  *
 186  * \return a pointer to the interface located or NULL if none was found.  This
 187  * actually returns an ASTOBJ reference and should be released using
 188  * #ASTOBJ_UNREF(iface, ast_smdi_interface_destroy).
 189  */
 190 AST_OPTIONAL_API(struct ast_smdi_interface *, ast_smdi_interface_find,
 191                  (const char *iface_name),
 192                  { return NULL; });
 193
 194 /*!
 195  * \brief Set the MWI indicator for a mailbox.
 196  * \param iface the interface to use.
 197  * \param mailbox the mailbox to use.
 198  */
 199 AST_OPTIONAL_API(int, ast_smdi_mwi_set,
 200                  (struct ast_smdi_interface *iface, const char *mailbox),
 201                  { return -1; });
 202
 203 /*!
 204  * \brief Unset the MWI indicator for a mailbox.
 205  * \param iface the interface to use.
 206  * \param mailbox the mailbox to use.
 207  */
 208 AST_OPTIONAL_API(int, ast_smdi_mwi_unset,
 209                  (struct ast_smdi_interface *iface, const char *mailbox),
 210                  { return -1; });
 211
 212 /*! \brief ast_smdi_md_message destructor. */
 213 AST_OPTIONAL_API(void, ast_smdi_md_message_destroy,
 214                  (struct ast_smdi_md_message *msg),
 215                  { return; });
 216
 217 /*! \brief ast_smdi_mwi_message destructor. */
 218 AST_OPTIONAL_API(void, ast_smdi_mwi_message_destroy,
 219                  (struct ast_smdi_mwi_message *msg),
 220                  { return; });
 221
 222 #endif /* !ASTERISK_SMDI_H */