Mon Aug 31 12:30:11 2015

Asterisk developer's documentation


res_fax.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2008-2009, Digium, Inc.
00005  *
00006  * Dwayne M. Hubbard <dhubbard@digium.com>
00007  * Kevin P. Fleming <kpfleming@digium.com>
00008  *
00009  * See http://www.asterisk.org for more information about
00010  * the Asterisk project. Please do not directly contact
00011  * any of the maintainers of this project for assistance;
00012  * the project provides a web site, mailing lists and IRC
00013  * channels for your use.
00014  *
00015  * This program is free software, distributed under the terms of
00016  * the GNU General Public License Version 2. See the LICENSE file
00017  * at the top of the source tree.
00018  */
00019 
00020 #ifndef _ASTERISK_RES_FAX_H
00021 #define _ASTERISK_RES_FAX_H
00022 
00023 #include <asterisk.h>
00024 #include <asterisk/lock.h>
00025 #include <asterisk/linkedlists.h>
00026 #include <asterisk/module.h>
00027 #include <asterisk/utils.h>
00028 #include <asterisk/options.h>
00029 #include <asterisk/frame.h>
00030 #include <asterisk/cli.h>
00031 #include <asterisk/stringfields.h>
00032 
00033 /*! \brief capabilities for res_fax to locate a fax technology module */
00034 enum ast_fax_capabilities {
00035    /*! SendFax is supported */
00036    AST_FAX_TECH_SEND      = (1 << 0),
00037    /*! ReceiveFax is supported */
00038    AST_FAX_TECH_RECEIVE   = (1 << 1),
00039    /*! Audio FAX session supported */
00040    AST_FAX_TECH_AUDIO     = (1 << 2),
00041    /*! T.38 FAX session supported */
00042    AST_FAX_TECH_T38       = (1 << 3),
00043    /*! sending mulitple documents supported */
00044    AST_FAX_TECH_MULTI_DOC = (1 << 4),
00045 };
00046 
00047 /*! \brief fax modem capabilities */
00048 enum ast_fax_modems {
00049    /*! V.17 */
00050    AST_FAX_MODEM_V17 = (1 << 0),
00051    /*! V.27 */
00052    AST_FAX_MODEM_V27 = (1 << 1),
00053    /*! V.29 */
00054    AST_FAX_MODEM_V29 = (1 << 2),
00055    /*! V.34 */
00056    AST_FAX_MODEM_V34 = (1 << 3),
00057 };
00058 
00059 /*! \brief current state of a fax session */
00060 enum ast_fax_state {
00061    /*! uninitialized state */
00062    AST_FAX_STATE_UNINITIALIZED = 0,
00063    /*! initialized state */
00064    AST_FAX_STATE_INITIALIZED,
00065    /*! fax resources open state */
00066    AST_FAX_STATE_OPEN,
00067    /*! fax session in progress */
00068    AST_FAX_STATE_ACTIVE,
00069    /*! fax session complete */
00070    AST_FAX_STATE_COMPLETE,
00071    /*! reserved state */
00072    AST_FAX_STATE_RESERVED,
00073    /*! inactive state */
00074    AST_FAX_STATE_INACTIVE,
00075 };
00076 
00077 /*! \brief fax session options */
00078 enum ast_fax_optflag {
00079    /*! false/disable configuration override */
00080    AST_FAX_OPTFLAG_FALSE = 0,
00081    /*! true/enable configuration override */
00082    AST_FAX_OPTFLAG_TRUE,
00083    /*! use the configured default */
00084    AST_FAX_OPTFLAG_DEFAULT,
00085 };
00086 
00087 struct ast_fax_t38_parameters {
00088    unsigned int version;               /*!< Supported T.38 version */
00089    unsigned int max_ifp;               /*!< Maximum IFP size supported */
00090    enum ast_control_t38_rate rate;           /*!< Maximum fax rate supported */
00091    enum ast_control_t38_rate_management rate_management; /*!< Rate management setting */
00092    unsigned int fill_bit_removal:1;       /*!< Set if fill bit removal can be used */
00093    unsigned int transcoding_mmr:1;           /*!< Set if MMR transcoding can be used */
00094    unsigned int transcoding_jbig:1;       /*!< Set if JBIG transcoding can be used */
00095 };
00096 
00097 struct ast_fax_document {
00098    AST_LIST_ENTRY(ast_fax_document) next;
00099    char filename[0];
00100 };
00101 
00102 AST_LIST_HEAD_NOLOCK(ast_fax_documents, ast_fax_document);
00103 
00104 /*! \brief The data communicated between the high level applications and the generic fax function */
00105 struct ast_fax_session_details {
00106    /*! fax session capability requirements.  The caps field is used to select
00107     * the proper fax technology module before the session starts */
00108    enum ast_fax_capabilities caps;
00109    /*! modem requirement for the session */
00110    enum ast_fax_modems modems;
00111    /*! session id */
00112    unsigned int id;
00113    /*! document(s) to be sent/received */
00114    struct ast_fax_documents documents;
00115    AST_DECLARE_STRING_FIELDS(
00116       /*! resolution negotiated during the fax session.  This is stored in the
00117        * FAXRESOLUTION channel variable when the fax session completes */
00118       AST_STRING_FIELD(resolution);
00119       /*! transfer rate negotiated during the fax session.  This is stored in the
00120        * FAXBITRATE channel variable when the fax session completes */
00121       AST_STRING_FIELD(transfer_rate);
00122       /*! local station identification.  This is set from the LOCALSTATIONID
00123        * channel variable before the fax session starts */
00124       AST_STRING_FIELD(localstationid);
00125       /*! remote station identification.  This is stored in the REMOTESTATIONID
00126        * channel variable after the fax session completes */
00127       AST_STRING_FIELD(remotestationid);
00128       /*! headerinfo variable is set from the LOCALHEADERINFO channel variable
00129        * before the fax session starts */
00130       AST_STRING_FIELD(headerinfo);
00131       /*! the result of the fax session */
00132       AST_STRING_FIELD(result);
00133       /*! a more descriptive result string of the fax session */
00134       AST_STRING_FIELD(resultstr);
00135       /*! the error reason of the fax session */
00136       AST_STRING_FIELD(error);
00137    );
00138    /*! the number of pages sent/received during a fax session */
00139    unsigned int pages_transferred;
00140    /*! session details flags for options */
00141    union {
00142       /*! dontuse dummy variable - do not ever use */ 
00143       uint32_t dontuse;
00144       struct {
00145          /*! flag to send debug manager events */
00146          uint32_t debug:2;
00147          /*! flag indicating the use of Error Correction Mode (ECM) */
00148          uint32_t ecm:1;
00149          /*! flag indicating the sending of status manager events */
00150          uint32_t statusevents:2;
00151          /*! allow audio mode FAX on T.38-capable channels */
00152          uint32_t allow_audio:2;
00153          /*! indicating the session switched to T38 */
00154          uint32_t switch_to_t38:1;
00155          /*! flag indicating whether CED should be sent (for receive mode) */
00156          uint32_t send_ced:1;
00157          /*! flag indicating whether CNG should be sent (for send mode) */
00158          uint32_t send_cng:1;
00159          /*! send a T.38 reinvite */
00160          uint32_t request_t38:1;
00161       };
00162    } option;
00163    /*! override the minimum transmission rate with a channel variable */
00164    unsigned int minrate;
00165    /*! override the maximum transmission rate with a channel varialbe */
00166    unsigned int maxrate;
00167    /*! our T.38 session parameters, if any */
00168    struct ast_fax_t38_parameters our_t38_parameters;
00169    /*! the other endpoint's T.38 session parameters, if any */
00170    struct ast_fax_t38_parameters their_t38_parameters;
00171 };
00172 
00173 struct ast_fax_tech;
00174 struct ast_fax_debug_info;
00175 struct ast_fax_tech_token;
00176 
00177 /*! \brief The data required to handle a fax session */
00178 struct ast_fax_session {
00179    /*! session id */
00180    unsigned int id;
00181    /*! session file descriptor */
00182    int fd;
00183    /*! fax session details structure */
00184    struct ast_fax_session_details *details;
00185    /*! fax frames received */
00186    unsigned long frames_received;
00187    /*! fax frames sent */
00188    unsigned long frames_sent;
00189    /*! the fax technology callbacks */
00190    const struct ast_fax_tech *tech;
00191    /*! private implementation pointer */
00192    void *tech_pvt;
00193    /*! fax state */
00194    enum ast_fax_state state;
00195    /*! name of the Asterisk channel using the fax session */
00196    char *channame;
00197    /*! unique ID of the Asterisk channel using the fax session */
00198    char *chan_uniqueid;
00199    /*! Asterisk channel using the fax session */
00200    struct ast_channel *chan;
00201    /*! fax debugging structure */
00202    struct ast_fax_debug_info *debug_info;
00203    /*! used to take variable-sized frames in and output frames of an expected size to the fax stack */
00204    struct ast_smoother *smoother;
00205 };
00206 
00207 /*! \brief used to register a FAX technology module with res_fax */
00208 struct ast_fax_tech {
00209    /*! the type of fax session supported with this ast_fax_tech structure */
00210    const char * const type;
00211    /*! a short description of the fax technology */
00212    const char * const description;
00213    /*! version string of the technology module */
00214    const char * const version;
00215    /*! the ast_fax_capabilities supported by the fax technology */
00216    const enum ast_fax_capabilities caps;
00217    /*! module information for the fax technology */
00218    struct ast_module *module;
00219    /*! reserves a session for future use; returns a token */
00220    struct ast_fax_tech_token *(* const reserve_session)(struct ast_fax_session *);
00221    /*! releases an unused session token */
00222    void (* const release_token)(struct ast_fax_tech_token *);
00223    /*! creates a new fax session, optionally using a previously-reserved token */
00224    void *(* const new_session)(struct ast_fax_session *, struct ast_fax_tech_token *);
00225    /*! destroys an existing fax session */
00226    void (* const destroy_session)(struct ast_fax_session *);
00227    /*! sends an Asterisk frame to res_fax */
00228    struct ast_frame *(* const read)(struct ast_fax_session *);
00229    /*! writes an Asterisk frame to the fax session */
00230    int (* const write)(struct ast_fax_session *, const struct ast_frame *);
00231    /*! starts the fax session */
00232    int (* const start_session)(struct ast_fax_session *);
00233    /*! cancels a fax session */
00234    int (* const cancel_session)(struct ast_fax_session *);
00235    /*! initiates the generation of silence to the fax session */
00236    int (* const generate_silence)(struct ast_fax_session *);
00237    /*! switches an existing dual-mode session from audio to T.38 */
00238    int (* const switch_to_t38)(struct ast_fax_session *);
00239    /*! displays capabilities of the fax technology */
00240    char * (* const cli_show_capabilities)(int);
00241    /*! displays details about the fax session */
00242    char * (* const cli_show_session)(struct ast_fax_session *, int);
00243    /*! displays statistics from the fax technology module */
00244    char * (* const cli_show_stats)(int);
00245    /*! displays settings from the fax technology module */
00246    char * (* const cli_show_settings)(int);
00247 };
00248 
00249 /*! \brief register a fax technology */
00250 int ast_fax_tech_register(struct ast_fax_tech *tech);
00251 
00252 /*! \brief unregister a fax technology */
00253 void ast_fax_tech_unregister(struct ast_fax_tech *tech);
00254 
00255 /*! \brief get the minimum supported fax rate */
00256 unsigned int ast_fax_minrate(void);
00257 
00258 /*! \brief get the maxiumum supported fax rate */
00259 unsigned int ast_fax_maxrate(void);
00260 
00261 /*! \brief convert an ast_fax_state to a string */
00262 const char *ast_fax_state_to_str(enum ast_fax_state state);
00263 
00264 /*!
00265  * \brief Log message at FAX or recommended level
00266  *
00267  * The first four parameters can be represented with Asterisk's
00268  * LOG_* levels. In other words, this function may be called
00269  * like
00270  *
00271  * ast_fax_log(LOG_DEBUG, msg);
00272  */
00273 void ast_fax_log(int level, const char *file, const int line, const char *function, const char *msg);
00274 
00275 #endif

Generated on 31 Aug 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1