spandsp  3.0.0
udptl.h
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * udptl.h - An implementation of the UDPTL protocol defined in
5  * ITU T.38, less the packet exchange part.
6  *
7  * Written by Steve Underwood <steveu@coppice.org>
8  *
9  * Copyright (C) 2009, 2022 Steve Underwood
10  *
11  * All rights reserved.
12  *
13  * This program is free software; you can redistribute it and/or modify
14  * it under the terms of the GNU General Public License version 2, as
15  * published by the Free Software Foundation.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program; if not, write to the Free Software
24  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25  */
26 
27 #if !defined(_SPANDSP_UDPTL_H_)
28 #define _SPANDSP_UDPTL_H_
29 
30 #define LOCAL_FAX_MAX_DATAGRAM 400
31 #define LOCAL_FAX_MAX_FEC_PACKETS 5
32 
33 #define UDPTL_BUF_MASK 15
34 
35 typedef int (*udptl_rx_packet_handler_t) (void *user_data, const uint8_t msg[], int len, int seq_no);
36 
37 typedef struct
38 {
39  int buf_len;
40  uint8_t buf[LOCAL_FAX_MAX_DATAGRAM];
42 
43 typedef struct
44 {
45  int buf_len;
46  uint8_t buf[LOCAL_FAX_MAX_DATAGRAM];
47  int fec_len[LOCAL_FAX_MAX_FEC_PACKETS];
48  uint8_t fec[LOCAL_FAX_MAX_FEC_PACKETS][LOCAL_FAX_MAX_DATAGRAM];
49  int fec_span;
50  int fec_entries;
52 
54 {
55  udptl_rx_packet_handler_t rx_packet_handler;
56  void *user_data;
57 
58  /*! This option indicates the error correction scheme used in transmitted UDPTL
59  packets. */
61 
62  /*! This option indicates the number of error correction entries transmitted in
63  UDPTL packets. */
65 
66  /*! This option indicates the span of the error correction entries in transmitted
67  UDPTL packets (FEC only). */
69 
70  /*! This option indicates the maximum size of a datagram that can be accepted by
71  the remote device. */
73 
74  /*! This option indicates the maximum size of a datagram that we are prepared to
75  accept. */
77 
78  int verbose;
79 
80  int tx_seq_no;
81  int rx_seq_no;
82  int rx_expected_seq_no;
83 
84  udptl_fec_tx_buffer_t tx[UDPTL_BUF_MASK + 1];
85  udptl_fec_rx_buffer_t rx[UDPTL_BUF_MASK + 1];
86 
87  /*! \brief Error and flow logging control */
89 };
90 
91 enum
92 {
93  UDPTL_ERROR_CORRECTION_NONE,
94  UDPTL_ERROR_CORRECTION_FEC,
95  UDPTL_ERROR_CORRECTION_REDUNDANCY
96 };
97 
98 typedef struct udptl_state_s udptl_state_t;
99 
100 #if defined(__cplusplus)
101 extern "C" {
102 #endif
103 
104 /*! \brief Process an arriving UDPTL packet.
105  \param s The UDPTL context.
106  \param buf The UDPTL packet buffer.
107  \param len The length of the packet.
108  \return 0 for OK. */
109 SPAN_DECLARE(int) udptl_rx_packet(udptl_state_t *s, const uint8_t buf[], int len);
110 
111 /*! \brief Construct a UDPTL packet, ready for transmission.
112  \param s The UDPTL context.
113  \param buf The UDPTL packet buffer.
114  \param msg The primary packet.
115  \param msg_len The length of the primary packet.
116  \return The length of the constructed UDPTL packet. */
117 SPAN_DECLARE(int) udptl_build_packet(udptl_state_t *s, uint8_t buf[], const uint8_t msg[], int msg_len);
118 
119 /*! \brief Change the error correction settings of a UDPTL context.
120  \param s The UDPTL context.
121  \param ec_scheme One of the optional error correction schemes.
122  \param span The packet span over which error correction should be applied.
123  \param entries The number of error correction entries to include in packets.
124  \return 0 for OK. */
125 SPAN_DECLARE(int) udptl_set_error_correction(udptl_state_t *s, int ec_scheme, int span, int entries);
126 
127 /*! \brief Check the error correction settings of a UDPTL context.
128  \param s The UDPTL context.
129  \param ec_scheme One of the optional error correction schemes.
130  \param span The packet span over which error correction is being applied.
131  \param entries The number of error correction being included in packets.
132  \return 0 for OK. */
133 SPAN_DECLARE(int) udptl_get_error_correction(udptl_state_t *s, int *ec_scheme, int *span, int *entries);
134 
135 SPAN_DECLARE(int) udptl_set_local_max_datagram(udptl_state_t *s, int max_datagram);
136 
137 SPAN_DECLARE(int) udptl_get_local_max_datagram(udptl_state_t *s);
138 
139 SPAN_DECLARE(int) udptl_set_far_max_datagram(udptl_state_t *s, int max_datagram);
140 
141 SPAN_DECLARE(int) udptl_get_far_max_datagram(udptl_state_t *s);
142 
143 /*! Get the logging context associated with a UDPTL context.
144  \brief Get the logging context associated with a UDPTL context.
145  \param s The modem context.
146  \return A pointer to the logging context */
147 SPAN_DECLARE(logging_state_t *) udptl_get_logging_state(udptl_state_t *s);
148 
149 /*! \brief Initialise a UDPTL context.
150  \param s The UDPTL context.
151  \param ec_scheme One of the optional error correction schemes.
152  \param span The packet span over which error correction should be applied.
153  \param entries The number of error correction entries to include in packets.
154  \param rx_packet_handler The callback function, used to report arriving IFP packets.
155  \param user_data An opaque pointer supplied to rx_packet_handler.
156  \return A pointer to the UDPTL context, or NULL if there was a problem. */
157 SPAN_DECLARE(udptl_state_t *) udptl_init(udptl_state_t *s, int ec_scheme, int span, int entries, udptl_rx_packet_handler_t rx_packet_handler, void *user_data);
158 
159 /*! \brief Release a UDPTL context.
160  \param s The UDPTL context.
161  \return 0 for OK. */
162 SPAN_DECLARE(int) udptl_release(udptl_state_t *s);
163 
164 /*! \brief Free a UDPTL context.
165  \param s The UDPTL context.
166  \return 0 for OK. */
167 SPAN_DECLARE(int) udptl_free(udptl_state_t *s);
168 
169 #if defined(__cplusplus)
170 }
171 #endif
172 
173 #endif
174 /*- End of file ------------------------------------------------------------*/
Definition: udptl.h:53
Definition: udptl.h:37
int far_max_datagram_size
Definition: udptl.h:72
int error_correction_scheme
Definition: udptl.h:60
int error_correction_span
Definition: udptl.h:68
int error_correction_entries
Definition: udptl.h:64
Definition: udptl.h:43
logging_state_t logging
Error and flow logging control.
Definition: udptl.h:88
Definition: private/logging.h:33
int local_max_datagram_size
Definition: udptl.h:76