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