headers.h 8.95 KB
Newer Older
Gijs Peskens's avatar
Gijs Peskens committed
1
/*
2 3
 * Copyright © 2020, VideoLAN and librist authors
 * Copyright © 2019-2020 SipRadius LLC
Gijs Peskens's avatar
Gijs Peskens committed
4 5
 * All rights reserved.
 *
6
 * SPDX-License-Identifier: BSD-2-Clause
Gijs Peskens's avatar
Gijs Peskens committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
 */

#ifndef LIBRIST_HEADERS_H
#define LIBRIST_HEADERS_H

#include <stdint.h>
#include <stdlib.h>

/* Used for cname, miface and shared secret */
#define RIST_MAX_STRING_SHORT 128
/* Used for url/address */
#define RIST_MAX_STRING_LONG 256

/* Track PROTOCOL and API changes */
#define RIST_PEER_UDPSOCKET_VERSION (0)
#define RIST_PEER_CONFIG_VERSION (0)
23
#define RIST_UDP_CONFIG_VERSION (0)
24
#define RIST_STATS_VERSION (0)
Gijs Peskens's avatar
Gijs Peskens committed
25 26 27 28 29 30 31 32 33 34 35 36

/* Default peer config values */
#define RIST_DEFAULT_VIRT_SRC_PORT (1971)
#define RIST_DEFAULT_VIRT_DST_PORT (1968)
#define RIST_DEFAULT_RECOVERY_MODE RIST_RECOVERY_MODE_TIME
#define RIST_DEFAULT_RECOVERY_MAXBITRATE (100000)
#define RIST_DEFAULT_RECOVERY_MAXBITRATE_RETURN (0)
#define RIST_DEFAULT_RECOVERY_LENGHT_MIN (1000)
#define RIST_DEFAULT_RECOVERY_LENGHT_MAX (1000)
#define RIST_DEFAULT_RECOVERY_REORDER_BUFFER (25)
#define RIST_DEFAULT_RECOVERY_RTT_MIN (50)
#define RIST_DEFAULT_RECOVERY_RTT_MAX (500)
37 38 39
#define RIST_DEFAULT_CONGESTION_CONTROL_MODE RIST_CONGESTION_CONTROL_MODE_NORMAL
#define RIST_DEFAULT_MIN_RETRIES (6)
#define RIST_DEFAULT_MAX_RETRIES (20)
40
#define RIST_DEFAULT_VERBOSE_LEVEL RIST_LOG_INFO
Gijs Peskens's avatar
Gijs Peskens committed
41 42 43
#define RIST_DEFAULT_PROFILE RIST_PROFILE_MAIN
#define RIST_DEFAULT_SESSION_TIMEOUT (60000)
#define RIST_DEFAULT_KEEPALIVE_INTERVAL (1000)
44
#define RIST_DEFAULT_TIMING_MODE RIST_TIMING_MODE_SOURCE
Gijs Peskens's avatar
Gijs Peskens committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60

