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 
73 enum 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. */
83 enum 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. */
95 enum 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 
103 enum sprt_timer_e
104 {
105  SPRT_TIMER_TA01 = 0,
106  SPRT_TIMER_TA02 = 1,
107  SPRT_TIMER_TR03 = 2
108 };
109 
110 enum sprt_timer_action_e
111 {
112  SPRT_TIMER_SET = 0,
113  SPRT_TIMER_CLEAR = 1,
114  SPRT_TIMER_ADJUST = 2
115 };
116 
117 typedef 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 
126 typedef int (*sprt_tx_packet_handler_t) (void *user_data, const uint8_t pkt[], int len);
127 typedef int (*sprt_rx_delivery_handler_t) (void *user_data, int channel, int seq_no, const uint8_t msg[], int len);
128 typedef span_timestamp_t (*sprt_timer_handler_t) (void *user_data, span_timestamp_t timeout);
129 
130 typedef struct sprt_state_s sprt_state_t;
131 
132 #if defined(__cplusplus)
133 extern "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. */
139 SPAN_DECLARE(const char *) sprt_transmission_channel_to_str(int channel);
140 
141 SPAN_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.*/
153 SPAN_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. */
161 SPAN_DECLARE(int) sprt_tx(sprt_state_t *s, int channel, const uint8_t buf[], int len);
162 
163 SPAN_DECLARE(int) sprt_set_local_tc_windows_size(sprt_state_t *s, int channel, int size);
164 
165 SPAN_DECLARE(int) sprt_get_local_tc_windows_size(sprt_state_t *s, int channel);
166 
167 SPAN_DECLARE(int) sprt_set_local_tc_payload_bytes(sprt_state_t *s, int channel, int max_len);
168 
169 SPAN_DECLARE(int) sprt_get_local_tc_payload_bytes(sprt_state_t *s, int channel);
170 
171 SPAN_DECLARE(int) sprt_set_local_tc_max_tries(sprt_state_t *s, int channel, int max_tries);
172 
173 SPAN_DECLARE(int) sprt_get_local_tc_max_tries(sprt_state_t *s, int channel);
174 
175 SPAN_DECLARE(int) sprt_set_far_tc_payload_bytes(sprt_state_t *s, int channel, int max_len);
176 
177 SPAN_DECLARE(int) sprt_get_far_tc_payload_bytes(sprt_state_t *s, int channel);
178 
179 SPAN_DECLARE(int) sprt_set_far_tc_windows_size(sprt_state_t *s, int channel, int size);
180 
181 SPAN_DECLARE(int) sprt_get_far_tc_windows_size(sprt_state_t *s, int channel);
182 
183 SPAN_DECLARE(int) sprt_set_tc_timeout(sprt_state_t *s, int channel, int timer, int timeout);
184 
185 SPAN_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 */
193 SPAN_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 */
200 SPAN_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 */
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. */
223 SPAN_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. */
240 SPAN_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. */
245 SPAN_DECLARE(int) sprt_free(sprt_state_t *s);
246 
247 #if defined(__cplusplus)
248 }
249 #endif
250 #endif
251 /*- End of file ------------------------------------------------------------*/
int sprt_release(sprt_state_t *s)
Release an SPRT context.
Definition: sprt.c:1330
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
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
const char * sprt_transmission_channel_to_str(int channel)
Find the name of an SPRT channel.
Definition: sprt.c:136
Definition: private/sprt.h:95
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
void(* span_modem_status_func_t)(void *user_data, int status)
Definition: async.h:131
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_free(sprt_state_t *s)
Free an SPRT context.
Definition: sprt.c:1336
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
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
Definition: private/logging.h:33
Definition: sprt.h:117