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 #ifndef ASTERISK_SMDI_H
  28 #define ASTERISK_SMDI_H
  29
  30 #include <termios.h>
  31 #include <time.h>
  32
  33 #include "asterisk/config.h"
  34 #include "asterisk/module.h"
  35 #include "asterisk/optional_api.h"
  36
  37 #define SMDI_MESG_NAME_LEN 80
  38 #define SMDI_MESG_DESK_NUM_LEN 3
  39 #define SMDI_MESG_DESK_TERM_LEN 4
  40 #define SMDI_MWI_FAIL_CAUSE_LEN 3
  41 #define SMDI_MAX_STATION_NUM_LEN 10
  42 #define SMDI_MAX_FILENAME_LEN 256
  43
  44 /*!
  45  * \brief An SMDI message waiting indicator message.
  46  *
  47  * The ast_smdi_mwi_message structure contains the parsed out parts of an smdi
  48  * message.  Each ast_smdi_interface structure has a message queue consisting
  49  * ast_smdi_mwi_message structures.
  50  */
  51 struct ast_smdi_mwi_message {
  52         char name[SMDI_MESG_NAME_LEN];
  53         char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];              /* forwarding station number */
  54         char cause[SMDI_MWI_FAIL_CAUSE_LEN + 1];                /* the type of failure */
  55         struct timeval timestamp;                               /* a timestamp for the message */
  56 };
  57
  58 /*!
  59  * \brief An SMDI message desk message.
  60  *
  61  * The ast_smdi_md_message structure contains the parsed out parts of an smdi
  62  * message.  Each ast_smdi_interface structure has a message queue consisting
  63  * ast_smdi_md_message structures.
  64  */
  65 struct ast_smdi_md_message {
  66         char name[SMDI_MESG_NAME_LEN];
  67         char mesg_desk_num[SMDI_MESG_DESK_NUM_LEN + 1];         /* message desk number */
  68         char mesg_desk_term[SMDI_MESG_DESK_TERM_LEN + 1];       /* message desk terminal */
  69         char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1];              /* forwarding station number */
  70         char calling_st[SMDI_MAX_STATION_NUM_LEN + 1];          /* calling station number */
  71         char type;                                              /* the type of the call */
  72         struct timeval timestamp;                               /* a timestamp for the message */
  73 };
  74
  75 /*!
  76  * \brief SMDI interface structure.
  77  *
  78  * The ast_smdi_interface structure holds information on a serial port that
  79  * should be monitored for SMDI activity.  The structure contains a message
  80  * queue of messages that have been received on the interface.
  81  */
  82 struct ast_smdi_interface;
  83
  84 /*!
  85  * \brief Get the next SMDI message from the queue.
  86  * \param iface a pointer to the interface to use.
  87  *
  88  * This function pulls the first unexpired message from the SMDI message queue
  89  * on the specified interface.  It will purge all expired SMDI messages before
  90  * returning.
  91  *
  92  * \return the next SMDI message, or NULL if there were no pending messages.
  93  */
  94 AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_pop,
  95                  (struct ast_smdi_interface *iface),
  96                  { return NULL; });
  97
  98 /*!
  99  * \brief Get the next SMDI message from the queue.
 100  * \param iface a pointer to the interface to use.
 101  * \param timeout the time to wait before returning in milliseconds.
 102  *
 103  * This function pulls a message from the SMDI message queue on the specified
 104  * interface.  If no message is available this function will wait the specified
 105  * amount of time before returning.
 106  *
 107  * \return the next SMDI message, or NULL if there were no pending messages and
 108  * the timeout has expired.
 109  */
 110 AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_wait,
 111                  (struct ast_smdi_interface *iface, int timeout),
 112                  { return NULL; });
 113
 114 /*!
 115  * \brief Get the next SMDI message from the queue.
 116  * \param iface a pointer to the interface to use.
 117  *
 118  * This function pulls the first unexpired message from the SMDI message queue
 119  * on the specified interface.  It will purge all expired SMDI messages before
 120  * returning.
 121  *
 122  * \return the next SMDI message, or NULL if there were no pending messages.
 123  */
 124 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_pop,
 125                  (struct ast_smdi_interface *iface),
 126                  { return NULL; });
 127
 128 /*!
 129  * \brief Get the next SMDI message from the queue.
 130  * \param iface a pointer to the interface to use.
 131  * \param timeout the time to wait before returning in milliseconds.
 132  *
 133  * This function pulls a message from the SMDI message queue on the specified
 134  * interface.  If no message is available this function will wait the specified
 135  * amount of time before returning.
 136  *
 137  * \return the next SMDI message, or NULL if there were no pending messages and
 138  * the timeout has expired.
 139  */
 140 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait,
 141                  (struct ast_smdi_interface *iface, int timeout),
 142                  { return NULL; });
 143
 144 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait_station,
 145                  (struct ast_smdi_interface *iface, int timeout, const char *station),
 146                  { return NULL; });
 147
 148 /*!
 149  * \brief Find an SMDI interface with the specified name.
 150  * \param iface_name the name/port of the interface to search for.
 151  *
 152  * \return an ao2 reference to the interface located or NULL if none was found.
 153  */
 154 AST_OPTIONAL_API(struct ast_smdi_interface *, ast_smdi_interface_find,
 155                  (const char *iface_name),
 156                  { return NULL; });
 157
 158 /*!
 159  * \brief Set the MWI indicator for a mailbox.
 160  * \param iface the interface to use.
 161  * \param mailbox the mailbox to use.
 162  */
 163 AST_OPTIONAL_API(int, ast_smdi_mwi_set,
 164                  (struct ast_smdi_interface *iface, const char *mailbox),
 165                  { return -1; });
 166
 167 /*!
 168  * \brief Unset the MWI indicator for a mailbox.
 169  * \param iface the interface to use.
 170  * \param mailbox the mailbox to use.
 171  */
 172 AST_OPTIONAL_API(int, ast_smdi_mwi_unset,
 173                  (struct ast_smdi_interface *iface, const char *mailbox),
 174                  { return -1; });
 175
 176 #endif /* !ASTERISK_SMDI_H */