diff --git a/configs/res_fax.conf.sample b/configs/res_fax.conf.sample new file mode 100644 index 0000000000..251a9ca2a6 --- /dev/null +++ b/configs/res_fax.conf.sample @@ -0,0 +1,24 @@ +; Generic Fax Application configuration + +[general] +; Maximum Transmission Rate +; Possible values are { 2400 | 4800 | 7200 | 9600 | 12000 | 14400 } +; Set this value to the maximum desired transfer rate. Default: 14400 +maxrate=14400 + +; Minimum Transmission Rate +; Possible values are { 2400 | 4800 | 7200 | 9600 | 12000 | 14400 } +; Set this value to the minimum desired transfer rate. Default: 2400 +minrate=2400 + +; Send Progress/Status events to manager session +; Manager events with 'call' class permissions will receive events indicating the +; steps to initiate a fax session. Fax completion events are always sent to manager +; sessions with 'call' class permissions, regardless of the value of this option. +; Default: no +statusevents=yes + +; modem capabilities +; Possible values are { v17 | v27 | v29 } +; Set this value to modify the default modem options. Default: v17,v27,v29 +modems=v17,v27,v29 diff --git a/include/asterisk/res_fax.h b/include/asterisk/res_fax.h new file mode 100644 index 0000000000..414ba38e30 --- /dev/null +++ b/include/asterisk/res_fax.h @@ -0,0 +1,249 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2008-2009, Digium, Inc. + * + * Dwayne M. Hubbard <dhubbard@digium.com> + * Kevin P. Fleming <kpfleming@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +#ifndef _ASTERISK_RES_FAX_H +#define _ASTERISK_RES_FAX_H + +#include <asterisk.h> +#include <asterisk/lock.h> +#include <asterisk/linkedlists.h> +#include <asterisk/module.h> +#include <asterisk/utils.h> +#include <asterisk/options.h> +#include <asterisk/frame.h> +#include <asterisk/cli.h> +#include <asterisk/stringfields.h> + +/*! \brief capabilities for res_fax to locate a fax technology module */ +enum ast_fax_capabilities { + /*! SendFax is supported */ + AST_FAX_TECH_SEND = (1 << 0), + /*! ReceiveFax is supported */ + AST_FAX_TECH_RECEIVE = (1 << 1), + /*! Audio FAX session supported */ + AST_FAX_TECH_AUDIO = (1 << 2), + /*! T.38 FAX session supported */ + AST_FAX_TECH_T38 = (1 << 3), +}; + +/*! \brief fax modem capabilities */ +enum ast_fax_modems { + /*! V.17 */ + AST_FAX_MODEM_V17 = (1 << 0), + /*! V.27 */ + AST_FAX_MODEM_V27 = (1 << 1), + /*! V.29 */ + AST_FAX_MODEM_V29 = (1 << 2), + /*! V.34 */ + AST_FAX_MODEM_V34 = (1 << 3), +}; + +/*! \brief current state of a fax session */ +enum ast_fax_state { + /*! uninitialized state */ + AST_FAX_STATE_UNINITIALIZED = 0, + /*! initialized state */ + AST_FAX_STATE_INITIALIZED, + /*! fax resources open state */ + AST_FAX_STATE_OPEN, + /*! fax session in progress */ + AST_FAX_STATE_ACTIVE, + /*! fax session complete */ + AST_FAX_STATE_COMPLETE, +}; + +/*! \brief fax session options */ +enum ast_fax_optflag { + /*! false/disable configuration override */ + AST_FAX_OPTFLAG_FALSE = 0, + /*! true/enable configuration override */ + AST_FAX_OPTFLAG_TRUE, + /*! use the configured default */ + AST_FAX_OPTFLAG_DEFAULT, +}; + +struct ast_fax_t38_parameters { + unsigned int version; /*!< Supported T.38 version */ + unsigned int max_ifp; /*!< Maximum IFP size supported */ + enum ast_control_t38_rate rate; /*!< Maximum fax rate supported */ + enum ast_control_t38_rate_management rate_management; /*!< Rate management setting */ + unsigned int fill_bit_removal:1; /*!< Set if fill bit removal can be used */ + unsigned int transcoding_mmr:1; /*!< Set if MMR transcoding can be used */ + unsigned int transcoding_jbig:1; /*!< Set if JBIG transcoding can be used */ +}; + +struct ast_fax_document { + AST_LIST_ENTRY(ast_fax_document) next; + char filename[0]; +}; + +AST_LIST_HEAD_NOLOCK(ast_fax_documents, ast_fax_document); + +/*! \brief The data communicated between the high level applications and the generic fax function */ +struct ast_fax_session_details { + /*! fax session capability requirements. The caps field is used to select + * the proper fax technology module before the session starts */ + enum ast_fax_capabilities caps; + /*! modem requirement for the session */ + enum ast_fax_modems modems; + /*! session id */ + unsigned int id; + /*! document(s) to be sent/received */ + struct ast_fax_documents documents; + AST_DECLARE_STRING_FIELDS( + /*! resolution negotiated during the fax session. This is stored in the + * FAXRESOLUTION channel variable when the fax session completes */ + AST_STRING_FIELD(resolution); + /*! transfer rate negotiated during the fax session. This is stored in the + * FAXBITRATE channel variable when the fax session completes */ + AST_STRING_FIELD(transfer_rate); + /*! local station identification. This is set from the LOCALSTATIONID + * channel variable before the fax session starts */ + AST_STRING_FIELD(localstationid); + /*! remote station identification. This is stored in the REMOTESTATIONID + * channel variable after the fax session completes */ + AST_STRING_FIELD(remotestationid); + /*! headerinfo variable is set from the LOCALHEADERINFO channel variable + * before the fax session starts */ + AST_STRING_FIELD(headerinfo); + /*! the result of the fax session */ + AST_STRING_FIELD(result); + /*! a more descriptive result string of the fax session */ + AST_STRING_FIELD(resultstr); + /*! the error reason of the fax session */ + AST_STRING_FIELD(error); + ); + /*! the number of pages sent/received during a fax session */ + unsigned int pages_transferred; + /*! session details flags for options */ + union { + /*! dontuse dummy variable - do not ever use */ + uint32_t dontuse; + struct { + /*! flag to send debug manager events */ + uint32_t debug:2; + /*! flag indicating the use of Error Correction Mode (ECM) */ + uint32_t ecm:2; + /*! flag indicating the sending of status manager events */ + uint32_t statusevents:2; + /*! allow audio mode FAX on T.38-capable channels */ + uint32_t allow_audio:2; + /*! indicating the session switched to T38 */ + uint32_t switch_to_t38:1; + }; + } option; + /*! override the minimum transmission rate with a channel variable */ + unsigned int minrate; + /*! override the maximum transmission rate with a channel varialbe */ + unsigned int maxrate; + /*! our T.38 session parameters, if any */ + struct ast_fax_t38_parameters our_t38_parameters; + /*! the other endpoint's T.38 session parameters, if any */ + struct ast_fax_t38_parameters their_t38_parameters; +}; + +struct ast_fax_tech; +struct ast_fax_debug_info; + +/*! \brief The data required to handle a fax session */ +struct ast_fax_session { + /*! session id */ + unsigned int id; + /*! session file descriptor */ + int fd; + /*! fax session details structure */ + struct ast_fax_session_details *details; + /*! fax frames received */ + unsigned long frames_received; + /*! fax frames sent */ + unsigned long frames_sent; + /*! the fax technology callbacks */ + const struct ast_fax_tech *tech; + /*! private implementation pointer */ + void *tech_pvt; + /*! fax state */ + enum ast_fax_state state; + /*! name of the Asterisk channel using the fax session */ + char *channame; + /*! Asterisk channel using the fax session */ + struct ast_channel *chan; + /*! fax debugging structure */ + struct ast_fax_debug_info *debug_info; + /*! used to take variable-sized frames in and output frames of an expected size to the fax stack */ + struct ast_smoother *smoother; +}; + +struct ast_fax_tech_token; + +/*! \brief used to register a FAX technology module with res_fax */ +struct ast_fax_tech { + /*! the type of fax session supported with this ast_fax_tech structure */ + const char * const type; + /*! a short description of the fax technology */ + const char * const description; + /*! version string of the technology module */ + const char * const version; + /*! the ast_fax_capabilities supported by the fax technology */ + const enum ast_fax_capabilities caps; + /*! module information for the fax technology */ + struct ast_module *module; + /*! reserves a session for future use; returns a token */ + struct ast_fax_tech_token *(* const reserve_session)(struct ast_fax_session *); + /*! releases an unused session token */ + void (* const release_token)(struct ast_fax_tech_token *); + /*! creates a new fax session, optionally using a previously-reserved token */ + void *(* const new_session)(struct ast_fax_session *, struct ast_fax_tech_token *); + /*! destroys an existing fax session */ + void (* const destroy_session)(struct ast_fax_session *); + /*! sends an Asterisk frame to res_fax */ + struct ast_frame *(* const read)(struct ast_fax_session *); + /*! writes an Asterisk frame to the fax session */ + int (* const write)(struct ast_fax_session *, const struct ast_frame *); + /*! starts the fax session */ + int (* const start_session)(struct ast_fax_session *); + /*! cancels a fax session */ + int (* const cancel_session)(struct ast_fax_session *); + /*! initiates the generation of silence to the fax session */ + int (* const generate_silence)(struct ast_fax_session *); + /*! switches an existing dual-mode session from audio to T.38 */ + int (* const switch_to_t38)(struct ast_fax_session *); + /*! displays capabilities of the fax technology */ + char * (* const cli_show_capabilities)(int); + /*! displays details about the fax session */ + char * (* const cli_show_session)(struct ast_fax_session *, int); + /*! displays statistics from the fax technology module */ + char * (* const cli_show_stats)(int); +}; + +/*! \brief register a fax technology */ +int ast_fax_tech_register(struct ast_fax_tech *tech); + +/*! \brief unregister a fax technology */ +void ast_fax_tech_unregister(struct ast_fax_tech *tech); + +/*! \brief get the minimum supported fax rate */ +unsigned int ast_fax_minrate(void); + +/*! \brief get the maxiumum supported fax rate */ +unsigned int ast_fax_maxrate(void); + +/*! \brief convert an ast_fax_state to a string */ +const char *ast_fax_state_to_str(enum ast_fax_state state); + +#endif