Asterisk - The Open Source Telephony Project  GIT-master-a24979a
res_fax.h
Go to the documentation of this file.
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 */
36  /*! SendFax is supported */
37  AST_FAX_TECH_SEND = (1 << 0),
38  /*! ReceiveFax is supported */
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 */
46  /*! T.38 - T.30 Gateway */
48  /*! V21 detection is supported */
50 };
51 
52 /*! \brief fax modem capabilities */
54  /*! V.17 */
55  AST_FAX_MODEM_V17 = (1 << 0),
56  /*! V.27ter */
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 */
66  /*! uninitialized state */
68  /*! initialized state */
70  /*! fax resources open state */
72  /*! fax session in progress */
74  /*! fax session complete */
76  /*! reserved state */
78  /*! inactive state */
80 };
81 
82 /*! \brief fax session options */
84  /*! false/disable configuration override */
86  /*! true/enable configuration override */
88  /*! use the configured 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 */
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  };
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
Asterisk main include file. File version handling, generic pbx functions.
Standard Command Line Interface.
Asterisk internal frame definitions.
ast_control_t38_rate
ast_control_t38_rate_management
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
Asterisk locking-related definitions:
The AMI - Asterisk Manager Interface - is a TCP protocol created to manage Asterisk with third-party ...
Asterisk module definitions.
Options provided by main asterisk program.
AST_LIST_HEAD_NOLOCK(contactliststruct, contact)
void ast_fax_tech_unregister(struct ast_fax_tech *tech)
unregister a fax technology
Definition: res_fax.c:991
unsigned int ast_fax_minrate(void)
get the minimum supported fax rate
Definition: res_fax.c:803
ast_fax_optflag
fax session options
Definition: res_fax.h:83
@ AST_FAX_OPTFLAG_DEFAULT
Definition: res_fax.h:89
@ AST_FAX_OPTFLAG_FALSE
Definition: res_fax.h:85
@ AST_FAX_OPTFLAG_TRUE
Definition: res_fax.h:87
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
ast_fax_capabilities
capabilities for res_fax to locate a fax technology module
Definition: res_fax.h:35
@ AST_FAX_TECH_T38
Definition: res_fax.h:43
@ AST_FAX_TECH_AUDIO
Definition: res_fax.h:41
@ AST_FAX_TECH_RECEIVE
Definition: res_fax.h:39
@ AST_FAX_TECH_V21_DETECT
Definition: res_fax.h:49
@ AST_FAX_TECH_MULTI_DOC
Definition: res_fax.h:45
@ AST_FAX_TECH_SEND
Definition: res_fax.h:37
@ AST_FAX_TECH_GATEWAY
Definition: res_fax.h:47
const char * ast_fax_state_to_str(enum ast_fax_state state)
convert an ast_fax_state to a string
Definition: res_fax.c:1012
unsigned int ast_fax_maxrate(void)
get the maxiumum supported fax rate
Definition: res_fax.c:795
int ast_fax_tech_register(struct ast_fax_tech *tech)
register a fax technology
Definition: res_fax.c:973
ast_fax_state
current state of a fax session
Definition: res_fax.h:65
@ AST_FAX_STATE_INITIALIZED
Definition: res_fax.h:69
@ AST_FAX_STATE_INACTIVE
Definition: res_fax.h:79
@ AST_FAX_STATE_ACTIVE
Definition: res_fax.h:73
@ AST_FAX_STATE_COMPLETE
Definition: res_fax.h:75
@ AST_FAX_STATE_OPEN
Definition: res_fax.h:71
@ AST_FAX_STATE_UNINITIALIZED
Definition: res_fax.h:67
@ AST_FAX_STATE_RESERVED
Definition: res_fax.h:77
ast_fax_modems
fax modem capabilities
Definition: res_fax.h:53
@ AST_FAX_MODEM_V17
Definition: res_fax.h:55
@ AST_FAX_MODEM_V29
Definition: res_fax.h:59
@ AST_FAX_MODEM_V27TER
Definition: res_fax.h:57
@ AST_FAX_MODEM_V34
Definition: res_fax.h:61
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
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
Main Channel structure associated with a channel.
struct ast_fax_document * next
Definition: res_fax.h:103
char filename[0]
Definition: res_fax.h:104
The data communicated between the high level applications and the generic fax function.
Definition: res_fax.h:110
const ast_string_field localstationid
Definition: res_fax.h:142
struct ast_fax_t38_parameters their_t38_parameters
Definition: res_fax.h:177
struct ast_fax_documents documents
Definition: res_fax.h:119
const ast_string_field result
Definition: res_fax.h:142
enum ast_fax_modems modems
Definition: res_fax.h:115
unsigned int t38timeout
Definition: res_fax.h:179
union ast_fax_session_details::@281 option
const ast_string_field headerinfo
Definition: res_fax.h:142
struct ast_fax_t38_parameters our_t38_parameters
Definition: res_fax.h:175
uint32_t switch_to_t38
Definition: res_fax.h:159
unsigned int minrate
Definition: res_fax.h:171
const ast_string_field resultstr
Definition: res_fax.h:142
unsigned int maxrate
Definition: res_fax.h:173
const ast_string_field error
Definition: res_fax.h:142
unsigned int id
Definition: res_fax.h:117
unsigned int pages_transferred
Definition: res_fax.h:144
const ast_string_field resolution
Definition: res_fax.h:142
const ast_string_field remotestationid
Definition: res_fax.h:142
const ast_string_field transfer_rate
Definition: res_fax.h:142
enum ast_fax_capabilities caps
Definition: res_fax.h:113
The data required to handle a fax session.
Definition: res_fax.h:202
void * tech_pvt
Definition: res_fax.h:216
char * chan_uniqueid
Definition: res_fax.h:222
struct ast_smoother * smoother
Definition: res_fax.h:228
const struct ast_fax_tech * tech
Definition: res_fax.h:214
unsigned long frames_received
Definition: res_fax.h:210
unsigned long frames_sent
Definition: res_fax.h:212
struct ast_channel * chan
Definition: res_fax.h:224
struct ast_fax_debug_info * debug_info
Definition: res_fax.h:226
char * channame
Definition: res_fax.h:220
unsigned int id
Definition: res_fax.h:204
enum ast_fax_state state
Definition: res_fax.h:218
struct ast_fax_session_details * details
Definition: res_fax.h:208
unsigned int transcoding_jbig
Definition: res_fax.h:99
enum ast_control_t38_rate rate
Definition: res_fax.h:95
unsigned int version
Definition: res_fax.h:93
unsigned int max_ifp
Definition: res_fax.h:94
unsigned int transcoding_mmr
Definition: res_fax.h:98
enum ast_control_t38_rate_management rate_management
Definition: res_fax.h:96
unsigned int fill_bit_removal
Definition: res_fax.h:97
used to register a FAX technology module with res_fax
Definition: res_fax.h:235
int(*const start_session)(struct ast_fax_session *)
Definition: res_fax.h:259
void(*const manager_fax_session)(struct mansession *, const char *, struct ast_fax_session *)
Definition: res_fax.h:271
char *(*const cli_show_settings)(int)
Definition: res_fax.h:276
int(*const generate_silence)(struct ast_fax_session *)
Definition: res_fax.h:263
int(*const switch_to_t38)(struct ast_fax_session *)
Definition: res_fax.h:265
char *(*const cli_show_capabilities)(int)
Definition: res_fax.h:267
int(*const write)(struct ast_fax_session *, const struct ast_frame *)
Definition: res_fax.h:257
int(*const cancel_session)(struct ast_fax_session *)
Definition: res_fax.h:261
struct ast_module * module
Definition: res_fax.h:245
const char *const type
Definition: res_fax.h:237
struct ast_frame *(*const read)(struct ast_fax_session *)
Definition: res_fax.h:255
char *(*const cli_show_stats)(int)
Definition: res_fax.h:274
const char *const version
Definition: res_fax.h:241
void(*const release_token)(struct ast_fax_tech_token *)
Definition: res_fax.h:249
struct ast_fax_tech_token *(*const reserve_session)(struct ast_fax_session *)
Definition: res_fax.h:247
const char *const description
Definition: res_fax.h:239
void(*const destroy_session)(struct ast_fax_session *)
Definition: res_fax.h:253
enum ast_fax_capabilities caps
Definition: res_fax.h:243
char *(*const cli_show_session)(struct ast_fax_session *, int)
Definition: res_fax.h:269
void *(*const new_session)(struct ast_fax_session *, struct ast_fax_tech_token *)
Definition: res_fax.h:251
Data structure associated with a single frame of data.
In case you didn't read that giant block of text above the mansession_session struct,...
Definition: manager.c:1632
Utility functions.