fixes crash during T.38 negotiation caused by invalid or missing FaxMaxDatagram field
[asterisk/asterisk.git] / include / asterisk / udptl.h
index 5b80980..3cbfeeb 100644 (file)
  * This program is free software, distributed under the terms of
  * the GNU General Public License
  *
  * This program is free software, distributed under the terms of
  * the GNU General Public License
  *
- * This version is disclaimed to DIGIUM for inclusion in the Asterisk project.
+ * A license has been granted to Digium (via disclaimer) for the use of
+ * this code.
  */
 
  */
 
+/*! \file
+ * \brief UDPTL support for T.38
+ * \author Steve Underwood <steveu@coppice.org>
+ * \ref udptl.c
+ * \todo add doxygen documentation to this file!
+ */
+
+
 #ifndef _ASTERISK_UDPTL_H
 #define _ASTERISK_UDPTL_H
 
 #ifndef _ASTERISK_UDPTL_H
 #define _ASTERISK_UDPTL_H
 
+#include "asterisk/network.h"
 #include "asterisk/frame.h"
 #include "asterisk/io.h"
 #include "asterisk/sched.h"
 #include "asterisk/channel.h"
 
 #include "asterisk/frame.h"
 #include "asterisk/io.h"
 #include "asterisk/sched.h"
 #include "asterisk/channel.h"
 