/* Rist URL parameter names for peer config */
#define RIST_URL_PARAM_BUFFER_SIZE "buffer"
#define RIST_URL_PARAM_SECRET "secret"
#define RIST_URL_PARAM_AES_TYPE "aes-type"
#define RIST_URL_PARAM_BANDWIDTH "bandwidth"
#define RIST_URL_PARAM_RET_BANDWIDTH "return-bandwidth"
#define RIST_URL_PARAM_REORDER_BUFFER "reorder-buffer"
#define RIST_URL_PARAM_RTT "rtt"
#define RIST_URL_PARAM_COMPRESSION "compression"
#define RIST_URL_PARAM_CNAME "cname"
#define RIST_URL_PARAM_VIRT_DST_PORT "virt-dst-port"
#define RIST_URL_PARAM_WEIGHT "weight"
#define RIST_URL_PARAM_MIFACE "miface"
#define RIST_URL_PARAM_SESSION_TIMEOUT "session-timeout"
#define RIST_URL_PARAM_KEEPALIVE_INT "keepalive-interval"
61 62
#define RIST_URL_PARAM_SRP_USERNAME "username"
#define RIST_URL_PARAM_SRP_PASSWORD "password"
Gijs Peskens's avatar
Gijs Peskens committed
63 64 65 66 67 68
/* Less common URL parameters */
#define RIST_URL_PARAM_BUFFER_SIZE_MIN "buffer-min"
#define RIST_URL_PARAM_BUFFER_SIZE_MAX "buffer-max"
#define RIST_URL_PARAM_RTT_MIN "rtt-min"
#define RIST_URL_PARAM_RTT_MAX "rtt-max"
#define RIST_URL_PARAM_AES_KEY_ROTATION "key-rotation"
69 70 71
#define RIST_URL_PARAM_CONGESTION_CONTROL "congestion-control"
#define RIST_URL_PARAM_MIN_RETRIES "min-retries"
#define RIST_URL_PARAM_MAX_RETRIES "max-retries"
72
#define RIST_URL_PARAM_TIMING_MODE "timing-mode"
73 74 75 76
/* udp specific parameters */
#define RIST_URL_PARAM_STREAM_ID "stream-id"
#define RIST_URL_PARAM_RTP_TIMESTAMP "rtp-timestamp"
#define RIST_URL_PARAM_RTP_SEQUENCE "rtp-sequence"
Gijs Peskens's avatar
Gijs Peskens committed
77
#define RIST_URL_PARAP_RTP_OUTPUT_PTYPE "rtp-ptype"
Gijs Peskens's avatar
Gijs Peskens committed
78 79 80 81 82
/* Rist additional parameter names */
#define RIST_URL_PARAM_VIRT_SRC_PORT "virt-src-port"
#define RIST_URL_PARAM_PROFILE "profile"
#define RIST_URL_PARAM_VERBOSE_LEVEL "verbose-level"

83 84 85 86 87 88 89 90
/* Error Codes */
#define RIST_ERR_MALLOC -1
#define RIST_ERR_NULL_PEER -2
#define RIST_ERR_INVALID_STRING_LENGTH -3
#define RIST_ERR_INVALID_PROFILE -4
#define RIST_ERR_MISSING_CALLBACK_FUNCTION -5
#define RIST_ERR_NULL_CREDENTIALS -6

Gijs Peskens's avatar
Gijs Peskens committed
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
enum rist_nack_type
{
	RIST_NACK_RANGE = 0,
	RIST_NACK_BITMASK = 1,
};

enum rist_profile
{
	RIST_PROFILE_SIMPLE = 0,
	RIST_PROFILE_MAIN = 1,
	RIST_PROFILE_ADVANCED = 2,
};

enum rist_log_level
{
	RIST_LOG_DISABLE = -1,
	RIST_LOG_ERROR = 3,
	RIST_LOG_WARN = 4,
	RIST_LOG_NOTICE = 5,
	RIST_LOG_INFO = 6,
	RIST_LOG_DEBUG = 7,
	RIST_LOG_SIMULATE = 100,
};

enum rist_recovery_mode
{
	RIST_RECOVERY_MODE_UNCONFIGURED = 0,
	RIST_RECOVERY_MODE_DISABLED = 1,
Sergio Ammirata's avatar
Sergio Ammirata committed
119
	RIST_RECOVERY_MODE_TIME = 2,
Gijs Peskens's avatar
Gijs Peskens committed
120 121
};

122
enum rist_congestion_control_mode
Gijs Peskens's avatar
Gijs Peskens committed
123
{
124 125 126
	RIST_CONGESTION_CONTROL_MODE_OFF = 0,
	RIST_CONGESTION_CONTROL_MODE_NORMAL = 1,
	RIST_CONGESTION_CONTROL_MODE_AGGRESSIVE = 2
Gijs Peskens's avatar
Gijs Peskens committed
127 128
};

129 130 131 132 133 134 135
enum rist_timing_mode
{
	RIST_TIMING_MODE_SOURCE = 0,
	RIST_TIMING_MODE_ARRIVAL = 1,
	RIST_TIMING_MODE_RTC = 2
};

