include/asterisk/smdi.h

   1 /*
   2  * Asterisk -- A telephony toolkit for Linux.
   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
  41 #define SMDI_MESG_DESK_NUM_LEN 3
  42 #define SMDI_MESG_DESK_TERM_LEN 4
  43 #define SMDI_MWI_FAIL_CAUSE_LEN 3
  44 #define SMDI_MAX_STATION_NUM_LEN 10
  45 #define SMDI_MAX_FILENAME_LEN 256
  46
  47 /*!
  48  * \brief An SMDI message waiting indicator message.
  49  *
  50  * The ast_smdi_mwi_message structure contains the parsed out parts of an smdi
  51  * message.  Each ast_smdi_interface structure has a message queue consisting
  52  * ast_smdi_mwi_message structures.
  53  */
  54 struct ast_smdi_mwi_message {
  55         ASTOBJ_COMPONENTS(struct ast_smdi_mwi_message);
  56         char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];              /* forwarding station number */
  57         char cause[SMDI_MWI_FAIL_CAUSE_LEN + 1];                /* the type of failure */
  58         struct timeval timestamp;                               /* a timestamp for the message */
  59 };
  60
  61 /*!
  62  * \brief An SMDI message desk message.
  63  *
  64  * The ast_smdi_md_message structure contains the parsed out parts of an smdi
  65  * message.  Each ast_smdi_interface structure has a message queue consisting
  66  * ast_smdi_md_message structures.
  67  */
  68 struct ast_smdi_md_message {
  69         ASTOBJ_COMPONENTS(struct ast_smdi_md_message);
  70         char mesg_desk_num[SMDI_MESG_DESK_NUM_LEN + 1];         /* message desk number */
  71         char mesg_desk_term[SMDI_MESG_DESK_TERM_LEN + 1];       /* message desk terminal */
  72         char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];              /* forwarding station number */
  73         char calling_st[SMDI_MAX_STATION_NUM_LEN + 1];          /* calling station number */
  74         char type;                                              /* the type of the call */
  75         struct timeval timestamp;                               /* a timestamp for the message */
  76 };
  77
  78 /*!
  79  * \brief SMDI interface structure.
  80  *
  81  * The ast_smdi_interface structure holds information on a serial port that
  82  * should be monitored for SMDI activity.  The structure contains a message
  83  * queue of messages that have been recieved on the interface.
  84  */
  85 struct ast_smdi_interface;
  86
  87 void ast_smdi_interface_unref(struct ast_smdi_interface *iface);
  88
  89 /*!
  90  * \brief Get the next SMDI message from the queue.
  91  * \param iface a pointer to the interface to use.
  92  *
  93  * This function pulls the first unexpired message from the SMDI message queue
  94  * on the specified interface.  It will purge all expired SMDI messages before
  95  * returning.
  96  *
  97  * \return the next SMDI message, or NULL if there were no pending messages.
  98  */
  99 struct ast_smdi_md_message *ast_smdi_md_message_pop(struct ast_smdi_interface *iface);
 100
 101 /*!
 102  * \brief Get the next SMDI message from the queue.
 103  * \param iface a pointer to the interface to use.
 104  * \param timeout the time to wait before returning in milliseconds.
 105  *
 106  * This function pulls a message from the SMDI message queue on the specified
 107  * interface.  If no message is available this function will wait the specified
 108  * amount of time before returning.
 109  *
 110  * \return the next SMDI message, or NULL if there were no pending messages and
 111  * the timeout has expired.
 112  */
 113 struct ast_smdi_md_message *ast_smdi_md_message_wait(struct ast_smdi_interface *iface, int timeout);
 114
 115 /*!
 116  * \brief Put an SMDI message back in the front of the queue.
 117  * \param iface a pointer to the interface to use.
 118  * \param md_msg a pointer to the message to use.
 119  *
 120  * This function puts a message back in the front of the specified queue.  It
 121  * should be used if a message was popped but is not going to be processed for
 122  * some reason, and the message needs to be returned to the queue.
 123  */
 124 void ast_smdi_md_message_putback(struct ast_smdi_interface *iface, struct ast_smdi_md_message *msg);
 125
 126 /*!
 127  * \brief Get the next SMDI message from the queue.
 128  * \param iface a pointer to the interface to use.
 129  *
 130  * This function pulls the first unexpired message from the SMDI message queue
 131  * on the specified interface.  It will purge all expired SMDI messages before
 132  * returning.
 133  *
 134  * \return the next SMDI message, or NULL if there were no pending messages.
 135  */
 136 struct ast_smdi_mwi_message *ast_smdi_mwi_message_pop(struct ast_smdi_interface *iface);
 137
 138 /*!
 139  * \brief Get the next SMDI message from the queue.
 140  * \param iface a pointer to the interface to use.
 141  * \param timeout the time to wait before returning in milliseconds.
 142  *
 143  * This function pulls a message from the SMDI message queue on the specified
 144  * interface.  If no message is available this function will wait the specified
 145  * amount of time before returning.
 146  *
 147  * \return the next SMDI message, or NULL if there were no pending messages and
 148  * the timeout has expired.
 149  */
 150 struct ast_smdi_mwi_message *ast_smdi_mwi_message_wait(struct ast_smdi_interface *iface, int timeout);
 151 struct ast_smdi_mwi_message *ast_smdi_mwi_message_wait_station(struct ast_smdi_interface *iface,
 152         int timeout, const char *station);
 153
 154 /*!
 155  * \brief Put an SMDI message back in the front of the queue.
 156  * \param iface a pointer to the interface to use.
 157  * \param mwi_msg a pointer to the message to use.
 158  *
 159  * This function puts a message back in the front of the specified queue.  It
 160  * should be used if a message was popped but is not going to be processed for
 161  * some reason, and the message needs to be returned to the queue.
 162  */
 163 void ast_smdi_mwi_message_putback(struct ast_smdi_interface *iface, struct ast_smdi_mwi_message *msg);
 164
 165 /*!
 166  * \brief Find an SMDI interface with the specified name.
 167  * \param iface_name the name/port of the interface to search for.
 168  *
 169  * \return a pointer to the interface located or NULL if none was found.  This
 170  * actually returns an ASTOBJ reference and should be released using
 171  * #ASTOBJ_UNREF(iface, ast_smdi_interface_destroy).
 172  */
 173 struct ast_smdi_interface *ast_smdi_interface_find(const char *iface_name);
 174
 175 /*!
 176  * \brief Set the MWI indicator for a mailbox.
 177  * \param iface the interface to use.
 178  * \param mailbox the mailbox to use.
 179  */
 180 int ast_smdi_mwi_set(struct ast_smdi_interface *iface, const char *mailbox);
 181
 182 /*!
 183  * \brief Unset the MWI indicator for a mailbox.
 184  * \param iface the interface to use.
 185  * \param mailbox the mailbox to use.
 186  */
 187 int ast_smdi_mwi_unset(struct ast_smdi_interface *iface, const char *mailbox);
 188
 189 /*! \brief ast_smdi_md_message destructor. */
 190 void ast_smdi_md_message_destroy(struct ast_smdi_md_message *msg);
 191
 192 /*! \brief ast_smdi_mwi_message destructor. */
 193 void ast_smdi_mwi_message_destroy(struct ast_smdi_mwi_message *msg);
 194
 195 #endif /* !ASTERISK_SMDI_H */