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