136
enum rist_data_block_sender_flags
Gijs Peskens's avatar
Gijs Peskens committed
137 138
{
	RIST_DATA_FLAGS_USE_SEQ = 1,
139 140 141 142 143
	RIST_DATA_FLAGS_NEED_FREE = 2
};

enum rist_data_block_receiver_flags
{
144 145
	RIST_DATA_FLAGS_DISCONTINUITY = 1,
	RIST_DATA_FLAGS_FLOW_BUFFER_START = 2
Gijs Peskens's avatar
Gijs Peskens committed
146 147 148 149 150 151 152 153
};

enum rist_stats_type
{
	RIST_STATS_SENDER_PEER,
	RIST_STATS_RECEIVER_FLOW
};

154 155 156 157 158 159 160 161
enum rist_connection_status
{
	RIST_CONNECTION_ESTABLISHED = 0,
	RIST_CONNECTION_TIMED_OUT = 1,
	RIST_CLIENT_CONNECTED = 2,
	RIST_CLIENT_TIMED_OUT = 3
};

Gijs Peskens's avatar
Gijs Peskens committed
162
struct rist_ctx;
Gijs Peskens's avatar
Gijs Peskens committed
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
struct rist_peer;

struct rist_data_block
{
	const void *payload;
	size_t payload_len;
	uint64_t ts_ntp;
	/* The virtual source and destination ports are not used for simple profile */
	uint16_t virt_src_port;
	/* These next fields are not needed/used by rist_sender_data_write */
	uint16_t virt_dst_port;
	struct rist_peer *peer;
	uint32_t flow_id;
	/* Get's populated by librist with the rtp_seq on output, can be used on input to tell librist which rtp_seq to use */
	uint64_t seq;
	uint32_t flags;
179
	struct rist_ref *ref;
Gijs Peskens's avatar
Gijs Peskens committed
180 181 182 183 184 185 186 187 188 189
};

struct rist_oob_block
{
	struct rist_peer *peer;
	const void *payload;
	size_t payload_len;
	uint64_t ts_ntp;
};

190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
struct rist_udp_config
{
	int version;

	/* Communication parameters */
	// If a value of 0 is specified for address family, the library
	// will parse the address and populate all communication parameters.
	// Alternatively, use either AF_INET or AF_INET6 and address will be
	// treated like an IP address or hostname
	int address_family;
	int initiate_conn;
	char address[RIST_MAX_STRING_LONG];
	char miface[RIST_MAX_STRING_SHORT];
	uint16_t physical_port;
	char prefix[16];
	int rtp_timestamp;
	int rtp_sequence;
	int rtp;
Gijs Peskens's avatar
Gijs Peskens committed
208
	uint8_t rtp_ptype;
209 210 211
	uint16_t stream_id;
};

Gijs Peskens's avatar
Gijs Peskens committed
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
struct rist_peer_config
{
	int version;

	/* Communication parameters */
	// If a value of 0 is specified for address family, the library
	// will parse the address and populate all communication parameters.
	// Alternatively, use either AF_INET or AF_INET6 and address will be
	// treated like an IP address or hostname
	int address_family;
	int initiate_conn;
	char address[RIST_MAX_STRING_LONG];
	char miface[RIST_MAX_STRING_SHORT];
	uint16_t physical_port;

	/* The virtual destination port is not used for simple profile */
	uint16_t virt_dst_port;

	/* Recovery options */
	enum rist_recovery_mode recovery_mode;
232 233 234 235 236 237 238
	uint32_t recovery_maxbitrate; /* kbps */
	uint32_t recovery_maxbitrate_return; /* kbps */
	uint32_t recovery_length_min; /* ms */
	uint32_t recovery_length_max; /* ms */
	uint32_t recovery_reorder_buffer; /* ms */
	uint32_t recovery_rtt_min; /* ms */
	uint32_t recovery_rtt_max; /* ms */
Gijs Peskens's avatar
Gijs Peskens committed
239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254

	/* Load balancing weight (use 0 for duplication) */
	uint32_t weight;

	/* Encryption */
	char secret[RIST_MAX_STRING_SHORT];
	int key_size;
	uint32_t key_rotation;

