spandsp 3.0.0
sprt.h
Go to the documentation of this file.
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * sprt.h - An implementation of the SPRT protocol defined in V.150.1
5 * Annex B, less the packet exchange part
6 *
7 * Written by Steve Underwood <steveu@coppice.org>
8 *
9 * Copyright (C) 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/*! \file */
28
29#if !defined(_SPANDSP_SPRT_H_)
30#define _SPANDSP_SPRT_H_
31
32#define SPRT_MIN_TC0_PAYLOAD_BYTES 140
33#define SPRT_MAX_TC0_PAYLOAD_BYTES 256
34#define SPRT_DEFAULT_TC0_PAYLOAD_BYTES 140
35
36#define SPRT_MIN_TC1_PAYLOAD_BYTES 132
37#define SPRT_MAX_TC1_PAYLOAD_BYTES 256
38#define SPRT_DEFAULT_TC1_PAYLOAD_BYTES 132
39
40#define SPRT_MIN_TC1_WINDOWS_SIZE 32
41#define SPRT_MAX_TC1_WINDOWS_SIZE 96
42#define SPRT_DEFAULT_TC1_WINDOWS_SIZE 32
43
44#define SPRT_MIN_TC2_PAYLOAD_BYTES 132
45#define SPRT_MAX_TC2_PAYLOAD_BYTES 256
46#define SPRT_DEFAULT_TC2_PAYLOAD_BYTES 132
47
48#define SPRT_MIN_TC2_WINDOWS_SIZE 8
49#define SPRT_MAX_TC2_WINDOWS_SIZE 32
50#define SPRT_DEFAULT_TC2_WINDOWS_SIZE 8
51
52#define SPRT_MIN_TC3_PAYLOAD_BYTES 140
53#define SPRT_MAX_TC3_PAYLOAD_BYTES 256
54#define SPRT_DEFAULT_TC3_PAYLOAD_BYTES 140
55
56/* Max window size for any channel. */
57#define SPRT_MAX_WINDOWS_SIZE 96
58
59/* Only typical values are specified for the timers */
60
61#define SPRT_DEFAULT_TIMER_TC1_TA01 90000 /* us */
62#define SPRT_DEFAULT_TIMER_TC1_TA02 130000 /* us */
63#define SPRT_DEFAULT_TIMER_TC1_TR03 500000 /* us */
64
65#define SPRT_DEFAULT_TIMER_TC2_TA01 90000 /* us */
66#define SPRT_DEFAULT_TIMER_TC2_TA02 500000 /* us */
67#define SPRT_DEFAULT_TIMER_TC2_TR03 500000 /* us */
68
69#define SPRT_MIN_MAX_TRIES 1
70#define SPRT_MAX_MAX_TRIES 20
71#define SPRT_DEFAULT_MAX_TRIES 10
72
73enum sprt_status_e
74{
75 SPRT_STATUS_OK = 0,
76 SPRT_STATUS_EXCESS_RETRIES = 1,
77 SPRT_STATUS_SUBSESSION_CHANGED = 2,
78 SPRT_STATUS_OUT_OF_SEQUENCE = 3
79};
80
81/* This view of the transmission channels divides them into an overall range, and a reliable subset
82 range within the overall range. */
83enum sprt_tcid_range_view_e
84{
85 SPRT_TCID_MIN = 0,
86 SPRT_TCID_MIN_RELIABLE = 1,
87 SPRT_TCID_MAX_RELIABLE = 2,
88 SPRT_TCID_MAX = 3
89};
90
91/* The total number of channels */
92#define SPRT_CHANNELS 4
93
94/* This view of the transmission channels specifically names them, for direct access. */
95enum sprt_tcid_e
96{
97 SPRT_TCID_UNRELIABLE_UNSEQUENCED = 0, /* Used for ack only */
98 SPRT_TCID_RELIABLE_SEQUENCED = 1, /* Used for data */
99 SPRT_TCID_EXPEDITED_RELIABLE_SEQUENCED = 2, /* Used for control/signalling data */
100 SPRT_TCID_UNRELIABLE_SEQUENCED = 3 /* Used for sequenced data that does not require reliable delivery */
101};
102
103enum sprt_timer_e
104{
105 SPRT_TIMER_TA01 = 0,
106 SPRT_TIMER_TA02 = 1,
107 SPRT_TIMER_TR03 = 2
108};
109
110enum sprt_timer_action_e
111{
112 SPRT_TIMER_SET = 0,
113 SPRT_TIMER_CLEAR = 1,
114 SPRT_TIMER_ADJUST = 2
115};
116
117typedef struct
118{
119 uint16_t payload_bytes;
120 uint16_t window_size;
121 int timer_ta01;
122 int timer_ta02;
123 int timer_tr03;
125
126typedef int (*sprt_tx_packet_handler_t) (void *user_data, const uint8_t pkt[], int len);
127typedef int (*sprt_rx_delivery_handler_t) (void *user_data, int channel, int seq_no, const uint8_t msg[], int len);
128typedef span_timestamp_t (*sprt_timer_handler_t) (void *user_data, span_timestamp_t timeout);
129
130typedef struct sprt_state_s sprt_state_t;
131
132#if defined(__cplusplus)
133extern "C" {
134#endif
135
136/*! \brief Find the name of an SPRT channel.
137 \param channel The number of the SPRT channel (0 to 3).
138 \return A pointer to a short string name for the channel, or NULL for an invalid channel. */
139SPAN_DECLARE(const char *) sprt_transmission_channel_to_str(int channel);
140
141SPAN_DECLARE(int) sprt_timer_expired(sprt_state_t *s, span_timestamp_t now);
142
143/*! \brief Process a packet arriving from the far end. If the packet validates as an SPRT
144 packet 0 is returned. If the packet does not follow the structure of an SPRT
145 packet, or its packet type field does not contain the expected value, -1 is
146 returned. In a mixed packet environment, where things like RTP, T.38 and SPRT
147 packets are mixed in the same stream, -1 should indicate than one of the other
148 packet sinks should be tried.
149 \param s The SPRT context.
150 \param pkt The SPRT packet buffer.
151 \param len The length of the packet.
152 \return 0 for accepted as a valid SPRT packet. -1 for rejected as an SPRT packet.*/
153SPAN_DECLARE(int) sprt_rx_packet(sprt_state_t *s, const uint8_t pkt[], int len);
154
155/*! \brief Send a message to a SPRT channel.
156 \param s The SPRT context.
157 \param channel The SPRT channel.
158 \param buf The message.
159 \param len The length of the message.
160 \return 0 for OK. */
161SPAN_DECLARE(int) sprt_tx(sprt_state_t *s, int channel, const uint8_t buf[], int len);
162
163SPAN_DECLARE(int) sprt_set_local_tc_windows_size(sprt_state_t *s, int channel, int size);
164
165SPAN_DECLARE(int) sprt_get_local_tc_windows_size(sprt_state_t *s, int channel);
166
167SPAN_DECLARE(int) sprt_set_local_tc_payload_bytes(sprt_state_t *s, int channel, int max_len);
168
169SPAN_DECLARE(int) sprt_get_local_tc_payload_bytes(sprt_state_t *s, int channel);
170
171SPAN_DECLARE(int) sprt_set_local_tc_max_tries(sprt_state_t *s, int channel, int max_tries);
172
173SPAN_DECLARE(int) sprt_get_local_tc_max_tries(sprt_state_t *s, int channel);
174
175SPAN_DECLARE(int) sprt_set_far_tc_payload_bytes(sprt_state_t *s, int channel, int max_len);
176
177SPAN_DECLARE(int) sprt_get_far_tc_payload_bytes(sprt_state_t *s, int channel);
178
179SPAN_DECLARE(int) sprt_set_far_tc_windows_size(sprt_state_t *s, int channel, int size);
180
181SPAN_DECLARE(int) sprt_get_far_tc_windows_size(sprt_state_t *s, int channel);
182
183SPAN_DECLARE(int) sprt_set_tc_timeout(sprt_state_t *s, int channel, int timer, int timeout);
184
185SPAN_DECLARE(int) sprt_get_tc_timeout(sprt_state_t *s, int channel, int timer);
186
187/*! Set whether the local end of the specified channel of the SPRT context is currently busy.
188 \brief Test if local end of SPRT context is busy.
189 \param s The SPRT context.
190 \param channel The SPRT channel number.
191 \param busy true for busy.
192 \return true for previously busy */
193SPAN_DECLARE(int) sprt_set_local_busy(sprt_state_t *s, int channel, bool busy);
194
195/*! Test whether the far end of the specified channel of the SPRT context is currently busy.
196 \brief Test if far end of SPRT context is busy.
197 \param s The SPRT context.
198 \param channel The SPRT channel number.
199 \return true for busy */
200SPAN_DECLARE(bool) sprt_get_far_busy_status(sprt_state_t *s, int channel);
201
202/*! Get the logging context associated with an SPRT context.
203 \brief Get the logging context associated with an SPRT context.
204 \param s The SPRT context.
205 \return A pointer to the logging context */
206SPAN_DECLARE(logging_state_t *) sprt_get_logging_state(sprt_state_t *s);
207
208/*! \brief Initialise an SPRT context.
209 \param s The SPRT context.
210 \param subsession_id The subsession ID for transmitted SPRT headers
211 \param rx_payload_type The payload type expected in received SPRT headers
212 \param tx_payload_type The payload type sent in transmitted SPRT headers
213 \param parms The parameter set for sizing the SPRT instance. NULL means use the defaults.
214 \param tx_packet_handler The callback function, used to send assembled packets.
215 \param tx_user_data An opaque pointer supplied to tx_packet_handler.
216 \param rx_delivery_handler The callback function, used to report arriving packets.
217 \param rx_user_data An opaque pointer supplied to rx_delivery_handler.
218 \param timer_handler The callback function, used to control the timers used by SPRT.
219 \param timer_user_data An opaque pointer supplied to timer_handler.
220 \param status_handler The callback function, used to report status events.
221 \param status_user_data An opaque pointer supplied to status_handler.
222 \return A pointer to the SPRT context, or NULL if there was a problem. */
223SPAN_DECLARE(sprt_state_t *) sprt_init(sprt_state_t *s,
224 uint8_t subsession_id,
225 uint8_t rx_payload_type,
226 uint8_t tx_payload_type,
227 channel_parms_t parms[SPRT_CHANNELS],
228 sprt_tx_packet_handler_t tx_packet_handler,
229 void *tx_user_data,
230 sprt_rx_delivery_handler_t rx_delivery_handler,
231 void *rx_user_data,
232 sprt_timer_handler_t timer_handler,
233 void *timer_user_data,
234 span_modem_status_func_t status_handler,
235 void *status_user_data);
236
237/*! \brief Release an SPRT context.
238 \param s The SPRT context.
239 \return 0 for OK. */
240SPAN_DECLARE(int) sprt_release(sprt_state_t *s);
241
242/*! \brief Free an SPRT context.
243 \param s The SPRT context.
244 \return 0 for OK. */
245SPAN_DECLARE(int) sprt_free(sprt_state_t *s);
246
247#if defined(__cplusplus)
248}
249#endif
250#endif
251/*- End of file ------------------------------------------------------------*/
void(* span_modem_status_func_t)(void *user_data, int status)
Definition async.h:131
struct logging_state_s logging_state_t
Definition logging.h:72
int sprt_release(sprt_state_t *s)
Release an SPRT context.
Definition sprt.c:1330
int sprt_tx(sprt_state_t *s, int channel, const uint8_t buf[], int len)
Send a message to a SPRT channel.
Definition sprt.c:903
bool sprt_get_far_busy_status(sprt_state_t *s, int channel)
Test if far end of SPRT context is busy.
Definition sprt.c:1193
const char * sprt_transmission_channel_to_str(int channel)
Find the name of an SPRT channel.
Definition sprt.c:136
int sprt_free(sprt_state_t *s)
Free an SPRT context.
Definition sprt.c:1336
int sprt_set_local_busy(sprt_state_t *s, int channel, bool busy)
Test if local end of SPRT context is busy.
Definition sprt.c:1170
sprt_state_t * sprt_init(sprt_state_t *s, uint8_t subsession_id, uint8_t rx_payload_type, uint8_t tx_payload_type, channel_parms_t parms[4], sprt_tx_packet_handler_t tx_packet_handler, void *tx_user_data, sprt_rx_delivery_handler_t rx_delivery_handler, void *rx_user_data, sprt_timer_handler_t timer_handler, void *timer_user_data, span_modem_status_func_t status_handler, void *status_user_data)
Initialise an SPRT context.
Definition sprt.c:1205
logging_state_t * sprt_get_logging_state(sprt_state_t *s)
Get the logging context associated with an SPRT context.
Definition sprt.c:1199
int sprt_rx_packet(sprt_state_t *s, const uint8_t pkt[], int len)
Process a packet arriving from the far end. If the packet validates as an SPRT packet 0 is returned....
Definition sprt.c:655
Definition sprt.h:118
Definition private/sprt.h:96