090470d4a5f1cc88f089d2fad2dfbb1a18ec99d0
[asterisk/asterisk.git] / 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 #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 */