	/* Compression (sender only as receiver is auto detect) */
	int compression;

	/* cname identifier for rtcp packets */
	char cname[RIST_MAX_STRING_SHORT];

	/* Congestion control */
255 256 257
	enum rist_congestion_control_mode congestion_control_mode;
	uint32_t min_retries;
	uint32_t max_retries;
Gijs Peskens's avatar
Gijs Peskens committed
258 259 260 261

	/* Connection options */
	uint32_t session_timeout;
	uint32_t keepalive_interval;
262
	uint32_t timing_mode;
263 264
	char srp_username[RIST_MAX_STRING_LONG];
	char srp_password[RIST_MAX_STRING_LONG];
Gijs Peskens's avatar
Gijs Peskens committed
265 266 267 268 269 270 271 272 273 274 275 276
};

struct rist_stats_sender_peer
{
	/* cname */
	char cname[RIST_MAX_STRING_SHORT];
	/* internal peer id */
	uint32_t peer_id;
	/* avg bandwidth calculation */
	size_t bandwidth;
	/* bandwidth devoted to retries */
	size_t retry_bandwidth;
277
	/* num sent packets */
Gijs Peskens's avatar
Gijs Peskens committed
278
	uint64_t sent;
279
	/* num received packets */
Gijs Peskens's avatar
Gijs Peskens committed
280 281 282
	uint64_t received;
	/* retransmitted packets */
	uint64_t retransmitted;
283
	/* quality: Q = (sent * 100.0) / sent + bloat_skipped + bandwidth_skipped + retransmit_skipped + retransmitted */
Gijs Peskens's avatar
Gijs Peskens committed
284 285 286 287 288 289 290
	double quality;
	/* current RTT */
	uint32_t rtt;
};

struct rist_stats_receiver_flow
{
291 292 293 294 295
	/* peer count */
	uint32_t peer_count;
	/* combined peer cnames */
	char cname[RIST_MAX_STRING_LONG];
	/* flow id (set by senders) */
Gijs Peskens's avatar
Gijs Peskens committed
296
	uint32_t flow_id;
Sergio Ammirata's avatar
Sergio Ammirata committed
297 298
	/* flow status */
	int status;
299 300 301 302 303 304 305
	/* avg bandwidth calculation */
	size_t bandwidth;
	/* bandwidth devoted to retries */
	size_t retry_bandwidth;
	/* num sent packets */
	uint64_t sent;
	/* num received packets */
Gijs Peskens's avatar
Gijs Peskens committed
306 307 308
	uint64_t received;
	/* missing, including reordered */
	uint32_t missing;
Sergio Ammirata's avatar
Sergio Ammirata committed
309 310
	/* reordered */
	uint32_t reordered;
311 312 313 314
	/* total recovered */
	uint32_t recovered;
	/* recovered on the first retry */
	uint32_t recovered_one_retry;
Gijs Peskens's avatar
Gijs Peskens committed
315 316
	/* lost packets */
	uint32_t lost;
317
	/* quality: Q = (received * 100.0) / received + missing */
318
	double quality;
Sergio Ammirata's avatar
Sergio Ammirata committed
319
	/* packet inter-arrival time (microseconds) */
Gijs Peskens's avatar
Gijs Peskens committed
320 321 322
	uint64_t min_inter_packet_spacing;
	uint64_t cur_inter_packet_spacing;
	uint64_t max_inter_packet_spacing;
323 324 325
	/* avg rtt all non dead peers */
	uint32_t rtt;
};
Gijs Peskens's avatar
Gijs Peskens committed
326

327 328
struct rist_stats
{
329 330 331
	uint32_t json_size;
	char *stats_json;
	uint16_t version;
332 333
	enum rist_stats_type stats_type;
	union {
Sergio Ammirata's avatar
Sergio Ammirata committed
334 335
		struct rist_stats_sender_peer sender_peer;
		struct rist_stats_receiver_flow receiver_flow;
336
	} stats;
337
};
Gijs Peskens's avatar
Gijs Peskens committed
338 339

#endif