00001 /* 00002 * Asterisk -- A telephony toolkit for Linux. 00003 * 00004 * Copyright (C) 2005-2008, Digium, Inc. 00005 * 00006 * Matthew A. Nicholson <mnicholson@digium.com> 00007 * Russell Bryant <russell@digium.com> 00008 * 00009 * See http://www.asterisk.org for more information about 00010 * the Asterisk project. Please do not directly contact 00011 * any of the maintainers of this project for assistance; 00012 * the project provides a web site, mailing lists and IRC 00013 * channels for your use. 00014 * 00015 * This program is free software, distributed under the terms of 00016 * the GNU General Public License Version 2. See the LICENSE file 00017 * at the top of the source tree. 00018 */ 00019 00020 /*! 00021 * \file 00022 * \brief SMDI support for Asterisk. 00023 * \author Matthew A. Nicholson <mnicholson@digium.com> 00024 * \author Russell Bryant <russell@digium.com> 00025 */ 00026 00027 00028 /* C is simply a ego booster for those who want to do objects the hard way. */ 00029 00030 00031 #ifndef ASTERISK_SMDI_H 00032 #define ASTERISK_SMDI_H 00033 00034 #include <termios.h> 00035 #include <time.h> 00036 00037 #include "asterisk/config.h" 00038 #include "asterisk/module.h" 00039 #include "asterisk/astobj.h" 00040 00041 #define SMDI_MESG_DESK_NUM_LEN 3 00042 #define SMDI_MESG_DESK_TERM_LEN 4 00043 #define SMDI_MWI_FAIL_CAUSE_LEN 3 00044 #define SMDI_MAX_STATION_NUM_LEN 10 00045 #define SMDI_MAX_FILENAME_LEN 256 00046 00047 /*! 00048 * \brief An SMDI message waiting indicator message. 00049 * 00050 * The ast_smdi_mwi_message structure contains the parsed out parts of an smdi 00051 * message. Each ast_smdi_interface structure has a message queue consisting 00052 * ast_smdi_mwi_message structures. 00053 */ 00054 struct ast_smdi_mwi_message { 00055 ASTOBJ_COMPONENTS(struct ast_smdi_mwi_message); 00056 char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1]; /* forwarding station number */ 00057 char cause[SMDI_MWI_FAIL_CAUSE_LEN + 1]; /* the type of failure */ 00058 struct timeval timestamp; /* a timestamp for the message */ 00059 }; 00060 00061 /*! 00062 * \brief An SMDI message desk message. 00063 * 00064 * The ast_smdi_md_message structure contains the parsed out parts of an smdi 00065 * message. Each ast_smdi_interface structure has a message queue consisting 00066 * ast_smdi_md_message structures. 00067 */ 00068 struct ast_smdi_md_message { 00069 ASTOBJ_COMPONENTS(struct ast_smdi_md_message); 00070 char mesg_desk_num[SMDI_MESG_DESK_NUM_LEN + 1]; /* message desk number */ 00071 char mesg_desk_term[SMDI_MESG_DESK_TERM_LEN + 1]; /* message desk terminal */ 00072 char fwd_st[SMDI_MAX_STATION_NUM_LEN + 1]; /* forwarding station number */ 00073 char calling_st[SMDI_MAX_STATION_NUM_LEN + 1]; /* calling station number */ 00074 char type; /* the type of the call */ 00075 struct timeval timestamp; /* a timestamp for the message */ 00076 }; 00077 00078 /*! 00079 * \brief SMDI interface structure. 00080 * 00081 * The ast_smdi_interface structure holds information on a serial port that 00082 * should be monitored for SMDI activity. The structure contains a message 00083 * queue of messages that have been received on the interface. 00084 */ 00085 struct ast_smdi_interface; 00086 00087 void ast_smdi_interface_unref(struct ast_smdi_interface *iface); 00088 00089 /*! 00090 * \brief Get the next SMDI message from the queue. 00091 * \param iface a pointer to the interface to use. 00092 * 00093 * This function pulls the first unexpired message from the SMDI message queue 00094 * on the specified interface. It will purge all expired SMDI messages before 00095 * returning. 00096 * 00097 * \return the next SMDI message, or NULL if there were no pending messages. 00098 */ 00099 struct ast_smdi_md_message *ast_smdi_md_message_pop(struct ast_smdi_interface *iface); 00100 00101 /*! 00102 * \brief Get the next SMDI message from the queue. 00103 * \param iface a pointer to the interface to use. 00104 * \param timeout the time to wait before returning in milliseconds. 00105 * 00106 * This function pulls a message from the SMDI message queue on the specified 00107 * interface. If no message is available this function will wait the specified 00108 * amount of time before returning. 00109 * 00110 * \return the next SMDI message, or NULL if there were no pending messages and 00111 * the timeout has expired. 00112 */ 00113 struct ast_smdi_md_message *ast_smdi_md_message_wait(struct ast_smdi_interface *iface, int timeout); 00114 00115 /*! 00116 * \brief Put an SMDI message back in the front of the queue. 00117 * \param iface a pointer to the interface to use. 00118 * \param md_msg a pointer to the message to use. 00119 * 00120 * This function puts a message back in the front of the specified queue. It 00121 * should be used if a message was popped but is not going to be processed for 00122 * some reason, and the message needs to be returned to the queue. 00123 */ 00124 void ast_smdi_md_message_putback(struct ast_smdi_interface *iface, struct ast_smdi_md_message *msg); 00125 00126 /*! 00127 * \brief Get the next SMDI message from the queue. 00128 * \param iface a pointer to the interface to use. 00129 * 00130 * This function pulls the first unexpired message from the SMDI message queue 00131 * on the specified interface. It will purge all expired SMDI messages before 00132 * returning. 00133 * 00134 * \return the next SMDI message, or NULL if there were no pending messages. 00135 */ 00136 struct ast_smdi_mwi_message *ast_smdi_mwi_message_pop(struct ast_smdi_interface *iface); 00137 00138 /*! 00139 * \brief Get the next SMDI message from the queue. 00140 * \param iface a pointer to the interface to use. 00141 * \param timeout the time to wait before returning in milliseconds. 00142 * 00143 * This function pulls a message from the SMDI message queue on the specified 00144 * interface. If no message is available this function will wait the specified 00145 * amount of time before returning. 00146 * 00147 * \return the next SMDI message, or NULL if there were no pending messages and 00148 * the timeout has expired. 00149 */ 00150 struct ast_smdi_mwi_message *ast_smdi_mwi_message_wait(struct ast_smdi_interface *iface, int timeout); 00151 struct ast_smdi_mwi_message *ast_smdi_mwi_message_wait_station(struct ast_smdi_interface *iface, 00152 int timeout, const char *station); 00153 00154 /*! 00155 * \brief Put an SMDI message back in the front of the queue. 00156 * \param iface a pointer to the interface to use. 00157 * \param mwi_msg a pointer to the message to use. 00158 * 00159 * This function puts a message back in the front of the specified queue. It 00160 * should be used if a message was popped but is not going to be processed for 00161 * some reason, and the message needs to be returned to the queue. 00162 */ 00163 void ast_smdi_mwi_message_putback(struct ast_smdi_interface *iface, struct ast_smdi_mwi_message *msg); 00164 00165 /*! 00166 * \brief Find an SMDI interface with the specified name. 00167 * \param iface_name the name/port of the interface to search for. 00168 * 00169 * \return a pointer to the interface located or NULL if none was found. This 00170 * actually returns an ASTOBJ reference and should be released using 00171 * #ASTOBJ_UNREF(iface, ast_smdi_interface_destroy). 00172 */ 00173 struct ast_smdi_interface *ast_smdi_interface_find(const char *iface_name); 00174 00175 /*! 00176 * \brief Set the MWI indicator for a mailbox. 00177 * \param iface the interface to use. 00178 * \param mailbox the mailbox to use. 00179 */ 00180 int ast_smdi_mwi_set(struct ast_smdi_interface *iface, const char *mailbox); 00181 00182 /*! 00183 * \brief Unset the MWI indicator for a mailbox. 00184 * \param iface the interface to use. 00185 * \param mailbox the mailbox to use. 00186 */ 00187 int ast_smdi_mwi_unset(struct ast_smdi_interface *iface, const char *mailbox); 00188 00189 /*! \brief ast_smdi_md_message destructor. */ 00190 void ast_smdi_md_message_destroy(struct ast_smdi_md_message *msg); 00191 00192 /*! \brief ast_smdi_mwi_message destructor. */ 00193 void ast_smdi_mwi_message_destroy(struct ast_smdi_mwi_message *msg); 00194 00195 #endif /* !ASTERISK_SMDI_H */