CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / res_fax.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008-2009, Digium, Inc.
5  *
6  * Dwayne M. Hubbard <dhubbard@digium.com>
7  * Kevin P. Fleming <kpfleming@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 #ifndef _ASTERISK_RES_FAX_H
21 #define _ASTERISK_RES_FAX_H
22
23 #include "asterisk.h"
24 #include "asterisk/lock.h"
25 #include "asterisk/linkedlists.h"
26 #include "asterisk/module.h"
27 #include "asterisk/utils.h"
28 #include "asterisk/options.h"
29 #include "asterisk/frame.h"
30 #include "asterisk/cli.h"
31 #include "asterisk/stringfields.h"
32 #include "asterisk/manager.h"
33
34 /*! \brief capabilities for res_fax to locate a fax technology module */
35 enum ast_fax_capabilities {
36         /*! SendFax is supported */
37         AST_FAX_TECH_SEND      = (1 << 0),
38         /*! ReceiveFax is supported */
39         AST_FAX_TECH_RECEIVE   = (1 << 1),
40         /*! Audio FAX session supported */
41         AST_FAX_TECH_AUDIO     = (1 << 2),
42         /*! T.38 FAX session supported */
43         AST_FAX_TECH_T38       = (1 << 3),
44         /*! sending mulitple documents supported */
45         AST_FAX_TECH_MULTI_DOC = (1 << 4),
46         /*! T.38 - T.30 Gateway */
47         AST_FAX_TECH_GATEWAY = (1 << 5),
48         /*! V21 detection is supported */
49         AST_FAX_TECH_V21_DETECT = (1 << 6),
50 };
51
52 /*! \brief fax modem capabilities */
53 enum ast_fax_modems {
54         /*! V.17 */
55         AST_FAX_MODEM_V17 = (1 << 0),
56         /*! V.27ter */
57         AST_FAX_MODEM_V27TER = (1 << 1),
58         /*! V.29 */
59         AST_FAX_MODEM_V29 = (1 << 2),
60         /*! V.34 */
61         AST_FAX_MODEM_V34 = (1 << 3),
62 };
63
64 /*! \brief current state of a fax session */
65 enum ast_fax_state {
66         /*! uninitialized state */
67         AST_FAX_STATE_UNINITIALIZED = 0,
68         /*! initialized state */
69         AST_FAX_STATE_INITIALIZED,
70         /*! fax resources open state */
71         AST_FAX_STATE_OPEN,
72         /*! fax session in progress */
73         AST_FAX_STATE_ACTIVE,
74         /*! fax session complete */
75         AST_FAX_STATE_COMPLETE,
76         /*! reserved state */
77         AST_FAX_STATE_RESERVED,
78         /*! inactive state */
79         AST_FAX_STATE_INACTIVE,
80 };
81
82 /*! \brief fax session options */
83 enum ast_fax_optflag {
84         /*! false/disable configuration override */
85         AST_FAX_OPTFLAG_FALSE = 0,
86         /*! true/enable configuration override */
87         AST_FAX_OPTFLAG_TRUE,
88         /*! use the configured default */
89         AST_FAX_OPTFLAG_DEFAULT,
90 };
91
92 struct ast_fax_t38_parameters {
93         unsigned int version;                                   /*!< Supported T.38 version */
94         unsigned int max_ifp;                                   /*!< Maximum IFP size supported */
95         enum ast_control_t38_rate rate;                         /*!< Maximum fax rate supported */
96         enum ast_control_t38_rate_management rate_management;   /*!< Rate management setting */
97         unsigned int fill_bit_removal:1;                        /*!< Set if fill bit removal can be used */
98         unsigned int transcoding_mmr:1;                         /*!< Set if MMR transcoding can be used */
99         unsigned int transcoding_jbig:1;                        /*!< Set if JBIG transcoding can be used */
100 };
101
102 struct ast_fax_document {
103         AST_LIST_ENTRY(ast_fax_document) next;
104         char filename[0];
105 };
106
107 AST_LIST_HEAD_NOLOCK(ast_fax_documents, ast_fax_document);
108
109 /*! \brief The data communicated between the high level applications and the generic fax function */
110 struct ast_fax_session_details {
111         /*! fax session capability requirements.  The caps field is used to select
112          * the proper fax technology module before the session starts */
113         enum ast_fax_capabilities caps;
114         /*! modem requirement for the session */
115         enum ast_fax_modems modems;
116         /*! session id */
117         unsigned int id;
118         /*! document(s) to be sent/received */
119         struct ast_fax_documents documents;
120         AST_DECLARE_STRING_FIELDS(
121                 /*! resolution negotiated during the fax session.  This is stored in the
122                  * FAXRESOLUTION channel variable when the fax session completes */
123                 AST_STRING_FIELD(resolution);
124                 /*! transfer rate negotiated during the fax session.  This is stored in the
125                  * FAXBITRATE channel variable when the fax session completes */
126                 AST_STRING_FIELD(transfer_rate);
127                 /*! local station identification.  This is set from the LOCALSTATIONID
128                  * channel variable before the fax session starts */
129                 AST_STRING_FIELD(localstationid);
130                 /*! remote station identification.  This is stored in the REMOTESTATIONID
131                  * channel variable after the fax session completes */
132                 AST_STRING_FIELD(remotestationid);
133                 /*! headerinfo variable is set from the LOCALHEADERINFO channel variable
134                  * before the fax session starts */
135                 AST_STRING_FIELD(headerinfo);
136                 /*! the result of the fax session */
137                 AST_STRING_FIELD(result);
138                 /*! a more descriptive result string of the fax session */
139                 AST_STRING_FIELD(resultstr);
140                 /*! the error reason of the fax session */
141                 AST_STRING_FIELD(error);
142         );
143         /*! the number of pages sent/received during a fax session */
144         unsigned int pages_transferred;
145         /*! session details flags for options */
146         union {
147                 /*! dontuse dummy variable - do not ever use */ 
148                 uint32_t dontuse;
149                 struct {
150                         /*! flag to send debug manager events */
151                         uint32_t debug:2;
152                         /*! flag indicating the use of Error Correction Mode (ECM) */
153                         uint32_t ecm:1;
154                         /*! flag indicating the sending of status manager events */
155                         uint32_t statusevents:2;
156                         /*! allow audio mode FAX on T.38-capable channels */
157                         uint32_t allow_audio:2;
158                         /*! indicating the session switched to T38 */
159                         uint32_t switch_to_t38:1;
160                         /*! flag indicating whether CED should be sent (for receive mode) */
161                         uint32_t send_ced:1;
162                         /*! flag indicating whether CNG should be sent (for send mode) */
163                         uint32_t send_cng:1;
164                         /*! send a T.38 reinvite */
165                         uint32_t request_t38:1;
166                         /*! a V.21 preamble was detected */
167                         uint32_t v21_detected:1;
168                 };
169         } option;
170         /*! override the minimum transmission rate with a channel variable */
171         unsigned int minrate;
172         /*! override the maximum transmission rate with a channel varialbe */
173         unsigned int maxrate;
174         /*! our T.38 session parameters, if any */
175         struct ast_fax_t38_parameters our_t38_parameters;
176         /*! the other endpoint's T.38 session parameters, if any */
177         struct ast_fax_t38_parameters their_t38_parameters;
178         /*! T.38 negotiation in ms */
179         unsigned int t38timeout;
180         /*! the id of the t.38 gateway framehook for this channel */
181         int gateway_id;
182         /*! The timeout for this gateway in ms */
183         int gateway_timeout;
184         /*! the id of the faxdetect framehook for this channel */
185         int faxdetect_id;
186         /*! The timeout for this fax detect in ms */
187         int faxdetect_timeout;
188         /*! flags used for fax detection */
189         int faxdetect_flags;
190         /*! Non-zero if T.38 is negotiated */
191         int is_t38_negotiated;
192 };
193
194 struct ast_fax_tech;
195 struct ast_fax_debug_info;
196 struct ast_fax_tech_token;
197
198 /*! \brief The data required to handle a fax session */
199 struct ast_fax_session {
200         /*! session id */
201         unsigned int id;
202         /*! session file descriptor */
203         int fd;
204         /*! fax session details structure */
205         struct ast_fax_session_details *details;
206         /*! fax frames received */
207         unsigned long frames_received;
208         /*! fax frames sent */
209         unsigned long frames_sent;
210         /*! the fax technology callbacks */
211         const struct ast_fax_tech *tech;
212         /*! private implementation pointer */
213         void *tech_pvt;
214         /*! fax state */
215         enum ast_fax_state state;
216         /*! name of the Asterisk channel using the fax session */
217         char *channame;
218         /*! unique ID of the Asterisk channel using the fax session */
219         char *chan_uniqueid;
220         /*! Asterisk channel using the fax session */
221         struct ast_channel *chan;
222         /*! fax debugging structure */
223         struct ast_fax_debug_info *debug_info;
224         /*! used to take variable-sized frames in and output frames of an expected size to the fax stack */
225         struct ast_smoother *smoother;
226 };
227
228 /* if this overlaps with any AST_FRFLAG_* values, problems will occur */
229 #define AST_FAX_FRFLAG_GATEWAY (1 << 13)
230
231 /*! \brief used to register a FAX technology module with res_fax */
232 struct ast_fax_tech {
233         /*! the type of fax session supported with this ast_fax_tech structure */
234         const char * const type;
235         /*! a short description of the fax technology */
236         const char * const description;
237         /*! version string of the technology module */
238         const char * const version;
239         /*! the ast_fax_capabilities supported by the fax technology */
240         const enum ast_fax_capabilities caps;
241         /*! module information for the fax technology */
242         struct ast_module *module;
243         /*! reserves a session for future use; returns a token */
244         struct ast_fax_tech_token *(* const reserve_session)(struct ast_fax_session *);
245         /*! releases an unused session token */
246         void (* const release_token)(struct ast_fax_tech_token *);
247         /*! creates a new fax session, optionally using a previously-reserved token */
248         void *(* const new_session)(struct ast_fax_session *, struct ast_fax_tech_token *);
249         /*! destroys an existing fax session */
250         void (* const destroy_session)(struct ast_fax_session *);
251         /*! sends an Asterisk frame to res_fax */
252         struct ast_frame *(* const read)(struct ast_fax_session *);
253         /*! writes an Asterisk frame to the fax session */
254         int (* const write)(struct ast_fax_session *, const struct ast_frame *);
255         /*! starts the fax session */
256         int (* const start_session)(struct ast_fax_session *);
257         /*! cancels a fax session */
258         int (* const cancel_session)(struct ast_fax_session *);
259         /*! initiates the generation of silence to the fax session */
260         int (* const generate_silence)(struct ast_fax_session *);
261         /*! switches an existing dual-mode session from audio to T.38 */
262         int (* const switch_to_t38)(struct ast_fax_session *);
263         /*! displays capabilities of the fax technology */
264         char * (* const cli_show_capabilities)(int);
265         /*! displays details about the fax session */
266         char * (* const cli_show_session)(struct ast_fax_session *, int);
267         /*! Generates manager event detailing the fax session */
268         void (* const manager_fax_session)(struct mansession *,
269                 const char *, struct ast_fax_session *);
270         /*! displays statistics from the fax technology module */
271         char * (* const cli_show_stats)(int);
272         /*! displays settings from the fax technology module */
273         char * (* const cli_show_settings)(int);
274 };
275
276 /*! \brief register a fax technology */
277 int ast_fax_tech_register(struct ast_fax_tech *tech);
278
279 /*! \brief unregister a fax technology */
280 void ast_fax_tech_unregister(struct ast_fax_tech *tech);
281
282 /*! \brief get the minimum supported fax rate */
283 unsigned int ast_fax_minrate(void);
284
285 /*! \brief get the maxiumum supported fax rate */
286 unsigned int ast_fax_maxrate(void);
287
288 /*! \brief convert an ast_fax_state to a string */
289 const char *ast_fax_state_to_str(enum ast_fax_state state);
290
291 /*! \brief get string representation of a FAX session's operation */
292 const char *ast_fax_session_operation_str(struct ast_fax_session *s);
293
294 /*!
295  * \brief Log message at FAX or recommended level
296  *
297  * The first four parameters can be represented with Asterisk's
298  * LOG_* levels. In other words, this function may be called
299  * like
300  *
301  * ast_fax_log(LOG_DEBUG, msg);
302  */
303 void ast_fax_log(int level, const char *file, const int line, const char *function, const char *msg);
304
305 #endif