Asterisk - The Open Source Telephony Project  21.4.1
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 
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 
104  char filename[0];
105 };
106 
108 
109 /*! \brief The data communicated between the high level applications and the generic fax function */
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 */
121  /*! resolution negotiated during the fax session. This is stored in the
122  * FAXRESOLUTION channel variable when the fax session completes */
124  /*! transfer rate negotiated during the fax session. This is stored in the
125  * FAXBITRATE channel variable when the fax session completes */
127  /*! local station identification. This is set from the LOCALSTATIONID
128  * channel variable before the fax session starts */
130  /*! remote station identification. This is stored in the REMOTESTATIONID
131  * channel variable after the fax session completes */
133  /*! headerinfo variable is set from the LOCALHEADERINFO channel variable
134  * before the fax session starts */
136  /*! the result of the fax session */
138  /*! a more descriptive result string of the fax session */
140  /*! the error reason of the fax session */
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 */
176  /*! the other endpoint's T.38 session parameters, if any */
178  /*! T.38 negotiation in ms */
179  unsigned int t38timeout;
180  /*! the id of the t.38 gateway framehook for this channel */
182  /*! The timeout for this gateway in ms */
184  /*! the id of the faxdetect framehook for this channel */
186  /*! The timeout for this fax detect in ms */
188  /*! flags used for fax detection */
190  /*! Non-zero if T.38 is negotiated */
192  /*! Upon v21 detection the gateway sends negotiation requests to both
193  T.38 endpoints, and do not wait on the "other" side to initiate */
195 };
196 
197 struct ast_fax_tech;
198 struct ast_fax_debug_info;
199 struct ast_fax_tech_token;
200 
201 /*! \brief The data required to handle a fax session */
203  /*! session id */
204  unsigned int id;
205  /*! session file descriptor */
206  int fd;
207  /*! fax session details structure */
209  /*! fax frames received */
210  unsigned long frames_received;
211  /*! fax frames sent */
212  unsigned long frames_sent;
213  /*! the fax technology callbacks */
214  const struct ast_fax_tech *tech;
215  /*! private implementation pointer */
216  void *tech_pvt;
217  /*! fax state */
218  enum ast_fax_state state;
219  /*! name of the Asterisk channel using the fax session */
220  char *channame;
221  /*! unique ID of the Asterisk channel using the fax session */
223  /*! Asterisk channel using the fax session */
224  struct ast_channel *chan;
225  /*! fax debugging structure */
227  /*! used to take variable-sized frames in and output frames of an expected size to the fax stack */
229 };
230 
231 /* if this overlaps with any AST_FRFLAG_* values, problems will occur */
232 #define AST_FAX_FRFLAG_GATEWAY (1 << 13)
233 
234 /*! \brief used to register a FAX technology module with res_fax */
235 struct ast_fax_tech {
236  /*! the type of fax session supported with this ast_fax_tech structure */
237  const char * const type;
238  /*! a short description of the fax technology */
239  const char * const description;
240  /*! version string of the technology module */
241  const char * const version;
242  /*! the ast_fax_capabilities supported by the fax technology */
243  const enum ast_fax_capabilities caps;
244  /*! module information for the fax technology */
246  /*! reserves a session for future use; returns a token */
247  struct ast_fax_tech_token *(* const reserve_session)(struct ast_fax_session *);
248  /*! releases an unused session token */
249  void (* const release_token)(struct ast_fax_tech_token *);
250  /*! creates a new fax session, optionally using a previously-reserved token */
251  void *(* const new_session)(struct ast_fax_session *, struct ast_fax_tech_token *);
252  /*! destroys an existing fax session */
253  void (* const destroy_session)(struct ast_fax_session *);
254  /*! sends an Asterisk frame to res_fax */
255  struct ast_frame *(* const read)(struct ast_fax_session *);
256  /*! writes an Asterisk frame to the fax session */
257  int (* const write)(struct ast_fax_session *, const struct ast_frame *);
258  /*! starts the fax session */
259  int (* const start_session)(struct ast_fax_session *);
260  /*! cancels a fax session */
261  int (* const cancel_session)(struct ast_fax_session *);
262  /*! initiates the generation of silence to the fax session */
263  int (* const generate_silence)(struct ast_fax_session *);
264  /*! switches an existing dual-mode session from audio to T.38 */
265  int (* const switch_to_t38)(struct ast_fax_session *);
266  /*! displays capabilities of the fax technology */
267  char * (* const cli_show_capabilities)(int);
268  /*! displays details about the fax session */
269  char * (* const cli_show_session)(struct ast_fax_session *, int);
270  /*! Generates manager event detailing the fax session */
271  void (* const manager_fax_session)(struct mansession *,
272  const char *, struct ast_fax_session *);
273  /*! displays statistics from the fax technology module */
274  char * (* const cli_show_stats)(int);
275  /*! displays settings from the fax technology module */
276  char * (* const cli_show_settings)(int);
277 };
278 
279 /*! \brief register a fax technology */
281 
282 /*! \brief unregister a fax technology */
284 
285 /*! \brief get the minimum supported fax rate */
286 unsigned int ast_fax_minrate(void);
287 
288 /*! \brief get the maxiumum supported fax rate */
289 unsigned int ast_fax_maxrate(void);
290 
291 /*! \brief convert an ast_fax_state to a string */
292 const char *ast_fax_state_to_str(enum ast_fax_state state);
293 
294 /*! \brief get string representation of a FAX session's operation */
295 const char *ast_fax_session_operation_str(struct ast_fax_session *s);
296 
297 /*!
298  * \brief Log message at FAX or recommended level
299  *
300  * The first four parameters can be represented with Asterisk's
301  * LOG_* levels. In other words, this function may be called
302  * like
303  *
304  * ast_fax_log(LOG_DEBUG, msg);
305  */
306 void ast_fax_log(int level, const char *file, const int line, const char *function, const char *msg);
307 
308 #endif
const ast_string_field result
Definition: res_fax.h:142
int(*const switch_to_t38)(struct ast_fax_session *)
Definition: res_fax.h:265
Main Channel structure associated with a channel.
Asterisk locking-related definitions:
Asterisk main include file. File version handling, generic pbx functions.
const struct ast_fax_tech * tech
Definition: res_fax.h:214
unsigned int t38timeout
Definition: res_fax.h:179
int(*const generate_silence)(struct ast_fax_session *)
Definition: res_fax.h:263
unsigned long frames_sent
Definition: res_fax.h:212
const ast_string_field headerinfo
Definition: res_fax.h:142
unsigned long frames_received
Definition: res_fax.h:210
unsigned int id
Definition: res_fax.h:204
char *(*const cli_show_stats)(int)
Definition: res_fax.h:274
uint32_t switch_to_t38
Definition: res_fax.h:159
const char *const type
Definition: res_fax.h:237
void ast_fax_tech_unregister(struct ast_fax_tech *tech)
unregister a FAX technology module
Definition: res_fax.c:991
const ast_string_field transfer_rate
Definition: res_fax.h:142
void(*const release_token)(struct ast_fax_tech_token *)
Definition: res_fax.h:249
struct ast_smoother * smoother
Definition: res_fax.h:228
int(*const cancel_session)(struct ast_fax_session *)
Definition: res_fax.h:261
enum ast_control_t38_rate rate
Definition: res_fax.h:95
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
const char *const description
Definition: res_fax.h:239
struct ast_channel * chan
Definition: res_fax.h:224
void ast_fax_log(int level, const char *file, const int line, const char *function, const char *msg)
Log message at FAX or recommended level.
Definition: res_fax.c:1035
Utility functions.
unsigned int id
Definition: res_fax.h:117
struct ast_fax_debug_info * debug_info
Definition: res_fax.h:226
struct ast_fax_t38_parameters our_t38_parameters
Definition: res_fax.h:175
enum ast_fax_capabilities caps
Definition: res_fax.h:243
struct ast_fax_tech_token *(*const reserve_session)(struct ast_fax_session *)
Definition: res_fax.h:247
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Asterisk internal frame definitions.
struct ast_fax_session_details * details
Definition: res_fax.h:208
In case you didn't read that giant block of text above the mansession_session struct, the mansession is named this solely to keep the API the same in Asterisk. This structure really represents data that is different from Manager action to Manager action. The mansession_session pointer contained within points to session-specific data.
Definition: manager.c:1785
unsigned int ast_fax_minrate(void)
get the minimum supported fax rate
Definition: res_fax.c:803
A set of macros to manage forward-linked lists.
char * channame
Definition: res_fax.h:220
The data communicated between the high level applications and the generic fax function.
Definition: res_fax.h:110
struct ast_module * module
Definition: res_fax.h:245
const ast_string_field remotestationid
Definition: res_fax.h:142
The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party ...
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:225
unsigned int transcoding_mmr
Definition: res_fax.h:98
unsigned int transcoding_jbig
Definition: res_fax.h:99
void(*const destroy_session)(struct ast_fax_session *)
Definition: res_fax.h:253
unsigned int pages_transferred
Definition: res_fax.h:144
unsigned int max_ifp
Definition: res_fax.h:94
struct ast_fax_documents documents
Definition: res_fax.h:119
used to register a FAX technology module with res_fax
Definition: res_fax.h:235
unsigned int minrate
Definition: res_fax.h:171
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
const char *const version
Definition: res_fax.h:241
void *(*const new_session)(struct ast_fax_session *, struct ast_fax_tech_token *)
Definition: res_fax.h:251
enum ast_fax_modems modems
Definition: res_fax.h:115
void(*const manager_fax_session)(struct mansession *, const char *, struct ast_fax_session *)
Definition: res_fax.h:271
enum ast_fax_state state
Definition: res_fax.h:218
unsigned int ast_fax_maxrate(void)
get the maxiumum supported fax rate
Definition: res_fax.c:795
unsigned int version
Definition: res_fax.h:93
char *(*const cli_show_session)(struct ast_fax_session *, int)
Definition: res_fax.h:269
const char * ast_fax_session_operation_str(struct ast_fax_session *s)
get string representation of a FAX session's operation
Definition: res_fax.c:4253
Standard Command Line Interface.
union ast_fax_session_details::@249 option
struct ast_frame *(*const read)(struct ast_fax_session *)
Definition: res_fax.h:255
The data required to handle a fax session.
Definition: res_fax.h:202
Data structure associated with a single frame of data.
enum ast_control_t38_rate_management rate_management
Definition: res_fax.h:96
enum ast_fax_capabilities caps
Definition: res_fax.h:113
char * chan_uniqueid
Definition: res_fax.h:222
int ast_fax_tech_register(struct ast_fax_tech *tech)
register a FAX technology module
Definition: res_fax.c:973
void * tech_pvt
Definition: res_fax.h:216
Options provided by main asterisk program.
int(*const write)(struct ast_fax_session *, const struct ast_frame *)
Definition: res_fax.h:257
const ast_string_field resultstr
Definition: res_fax.h:142
const ast_string_field localstationid
Definition: res_fax.h:142
unsigned int maxrate
Definition: res_fax.h:173
const char * ast_fax_state_to_str(enum ast_fax_state state)
convert a ast_fax_state to a string
Definition: res_fax.c:1012
const ast_string_field error
Definition: res_fax.h:142
char *(*const cli_show_capabilities)(int)
Definition: res_fax.h:267
int(*const start_session)(struct ast_fax_session *)
Definition: res_fax.h:259
char *(*const cli_show_settings)(int)
Definition: res_fax.h:276
Asterisk module definitions.
unsigned int fill_bit_removal
Definition: res_fax.h:97
struct ast_fax_t38_parameters their_t38_parameters
Definition: res_fax.h:177
const ast_string_field resolution
Definition: res_fax.h:142