Recorded merge of revisions 195366 via svnmerge from
[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, (struct ast_smdi_interface
89         *iface), { return; });
90
91 /*! 
92  * \brief Get the next SMDI message from the queue.
93  * \param iface a pointer to the interface to use.
94  *
95  * This function pulls the first unexpired message from the SMDI message queue
96  * on the specified interface.  It will purge all expired SMDI messages before
97  * returning.
98  *
99  * \return the next SMDI message, or NULL if there were no pending messages.
100  */
101 AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_pop, (struct
102         ast_smdi_interface *iface), { return NULL; });
103
104 /*!
105  * \brief Get the next SMDI message from the queue.
106  * \param iface a pointer to the interface to use.
107  * \param timeout the time to wait before returning in milliseconds.
108  *
109  * This function pulls a message from the SMDI message queue on the specified
110  * interface.  If no message is available this function will wait the specified
111  * amount of time before returning.
112  *
113  * \return the next SMDI message, or NULL if there were no pending messages and
114  * the timeout has expired.
115  */
116 AST_OPTIONAL_API(struct ast_smdi_md_message *, ast_smdi_md_message_wait,
117         (struct ast_smdi_interface *iface, int timeout), { return NULL; });
118
119 /*!
120  * \brief Put an SMDI message back in the front of the queue.
121  * \param iface a pointer to the interface to use.
122  * \param md_msg a pointer to the message to use.
123  *
124  * This function puts a message back in the front of the specified queue.  It
125  * should be used if a message was popped but is not going to be processed for
126  * some reason, and the message needs to be returned to the queue.
127  */
128 AST_OPTIONAL_API(void, ast_smdi_md_message_putback, (struct ast_smdi_interface
129         *iface, struct ast_smdi_md_message *msg), { return; });
130
131 /*!
132  * \brief Get the next SMDI message from the queue.
133  * \param iface a pointer to the interface to use.
134  *
135  * This function pulls the first unexpired message from the SMDI message queue
136  * on the specified interface.  It will purge all expired SMDI messages before
137  * returning.
138  *
139  * \return the next SMDI message, or NULL if there were no pending messages.
140  */
141 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_pop,
142         (struct ast_smdi_interface *iface), { return NULL; });
143
144 /*!
145  * \brief Get the next SMDI message from the queue.
146  * \param iface a pointer to the interface to use.
147  * \param timeout the time to wait before returning in milliseconds.
148  *
149  * This function pulls a message from the SMDI message queue on the specified
150  * interface.  If no message is available this function will wait the specified
151  * amount of time before returning.
152  *
153  * \return the next SMDI message, or NULL if there were no pending messages and
154  * the timeout has expired.
155  */
156 AST_OPTIONAL_API(struct ast_smdi_mwi_message *, ast_smdi_mwi_message_wait,
157         (struct ast_smdi_interface *iface, int timeout), { return NULL; });
158 AST_OPTIONAL_API(struct ast_smdi_mwi_message *,
159         ast_smdi_mwi_message_wait_station, (struct ast_smdi_interface *iface, int
160         timeout, const char *station), { return NULL; });
161
162 /*!
163  * \brief Put an SMDI message back in the front of the queue.
164  * \param iface a pointer to the interface to use.
165  * \param mwi_msg a pointer to the message to use.
166  *
167  * This function puts a message back in the front of the specified queue.  It
168  * should be used if a message was popped but is not going to be processed for
169  * some reason, and the message needs to be returned to the queue.
170  */
171 AST_OPTIONAL_API(void, ast_smdi_mwi_message_putback, (struct ast_smdi_interface
172         *iface, struct ast_smdi_mwi_message *msg), { return; });
173
174 /*!
175  * \brief Find an SMDI interface with the specified name.
176  * \param iface_name the name/port of the interface to search for.
177  *
178  * \return a pointer to the interface located or NULL if none was found.  This
179  * actually returns an ASTOBJ reference and should be released using
180  * #ASTOBJ_UNREF(iface, ast_smdi_interface_destroy).
181  */
182 AST_OPTIONAL_API(struct ast_smdi_interface *, ast_smdi_interface_find,
183         (const char *iface_name), { return NULL; });
184
185 /*!
186  * \brief Set the MWI indicator for a mailbox.
187  * \param iface the interface to use.
188  * \param mailbox the mailbox to use.
189  */
190 AST_OPTIONAL_API(int, ast_smdi_mwi_set, (struct ast_smdi_interface *iface,
191         const char *mailbox), { return -1; });
192
193 /*! 
194  * \brief Unset the MWI indicator for a mailbox.
195  * \param iface the interface to use.
196  * \param mailbox the mailbox to use.
197  */
198 AST_OPTIONAL_API(int, ast_smdi_mwi_unset, (struct ast_smdi_interface *iface,
199         const char *mailbox), { return -1; });
200
201 /*! \brief ast_smdi_md_message destructor. */
202 AST_OPTIONAL_API(void, ast_smdi_md_message_destroy,
203         (struct ast_smdi_md_message *msg), { return; });
204
205 /*! \brief ast_smdi_mwi_message destructor. */
206 AST_OPTIONAL_API(void, ast_smdi_mwi_message_destroy, (struct
207         ast_smdi_mwi_message *msg), { return; });
208
209 #endif /* !ASTERISK_SMDI_H */