-#include <netinet/in.h>
 
 
-enum
-{
+enum ast_t38_ec_modes {
     UDPTL_ERROR_CORRECTION_NONE,
     UDPTL_ERROR_CORRECTION_FEC,
     UDPTL_ERROR_CORRECTION_REDUNDANCY
     UDPTL_ERROR_CORRECTION_NONE,
     UDPTL_ERROR_CORRECTION_FEC,
     UDPTL_ERROR_CORRECTION_REDUNDANCY
@@ -36,12 +44,12 @@ extern "C" {
 #endif
 
 struct ast_udptl_protocol {
 #endif
 
 struct ast_udptl_protocol {
-       /* Get UDPTL struct, or NULL if unwilling to transfer */
+       /*! \brief Get UDPTL struct, or NULL if unwilling to transfer */
        struct ast_udptl *(*get_udptl_info)(struct ast_channel *chan);
        struct ast_udptl *(*get_udptl_info)(struct ast_channel *chan);
-       /* Set UDPTL peer */
+       /*! \brief Set UDPTL peer */
        int (* const set_udptl_peer)(struct ast_channel *chan, struct ast_udptl *peer);
        const char * const type;
        int (* const set_udptl_peer)(struct ast_channel *chan, struct ast_udptl *peer);
        const char * const type;
-       struct ast_udptl_protocol *next;
+       AST_RWLIST_ENTRY(ast_udptl_protocol) list;
 };
 
 struct ast_udptl;
 };
 
 struct ast_udptl;
@@ -52,11 +60,26 @@ struct ast_udptl *ast_udptl_new(struct sched_context *sched, struct io_context *
 
 struct ast_udptl *ast_udptl_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int callbackmode, struct in_addr in);
 
 
 struct ast_udptl *ast_udptl_new_with_bindaddr(struct sched_context *sched, struct io_context *io, int callbackmode, struct in_addr in);
 
-void ast_udptl_set_peer(struct ast_udptl *udptl, struct sockaddr_in *them);
+/*!
+ * \brief Associates a character string 'tag' with a UDPTL session.
+ * \param udptl The UDPTL session.
+ * \param format printf-style format string used to construct the tag
+ * 
+ * This function formats a tag for the specified UDPTL
+ * session, so that any log messages generated by the UDPTL stack
+ * related to that session will include the tag and the reader of
+ * the messages will be able to identify which endpoint caused them
+ * to be generated.
+ *
+ * \retval none
+ */
+void __attribute__((format(printf, 2, 3))) ast_udptl_set_tag(struct ast_udptl *udptl, const char *format, ...);
+
+void ast_udptl_set_peer(struct ast_udptl *udptl, const struct sockaddr_in *them);
 
 
-void ast_udptl_get_peer(struct ast_udptl *udptl, struct sockaddr_in *them);
+void ast_udptl_get_peer(const struct ast_udptl *udptl, struct sockaddr_in *them);
 
 
-void ast_udptl_get_us(struct ast_udptl *udptl, struct sockaddr_in *us);
+void ast_udptl_get_us(const struct ast_udptl *udptl, struct sockaddr_in *us);
 
 void ast_udptl_destroy(struct ast_udptl *udptl);
 
 
 void ast_udptl_destroy(struct ast_udptl *udptl);
 
@@ -70,37 +93,49 @@ int ast_udptl_write(struct ast_udptl *udptl, struct ast_frame *f);
 
 struct ast_frame *ast_udptl_read(struct ast_udptl *udptl);
 
 
 struct ast_frame *ast_udptl_read(struct ast_udptl *udptl);
 
-int ast_udptl_fd(struct ast_udptl *udptl);
-
-int ast_udptl_settos(struct ast_udptl *udptl, int tos);
+int ast_udptl_fd(const struct ast_udptl *udptl);
 
 
-void ast_udptl_set_m_type(struct ast_udptl* udptl, int pt);
+int ast_udptl_setqos(struct ast_udptl *udptl, unsigned int tos, unsigned int cos);
 
 
-void ast_udptl_set_udptlmap_type(struct ast_udptl* udptl, int pt,
-                        char* mimeType, char* mimeSubtype);
+void ast_udptl_set_m_type(struct ast_udptl *udptl, unsigned int pt);
 
 
-int ast_udptl_lookup_code(struct ast_udptl* udptl, int isAstFormat, int code);
+void ast_udptl_set_udptlmap_type(struct ast_udptl *udptl, unsigned int pt,
+                                char *mimeType, char *mimeSubtype);
 
 
-void ast_udptl_offered_from_local(struct ast_udptl* udptl, int local);
+enum ast_t38_ec_modes ast_udptl_get_error_correction_scheme(const struct ast_udptl *udptl);
 
 
-int ast_udptl_get_error_correction_scheme(struct ast_udptl* udptl);
+void ast_udptl_set_error_correction_scheme(struct ast_udptl *udptl, enum ast_t38_ec_modes ec);
 
 
-void ast_udptl_set_error_correction_scheme(struct ast_udptl* udptl, int ec);
+void ast_udptl_set_local_max_ifp(struct ast_udptl *udptl, unsigned int max_ifp);
 
 
-int ast_udptl_get_local_max_datagram(struct ast_udptl* udptl);
-
-void ast_udptl_set_local_max_datagram(struct ast_udptl* udptl, int max_datagram);
+/*! 
+ * \brief retrieves local_max_datagram.
+ * 
+ * \retval positive value representing max datagram size.
+ * \retval 0 if no value is present
+ */
+unsigned int ast_udptl_get_local_max_datagram(struct ast_udptl *udptl);
 
 
-int ast_udptl_get_far_max_datagram(struct ast_udptl* udptl);
+/*! 
+ * \brief sets far max datagram size.  If max_datagram is = 0, the far max datagram
+ *  size is set to a default value.
+ */
+void ast_udptl_set_far_max_datagram(struct ast_udptl *udptl, unsigned int max_datagram);
 
 
-void ast_udptl_set_far_max_datagram(struct ast_udptl* udptl, int max_datagram);
+unsigned int ast_udptl_get_far_max_datagram(const struct ast_udptl *udptl);
 
 
-void ast_udptl_get_current_formats(struct ast_udptl* udptl,
-                            int* astFormats, int* nonAstFormats);
+/*! 
+ * \brief retrieves far max ifp
+ * 
+ * \retval positive value representing max ifp size
+ * \retval 0 if no value is present
+ */
+unsigned int ast_udptl_get_far_max_ifp(struct ast_udptl *udptl);
 
 void ast_udptl_setnat(struct ast_udptl *udptl, int nat);
 
 
 void ast_udptl_setnat(struct ast_udptl *udptl, int nat);
 
-int ast_udptl_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
+int ast_udptl_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags,
+                    struct ast_frame **fo, struct ast_channel **rc);
 
 int ast_udptl_proto_register(struct ast_udptl_protocol *proto);
 
 
 int ast_udptl_proto_register(struct ast_udptl_protocol *proto);
 
@@ -110,7 +145,10 @@ void ast_udptl_stop(struct ast_udptl *udptl);
 
 void ast_udptl_init(void);
 
 
 void ast_udptl_init(void);
 
-void ast_udptl_reload(void);
+/*!
+ * \version 1.6.1 return changed to int
+ */
+int ast_udptl_reload(void);
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }