Wed Jan 8 2020 09:49:50

Asterisk developer's documentation


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