[asterisk-commits] kpfleming: branch group/t38_gateway r264754 - in /team/group/t38_gateway: ./ ...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Thu May 20 16:33:53 CDT 2010 

Author: kpfleming
Date: Thu May 20 16:33:52 2010
New Revision: 264754

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=264754
Log:
store some initial work at expressing the T.38 gateway design as a set
of APIs to be implemented


Added:
    team/group/t38_gateway/   (props changed)
      - copied from r264753, trunk/
Modified:
    team/group/t38_gateway/include/asterisk/res_fax.h

Propchange: team/group/t38_gateway/
------------------------------------------------------------------------------
Binary property 'branch-1.4-blocked' - no diff available.

Propchange: team/group/t38_gateway/
------------------------------------------------------------------------------
Binary property 'branch-1.4-merged' - no diff available.

Propchange: team/group/t38_gateway/
------------------------------------------------------------------------------
--- reviewboard:url (added)
+++ reviewboard:url Thu May 20 16:33:52 2010
@@ -1,0 +1,1 @@
+https://reviewboard.asterisk.org

Propchange: team/group/t38_gateway/
------------------------------------------------------------------------------
--- svn:externals (added)
+++ svn:externals Thu May 20 16:33:52 2010
@@ -1,0 +1,1 @@
+menuselect https://origsvn.digium.com/svn/menuselect/trunk

Propchange: team/group/t38_gateway/
------------------------------------------------------------------------------
--- svn:ignore (added)
+++ svn:ignore Thu May 20 16:33:52 2010
@@ -1,0 +1,26 @@
+asterisk
+defaults.h
+ast_expr2.output
+.version
+.depend
+.applied
+mpg123-0.59r
+mpg123-0.59r.tar.gz
+update.out
+.lastclean
+.cleancount
+.tags-depend
+.tags-sources
+tags
+TAGS
+testexpr2
+makeopts
+menuselect.makeopts
+menuselect.makedeps
+config.status
+config.log
+menuselect-tree
+autom4te.cache
+makeopts.embed_rules
+aclocal.m4
+update.log

Propchange: team/group/t38_gateway/
------------------------------------------------------------------------------
    svn:mergeinfo = /be/branches/C.3:256426

Modified: team/group/t38_gateway/include/asterisk/res_fax.h
URL: http://svnview.digium.com/svn/asterisk/team/group/t38_gateway/include/asterisk/res_fax.h?view=diff&rev=264754&r1=264753&r2=264754
==============================================================================
--- team/group/t38_gateway/include/asterisk/res_fax.h (original)
+++ team/group/t38_gateway/include/asterisk/res_fax.h Thu May 20 16:33:52 2010
@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2008-2009, Digium, Inc.
+ * Copyright (C) 2008-2010, Digium, Inc.
  *
  * Dwayne M. Hubbard <dhubbard at digium.com>
  * Kevin P. Fleming <kpfleming at digium.com>
@@ -256,4 +256,203 @@
 /*! \brief convert an ast_fax_state to a string */
 const char *ast_fax_state_to_str(enum ast_fax_state state);
 
