res_fax.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2008-2009, Digium, Inc.
 *
 * Dwayne M. Hubbard <[email protected]>
 * Kevin P. Fleming <[email protected]>
 *
 * 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"
#include "asterisk/manager.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),
   /*! sending mulitple documents supported */
   AST_FAX_TECH_MULTI_DOC = (1 << 4),
   /*! T.38 - T.30 Gateway */
   AST_FAX_TECH_GATEWAY = (1 << 5),
   /*! V21 detection is supported */
   AST_FAX_TECH_V21_DETECT = (1 << 6),
};

/*! \brief fax modem capabilities */
enum ast_fax_modems {
   /*! V.17 */
   AST_FAX_MODEM_V17 = (1 << 0),
   /*! V.27ter */
   AST_FAX_MODEM_V27TER = (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,
   /*! reserved state */
   AST_FAX_STATE_RESERVED,
   /*! inactive state */
   AST_FAX_STATE_INACTIVE,
};

/*! \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:1;
         /*! 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;
         /*! flag indicating whether CED should be sent (for receive mode) */
         uint32_t send_ced:1;
         /*! flag indicating whether CNG should be sent (for send mode) */
         uint32_t send_cng:1;
         /*! send a T.38 reinvite */
         uint32_t request_t38:1;
         /*! a V.21 preamble was detected */
         uint32_t v21_detected: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;
   /*! T.38 negotiation in ms */
   unsigned int t38timeout;
   /*! the id of the t.38 gateway framehook for this channel */
   int gateway_id;
   /*! The timeout for this gateway in ms */
   int gateway_timeout;
   /*! the id of the faxdetect framehook for this channel */
   int faxdetect_id;
   /*! The timeout for this fax detect in ms */
   int faxdetect_timeout;
   /*! flags used for fax detection */
   int faxdetect_flags;
   /*! Non-zero if T.38 is negotiated */
   int is_t38_negotiated;
   /*! Upon v21 detection the gateway sends negotiation requests to both
      T.38 endpoints, and do not wait on the "other" side to initiate */
   int negotiate_both;
};

struct ast_fax_tech;
struct ast_fax_debug_info;
struct ast_fax_tech_token;

/*! \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;
   /*! unique ID of the Asterisk channel using the fax session */
   char *chan_uniqueid;
   /*! 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;
};

/* if this overlaps with any AST_FRFLAG_* values, problems will occur */
#define AST_FAX_FRFLAG_GATEWAY (1 << 13)

/*! \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);
   /*! Generates manager event detailing the fax session */
   void (* const manager_fax_session)(struct mansession *,
      const char *, struct ast_fax_session *);
   /*! displays statistics from the fax technology module */
   char * (* const cli_show_stats)(int);
   /*! displays settings from the fax technology module */
   char * (* const cli_show_settings)(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);

/*! \brief get string representation of a FAX session's operation */
const char *ast_fax_session_operation_str(struct ast_fax_session *s);

/*!
 * \brief Log message at FAX or recommended level
 *
 * The first four parameters can be represented with Asterisk's
 * LOG_* levels. In other words, this function may be called
 * like
 *
 * ast_fax_log(LOG_DEBUG, msg);
 */
void ast_fax_log(int level, const char *file, const int line, const char *function, const char *msg);

#endif