twrtp.h

/*
 * Themyscira Wireless RTP endpoint implementation:
 * public API definition for Osmocom-integrated version.
 *
 * This code was contributed to Osmocom Cellular Network Infrastructure
 * project by Mother Mychaela N. Falconia of Themyscira Wireless.
 * Mother Mychaela's contributions are NOT subject to copyright:
 * no rights reserved, all rights relinquished.
 */
 
#pragma once
 
#include <stdint.h>
#include <stdbool.h>
 
#include <osmocom/core/msgb.h>
#include <osmocom/core/socket.h>
 
struct osmo_twrtp;
 
struct osmo_twrtp_stats {
        /* For ABI reasons, none of the following fields may be deleted
         * or reordered! */
        uint32_t rx_rtp_pkt;
        uint32_t rx_rtp_badsrc;
        uint32_t rx_rtcp_pkt;
        uint32_t rx_rtcp_badsrc;
        uint32_t rx_rtcp_invalid;
        uint32_t rx_rtcp_wrong_ssrc;
        uint32_t tx_rtp_pkt;
        uint32_t tx_rtp_bytes;
        uint32_t tx_rtcp_pkt;
        /* New fields may be added here at the end; once added, they become
         * permanent like the initially defined ones. */
};
 
/* declare structs that are used in our API */
 
struct osmo_twjit;
struct osmo_twjit_config;
struct osmo_twjit_stats;
struct osmo_twjit_rr_info;
 
/* public API functions: create & destroy, local and remote addresses */
 
struct osmo_twrtp *
osmo_twrtp_create(void *ctx, uint16_t clock_khz, uint16_t quantum_ms,
                  bool random_ts_seq,
                  const struct osmo_twjit_config *twjit_config);
void osmo_twrtp_destroy(struct osmo_twrtp *endp);
 
int osmo_twrtp_supply_fds(struct osmo_twrtp *endp, int rtp_fd, int rtcp_fd);
int osmo_twrtp_bind_local(struct osmo_twrtp *endp,
                          const struct osmo_sockaddr *rtp_addr, bool bind_rtcp);
int osmo_twrtp_set_remote(struct osmo_twrtp *endp,
                          const struct osmo_sockaddr *rtp_addr);
 
/* receiving incoming RTP via twjit */
 
void osmo_twrtp_twjit_rx_ctrl(struct osmo_twrtp *endp, bool rx_enable);
 
/* output function, to be called by TDM/GSM/etc fixed-timing side */
struct msgb *osmo_twrtp_twjit_rx_poll(struct osmo_twrtp *endp);
 
/* receiving incoming RTP without twjit */
 
/* callback function takes ownership of msgb *if* it returns true */
typedef bool (*osmo_twrtp_raw_rx_cb)(struct osmo_twrtp *endp, void *user_data,
                                     struct msgb *msg);
 
void osmo_twrtp_set_raw_rx_cb(struct osmo_twrtp *endp, osmo_twrtp_raw_rx_cb cb,
                              void *user_data);
 
/* RTP Tx direction */
 
int osmo_twrtp_tx_quantum(struct osmo_twrtp *endp, const uint8_t *payload,
                          unsigned payload_len, uint8_t payload_type,
                          bool marker, bool auto_marker, bool send_rtcp);
void osmo_twrtp_tx_skip(struct osmo_twrtp *endp);
void osmo_twrtp_tx_restart(struct osmo_twrtp *endp);
 
int osmo_twrtp_tx_forward(struct osmo_twrtp *endp, struct msgb *msg);
 
/* support for emitting RTCP SR & RR */
 
int osmo_twrtp_set_sdes(struct osmo_twrtp *endp, const char *cname,
                        const char *name, const char *email, const char *phone,
                        const char *loc, const char *tool, const char *note);
void osmo_twrtp_set_auto_rtcp_interval(struct osmo_twrtp *endp,
                                        uint16_t interval);
 
int osmo_twrtp_send_rtcp_rr(struct osmo_twrtp *endp);
 
/* information retrieval functions */
 
struct osmo_twjit *osmo_twrtp_get_twjit(struct osmo_twrtp *endp);
 
const struct osmo_twrtp_stats *osmo_twrtp_get_stats(struct osmo_twrtp *endp);
 
/* have we received at least one RTCP RR matching our RTP Tx output? */
bool osmo_twrtp_got_rtcp_rr(struct osmo_twrtp *endp);
 
/* retrieving RTCP RR info: valid only if above function returned true */
uint32_t osmo_twrtp_rr_lost_word(struct osmo_twrtp *endp);
int32_t osmo_twrtp_rr_lost_cumulative(struct osmo_twrtp *endp);
uint32_t osmo_twrtp_rr_jitter_last(struct osmo_twrtp *endp);
uint32_t osmo_twrtp_rr_jitter_max(struct osmo_twrtp *endp);
 
/* socket-related miscellany */
 
int osmo_twrtp_get_rtp_fd(struct osmo_twrtp *endp);
int osmo_twrtp_get_rtcp_fd(struct osmo_twrtp *endp);
 
int osmo_twrtp_set_dscp(struct osmo_twrtp *endp, uint8_t dscp);
int osmo_twrtp_set_socket_prio(struct osmo_twrtp *endp, int prio);