+struct ast_fax_preamble_detector;
+
+/*!
+ * \brief Create a FAX V.21 preamble detector
+ * \since 1.8
+ *
+ * \retval NULL failure
+ * \retval non-NULL successfully allocated detector
+ *
+ */
+struct ast_fax_preamble_detector *ast_fax_preamble_detector_create(void);
+
+/*!
+ * \brief Destroy a FAX V.21 preamble detector
+ * \since 1.8
+ *
+ * \param[in] fpd Previously created preamble detector
+ *
+ * \return No return value
+ *
+ */
+void ast_fax_preamble_detector_destroy(struct ast_fax_preamble_detector *fpd);
+
+/*!
+ * \brief Feed audio into a FAX V.21 preamble detector
+ * \since 1.8
+ *
+ * \param[in] fpd Previously created preamble detector
+ * \param[in] frame Frame(s) of audio to be processed
+ *
+ * \retval 0 No preamble found
+ * \retval >0 Preamble detected
+ * \retval <0 Error occurred, detector is no longer usable
+ *
+ * \note Frames of audio passed to the detector must be AST_FRAME_VOICE
+ * with subclass AST_FORMAT_SLINEAR. Frames of any other type will
+ * be ignored.
+ *
+ */
+int ast_fax_preamble_detector_feed(struct ast_fax_preamble_detector *fpd, const struct ast_frame *frame);
+
+struct ast_fax_gateway;
+
+/*!
+ * \brief Create an audio<->T.38 FAX gateway
+ * \since 1.8
+ *
+ * \param[in] channel The channel on which the gateway should operate
+ * \param[in] fd A file descriptor the gateway can use to know when audio is available from the network
+ * \param[in] private A pointer to private data to be associated with the gateway, and passed to the read/write callback functions
+ * \param[in] read A callback function the gateway will call to read audio
+ * \param[in] write A callback function the gateway will call to write audio
+ *
+ * \details
+ * This function creates a FAX gateway object, which handles conversion
+ * between audio FAX and T.38 FAX in real time. It also handles T.38 negotiation
+ * and session setup, and relies upon the datastore that the FAXOPT dialplan
+ * function creates to get its parameters for how the T.38 and audio sessions
+ * should be configured.
+ *
+ * The expected usage of this object is by channel drivers that support
+ * devices/endpoints that have no T.38 support of their own, but to which
+ * normal FAX machines can be attached. A channel driver that uses these
+ * gateway objects can make itself appear to the rest of Asterisk as if its
+ * endpoints \b do \b have T.38 support, even though they don't.
+ *
+ * When a channel driver has decided to place a gateway object on a channel
+ * it should create one using this function, and provide a number of pieces
+ * of information:
+ *
+ * \li A pointer to an ast_channel, which the gateway object will effectively
+ * "own" until it is destroyed. This channel is the T.38 side of the gateway.
+ * \li A file descriptor that the gateway can use to know when audio is available
+ * from the endpoint that the channel driver manages. This is the audio
+ * side of the gateway.
+ * \li A pointer to some private data managed by the channel driver. The gateway
+ * will not use this pointer for any purpose except to pass it back to the
+ * channel driver when audio needs to be read or written from the endpoint.
+ * \li Pointers to callback functions for reading and writing audio. These
+ * functions must accept and generate only frames of type AST_FRAME_VOICE
+ * with subclass AST_FORMAT_SLINEAR; the gateway will not do any transcoding
+ * of the audio streams.
+ *
+ * After the gateway has been created, the channel driver should call
+ * ast_fax_gateway_fd() to get the file descriptor the gateway will use
+ * to signal when the T.38 side of the gateway has data available to be
+ * read; the channel driver should then either poll this file descriptor
+ * itself, or place it into the fds array of the ast_channel so that
+ * the Asterisk bridge code or an application will poll on it. In either
+ * case, when the file descriptor indicates that data is ready, it must
+ * be read by calling ast_fax_gateway_read().
+ *
+ * When the gateway object is no longer necessary (the session is complete
+ * or has failed, or never started, etc.), ast_fax_gateway_read() and
+ * ast_fax_gateway_write() will return errors, and the channel driver
+ * can call ast_fax_gateway_destroy() to shut down the gateway object
+ * and return control of the channel to its normal functions.
+ *
+ * \retval NULL failure
+ * \retval non-NULL successfully allocated gateway
+ *
+ * \note The channel pointed to by the 'channel' parameter must be locked
+ * before this function is called, and will be left locked.
+ *
+ */
+struct ast_fax_gateway *ast_fax_gateway_create(struct ast_channel *channel,
+					       int fd,
+					       void *private,
+					       struct ast_frame * (*read)(void *),
+					       int (*write)(void *, const struct ast_frame *));
+
+/*!
+ * \brief Obtain the file descriptor a gateway provides to trigger reads
+ *
+ * \param[in] fgw Previously created gateway
+ *
+ * \details
+ * A gateway needs to be able to indicate when it has data available to be sent
+ * to the T.38 endpoint it is connected to; it does this by providing a file
+ * descriptor that can be used in select() or poll(), and which will become
+ * 'ready for reading' when there is at least one ast_frame available.
+ * The file descriptor will supply one byte of data for each frame that is
+ * available, so after calling ast_fax_gateway_read() to retrieve a frame,
+ * a single byte of data should be read from the file descriptor, and then
+ * it can be checked again to see if more data is available.
+ *
+ * When the gateway is in use by a channel driver, the most common use of
+ * this file descriptor will be to place it into the fds array on the
+ * ast_channel, so that ast_read() will be called when the gateway
+ * has data available... and then the channel driver's read callback can
+ * call ast_fax_gateway_read() to get the data and return it to the Asterisk
+ * core.
+ *
+ * \return File descriptor
+ *
+ * \note The file descriptor returned by this function will be valid until
+ * ast_fax_gateway_destroy() is called for this gateway; it should not be
+ * used after that function is called.
+ *
+ */
+int ast_fax_gateway_fd(const struct ast_fax_gateway *fgw);
+
+/*!
+ * \brief Destroy an audio<->T.38 FAX gateway
+ * \since 1.8
+ *
+ * \param[in] fgw Previously created gateway
+ *
+ * \return No return value
+ *
+ * \note The channel associated with the gateway (originally passed to
+ * ast_fax_gateway_create()) must be locked before this function is called,
+ * and will be left locked.
+ *
+ */
+void ast_fax_gateway_destroy(struct ast_fax_gateway *fgw);
+
+/*!
+ * \brief Read a T.38-side frame from the gateway
+ *
+ * \param[in] fgw Previously created gateway
+ *
+ * \details
+ * This function should be called whenever the file descriptor provided by
+ * ast_fax_gateway_fd() indicates that a frame is ready for reading. The
+ * frame returned from this function could be a T.38 IFP frame (frame type
+ * AST_FRAME_MODEM with subclass AST_MODEM_T38) or it could be a control
+ * frame of type AST_CONTROL_T38_PARAMETERS. Typically this would be called
+ * by a channel driver's read callback function (called by ast_read()) and the
+ * resulting frame would be returned unmodified by that function to the Asterisk
+ * core.
+ *
+ * \retval non-NULL for success (a pointer to an ast_frame that must be freed
+ * when the reader no longer needs it)
+ * \retval NULL for failure
+ *
+ */
+struct ast_frame *ast_fax_gateway_read(struct ast_fax_gateway *fgw);
+
+/*!
+ * \brief Write a T.38-side frame to the gateway
+ *
+ * \param[in] fgw Previously created gateway
+ * \param[in] frame The frame to be written
+ *
+ * \details
+ * This function should be called to write T.38 IFP frames (frame type
+ * AST_FRAME_MODEM with subclass AST_MODEM_T38) and control frames of
+ * type AST_CONTROL_T38_PARAMETERS as they arrive from the Asterisk
+ * core.  Typically this would be done by a channel driver's write
+ * callback function (called by ast_write()) after it has determined
+ * that the frame should be sent to the gateway.
+ *
+ * \retval 0 for success
+ * \retval non-zero for failure
+ *
+ */
+int ast_fax_gateway_write(struct ast_fax_gateway *fgw, const struct ast_frame *frame);
+
 #endif

More information about the asterisk-commits mailing list