Sat Aug 6 00:39:32 2011

Asterisk developer's documentation


smdi.h

Go to the documentation of this file.
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 */

Generated on Sat Aug 6 00:39:32 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7