qiurui
/
uvgrtp-base
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

common: Update documentation of public API 

This commit makes Doxygen generation create better documentation.
This commit is contained in:
Joni Räsänen 2022-09-15 07:53:59 +03:00
parent 0dc49ae325
commit 4dba1d55d1
6 changed files with 173 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
include/uvgrtp/context.hh
View File

@ -10,6 +10,9 @@ namespace uvgrtp {
class session;
/**
* \brief Provides CNAME isolation and can be used to create uvgrtp::session objects
*/
class context {
public:
/**
@ -31,13 +34,12 @@ namespace uvgrtp {
/**
* \brief Create a new RTP session
*
* \param addr IPv4 address of the remote participant
* \param address IPv4 address of the remote participant
*
* \return RTP session object
*
* \retval uvgrtp::session On success
* \retval nullptr If "remote_addr" is empty
* \retval nullptr If memory allocation failed
* \retval nullptr If "address" is empty or memory allocation failed
*/
uvgrtp::session *create_session(std::string address);
@ -55,7 +57,6 @@ namespace uvgrtp {
* \return RTP session object
*
* \retval uvgrtp::session On success
* \retval nullptr If remote_addr or local_addr is empty
* \retval nullptr If memory allocation failed
*/
uvgrtp::session *create_session(std::string remote_addr, std::string local_addr);
@ -76,6 +77,12 @@ namespace uvgrtp {
std::string& get_cname();
/// \endcond
/**
* \brief Has Crypto++ been included in uvgRTP library
*
* \retval true Crypto++ has been included, using SRTP is possible
* \retval false Crypto++ has not been included, using SRTP is not possible
*/
bool crypto_enabled() const;
private:

42
include/uvgrtp/frame.hh
View File

@ -49,6 +49,7 @@ namespace uvgrtp {
uint8_t *data = nullptr;
});
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-5" target="_blank">RFC 3550 section 5</a> */
struct rtp_frame {
struct rtp_header header;
uint32_t *csrc = nullptr;
@ -56,32 +57,52 @@ namespace uvgrtp {
size_t padding_len = 0; /* non-zero if frame is padded */
/** \brief Length of the packet payload in bytes added by uvgRTP to help process the frame
*
* \details payload_len = total length - header length - padding length (if padded)
*/
size_t payload_len = 0;
uint8_t* payload = nullptr;
/// \cond DO_NOT_DOCUMENT
uint8_t *dgram = nullptr; /* pointer to the UDP datagram (for internal use only) */
size_t dgram_size = 0; /* size of the UDP datagram */
/// \endcond
};
/** \brief Header of for all RTCP packets defined in <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6" target="_blank">RFC 3550 section 6</a> */
struct rtcp_header {
/** \brief This field identifies the version of RTP. The version defined by
* RFC 3550 is two (2). */
uint8_t version = 0;
/** \brief Does this packet contain padding at the end */
uint8_t padding = 0;
union {
uint8_t count = 0;
uint8_t pkt_subtype; /* for app packets */
/** \brief Source count or report count. Alternative to pkt_subtype. */
uint8_t count = 0;
/** \brief Subtype in APP packets. Alternative to count */
uint8_t pkt_subtype;
};
/** \brief Identifies the RTCP packet type */
uint8_t pkt_type = 0;
uint16_t length = 0; // whole message measured in 32-bit words
/** \brief Length of the whole message measured in 32-bit words */
uint16_t length = 0;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.4.1" target="_blank">RFC 3550 section 6.4.1</a> */
struct rtcp_sender_info {
uint32_t ntp_msw = 0; /* NTP timestamp, most significant word */
uint32_t ntp_lsw = 0; /* NTP timestamp, least significant word */
uint32_t rtp_ts = 0; /* RTP timestamp corresponding to same time as NTP */
/** \brief NTP timestamp, most significant word */
uint32_t ntp_msw = 0;
/** \brief NTP timestamp, least significant word */
uint32_t ntp_lsw = 0;
/** \brief RTP timestamp corresponding to this NTP timestamp */
uint32_t rtp_ts = 0;
uint32_t pkt_cnt = 0;
/** \brief Also known as octet count*/
uint32_t byte_cnt = 0;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.4.1" target="_blank">RFC 3550 section 6.4.1</a> */
struct rtcp_report_block {
uint32_t ssrc = 0;
uint8_t fraction = 0;
@ -92,12 +113,14 @@ namespace uvgrtp {
uint32_t dlsr = 0; /* delay since last Sender Report */
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.4.2" target="_blank">RFC 3550 section 6.4.2</a> */
struct rtcp_receiver_report {
struct rtcp_header header;
uint32_t ssrc = 0;
std::vector<rtcp_report_block> report_blocks;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.4.1" target="_blank">RFC 3550 section 6.4.1</a> */
struct rtcp_sender_report {
struct rtcp_header header;
uint32_t ssrc = 0;
@ -105,28 +128,33 @@ namespace uvgrtp {
std::vector<rtcp_report_block> report_blocks;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.5" target="_blank">RFC 3550 section 6.5</a> */
struct rtcp_sdes_item {
uint8_t type = 0;
uint8_t length = 0;
uint8_t *data = nullptr;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.5" target="_blank">RFC 3550 section 6.5</a> */
struct rtcp_sdes_chunk {
uint32_t ssrc = 0;
std::vector<rtcp_sdes_item> items;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.5" target="_blank">RFC 3550 section 6.5</a> */
struct rtcp_sdes_packet {
struct rtcp_header header;
std::vector<rtcp_sdes_chunk> chunks;
};
/** \brief See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6.7" target="_blank">RFC 3550 section 6.7</a> */
struct rtcp_app_packet {
struct rtcp_header header;
uint32_t ssrc = 0;
uint8_t name[4] = {0};
uint8_t *payload = nullptr;
size_t payload_len = 0; // in bytes
/** \brief Size of the payload in bytes. Added by uvgRTP to help process the payload. */
size_t payload_len = 0;
};
PACK(struct zrtp_frame {

32
include/uvgrtp/media_stream.hh
View File

@ -35,8 +35,17 @@ namespace uvgrtp {
class media;
}
// Corresponds to one RTP session in RFC 3550
/**
* \brief The media_stream is an entity which represents one RTP stream.
*
* \details media_stream is defined by the ports which are used for sending and/or receiving media.
* It is possible for media_stream to be bi- or unidirectional. The unidirectionality
* is achieved by specifying RCE_SEND_ONLY or RCE_RECEIVE_ONLY flag when creating media_stream.
*
* If RCE_RTCP was given when creating media_stream, you can get the uvgrtp::rtcp object with get_rtcp()-function.
*
* media_stream corresponds to one RTP session in <a href="https://www.rfc-editor.org/rfc/rfc3550">RFC 3550</a>.
*/
class media_stream {
public:
/// \cond DO_NOT_DOCUMENT
@ -69,12 +78,9 @@ namespace uvgrtp {
*
* \brief Add keying information for user-managed SRTP session
*
* \details For user-managed SRTP session, the media stream is not started
* until SRTP key has been added and all calls to push_frame() will fail
*
* Notice that if user-managed SRTP has been enabled during media stream creation,
* this function must be called before anything else. All calls to other functions
* will fail with ::RTP_NOT_INITIALIZED until the SRTP context has been specified
* \details For user-managed SRTP session (flag RCE_SRTP_KMNGMNT_USER),
* the media stream is not started until SRTP key has been added and all calls
* to push_frame() will fail.
*
* \param key SRTP master key, default is 128-bit long
* \param salt 112-bit long salt
@ -214,8 +220,7 @@ namespace uvgrtp {
* \return RTP frame
*
* \retval uvgrtp::frame::rtp_frame* On success
* \retval nullptr If a frame was not received within the specified time limit
* \retval nullptr If an unrecoverable error happened
* \retval nullptr If a frame was not received within the specified time limit or in case of an error
*/
uvgrtp::frame::rtp_frame *pull_frame(size_t timeout_ms);
@ -246,7 +251,6 @@ namespace uvgrtp {
*
* \retval RTP_OK On success
* \retval RTP_INVALID_VALUE If the provided value is not valid for a given configuration flag
* \retval RTP_INVALID_VALUE If the provided configuration flag is not supported
* \retval RTP_GENERIC_ERROR If setsockopt(2) failed
*/
rtp_error_t configure_ctx(int rcc_flag, ssize_t value);
@ -271,6 +275,12 @@ namespace uvgrtp {
*/
uvgrtp::rtcp *get_rtcp();
/**
* \brief Get SSRC identifier. You can use the SSRC value for example to find the report
* block belonging to this media_stream in RTCP sender/receiver report.
*
* \return SSRC value
*/
uint32_t get_ssrc() const;
private:

83
include/uvgrtp/rtcp.hh
View File

@ -86,9 +86,25 @@ namespace uvgrtp {
uint32_t payload_len;
const uint8_t* payload;
};
/// \endcond
/**
* \brief RTCP instance handles all incoming and outgoing RTCP traffic, including report generation
*
* \details If media_stream was created with RCE_RTCP flag, RTCP is enabled. RTCP periodically sends compound RTCP packets.
* The bit rate of RTP session influences the reporting interval, but changing this has not yet been implemented.
*
* The compound RTCP packet begins with either Sender Reports if we sent RTP packets recently or Receiver Report if we didn't
* send RTP packets recently. Both of these report types include report blocks for all the RTP sources we have received packets
* from during reporting period. The compound packets also always have an SDES packet and calling send_sdes_packet()-function will
* modify the contents of this SDES packet.
*
* You can use the APP packet to test new RTCP packet types using the send_app_packet()-function.
* The APP packets are added to these periodically sent compound packets.
*
*
* See <a href="https://www.rfc-editor.org/rfc/rfc3550#section-6" target="_blank">RFC 3550 section 6</a> for more details.
*/
class rtcp {
public:
/// \cond DO_NOT_DOCUMENT
@ -244,7 +260,17 @@ namespace uvgrtp {
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_sender_hook(void (*hook)(uvgrtp::frame::rtcp_sender_report *));
rtp_error_t install_sender_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_sender_report>)> sr_handler);
/**
* \brief Install an RTCP Sender Report hook
*
* \details This function is called when an RTCP Sender Report is received
*
* \param sr_handler C++ function pointer to the hook
*
* \retval RTP_OK on success
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_sender_hook(std::function<void(std::unique_ptr<uvgrtp::frame::rtcp_sender_report>)> sr_handler);
/**
@ -258,7 +284,17 @@ namespace uvgrtp {
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_receiver_hook(void (*hook)(uvgrtp::frame::rtcp_receiver_report *));
rtp_error_t install_receiver_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_receiver_report>)> rr_handler);
/**
* \brief Install an RTCP Receiver Report hook
*
* \details This function is called when an RTCP Receiver Report is received
*
* \param rr_handler C++ function pointer to the hook
*
* \retval RTP_OK on success
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_receiver_hook(std::function<void(std::unique_ptr<uvgrtp::frame::rtcp_receiver_report>)> rr_handler);
/**
@ -272,7 +308,17 @@ namespace uvgrtp {
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_sdes_hook(void (*hook)(uvgrtp::frame::rtcp_sdes_packet *));
rtp_error_t install_sdes_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_sdes_packet>)> sdes_handler);
/**
* \brief Install an RTCP SDES packet hook
*
* \details This function is called when an RTCP SDES packet is received
*
* \param sdes_handler C++ function pointer to the hook
*
* \retval RTP_OK on success
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_sdes_hook(std::function<void(std::unique_ptr<uvgrtp::frame::rtcp_sdes_packet>)> sdes_handler);
/**
@ -286,10 +332,34 @@ namespace uvgrtp {
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_app_hook(void (*hook)(uvgrtp::frame::rtcp_app_packet *));
rtp_error_t install_app_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_app_packet>)> app_handler);
/**
* \brief Install an RTCP APP packet hook
*
* \details This function is called when an RTCP APP packet is received
*
* \param app_handler C++ function pointer to the hook
*
* \retval RTP_OK on success
* \retval RTP_INVALID_VALUE If hook is nullptr
*/
rtp_error_t install_app_hook(std::function<void(std::unique_ptr<uvgrtp::frame::rtcp_app_packet>)> app_handler);
/// \cond DO_NOT_DOCUMENT
// These have been replaced by functions with unique_ptr in them
rtp_error_t install_sender_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_sender_report>)> sr_handler);
rtp_error_t install_receiver_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_receiver_report>)> rr_handler);
rtp_error_t install_sdes_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_sdes_packet>)> sdes_handler);
rtp_error_t install_app_hook(std::function<void(std::shared_ptr<uvgrtp::frame::rtcp_app_packet>)> app_handler);
/// \endcond
/**
* \brief Remove all installed hooks for RTCP
*
* \details Removes all installed hooks so they can be readded in case of changes
*
* \retval RTP_OK on success
*/
rtp_error_t remove_all_hooks();
/// \cond DO_NOT_DOCUMENT
@ -301,13 +371,12 @@ namespace uvgrtp {
/* Update RTCP-related sender statistics */
static rtp_error_t send_packet_handler_vec(void *arg, uvgrtp::buf_vec& buffers);
/// \endcond
// the length field is the rtcp packet size measured in 32-bit words - 1
size_t rtcp_length_in_bytes(uint16_t length);
/// \cond DO_NOT_DOCUMENT
void set_payload_size(size_t mtu_size);
/// \endcond
private:

50
include/uvgrtp/session.hh
View File

@ -13,8 +13,14 @@ namespace uvgrtp {
class media_stream;
class zrtp;
/* This session is not the same as RTP session. One uvgRTP session
* houses multiple RTP sessions.
/** \brief Provides ZRTP synchronization and can be used to create uvgrtp::media_stream objects
*
* \details
*
*
*
* By itself session does not do anything. The actual RTP streaming is done by media_stream objects,
* which can be created by session. media_stream corresponds to an RTP session in RFC 3550.
*/
class session {
@ -26,22 +32,22 @@ namespace uvgrtp {
/// \endcond
/**
* \brief Create a bidirectional media stream for an RTP session
* \brief Create a uni- or bidirectional media stream
*
* \details
*
* If both addresses were provided when uvgrtp::session was created, uvgRTP binds
* itself to local_addr:src_port and sends packets to remote_addr:dst_port.
*
* If only one address was provided, the RCE_SEND_ONLY flag in rce_flags can be used to
* avoid binding and src_port is thus ignored. RCE_RECEIVE_ONLY means dst_port is ignored.
* Without either, the one address is interpreted as remote_addr and binding happens to ANY.
*
* This object is used for both sending and receiving media, see documentation
* The created object is used for sending and/or receiving media, see documentation
* for uvgrtp::media_stream for more details.
*
* User can enable and disable functionality of uvgRTP by OR'ing (using |) RCE_* flags
* together and passing them using the rce_flags parameter
* If both addresses were provided when uvgrtp::session was created, by default
* uvgRTP binds itself to local_addr:src_port and sends packets to remote_addr:dst_port.
*
* User can enable and disable functionality of media_stream by OR'ing (using |) RCE_* flags
* together and passing them using the rce_flags parameter. In rce_flags, the RCE_SEND_ONLY flag
* can be used to avoid binding and src_port is thus ignored. Correspondinly RCE_RECEIVE_ONLY flag
* means dst_port is ignored. Without either RCE_SEND_ONLY or RCE_RECEIVE_ONLY,
* and if only one address was provided for session that address is interpreted as remote_addr and
* binding happens to ANY:src_port.
*
* \param src_port Local port that uvgRTP listens to for incoming RTP packets
* \param dst_port Remote port where uvgRTP sends RTP packets
@ -56,22 +62,18 @@ namespace uvgrtp {
uvgrtp::media_stream *create_stream(uint16_t src_port, uint16_t dst_port, rtp_format_t fmt, int rce_flags);
/**
* \brief Create a bidirectional media stream for an RTP session
* \brief Create a unidirectional media_stream for an RTP session
*
* \details
*
* If both addresses were provided when uvgrtp::session was created, uvgRTP binds
* sends packets to remote_addr:port and does not bind.
*
* If only one address was provided, the RCE_SEND_ONLY flag in rce_flags can be used to
* avoid binding and port is used as remote_port. RCE_RECEIVE_ONLY means port is used for binding.
* Without either, the one address is interpreted as remote_addr and binding happens to ANY.
*
* This object is used for both sending and receiving media, see documentation
* The created object is used for sending or receiving media, see documentation
* for uvgrtp::media_stream for more details.
*
* User can enable and disable functionality of uvgRTP by OR'ing (using |) RCE_* flags
* together and passing them using the rce_flags parameter
* together and passing them using the rce_flags parameter. The RCE_SEND_ONLY flag in
* rce_flags means the port is interpreted as a remote port. The RCE_RECEIVE_ONLY means
* the port is used for binding to a local interface. Without either flag,
* this function defaults to RCE_SEND_ONLY.
*
* \param port Either local or remote port depending on rce_flags
* \param fmt Format of the media stream. see ::RTP_FORMAT for more details

8
include/uvgrtp/util.hh
View File

@ -261,12 +261,13 @@ enum RTP_CTX_ENABLE_FLAGS {
* in the firewall open */
RCE_HOLEPUNCH_KEEPALIVE = 1 << 14,
/** Use 192-bit keys with SRTP */
/** Use 192-bit keys with SRTP, only user key management is supported */
RCE_SRTP_KEYSIZE_192 = 1 << 15,
/** Use 256-bit keys with SRTP */
/** Use 256-bit keys with SRTP, only user key management is supported */
RCE_SRTP_KEYSIZE_256 = 1 << 16,
/** Select which ZRTP stream does not perform Diffie-Hellman negotiation */
RCE_ZRTP_MULTISTREAM_NO_DH = 1 << 17,
RCE_LAST = 1 << 18
@ -299,7 +300,7 @@ enum RTP_CTX_CONFIGURATION_FLAGS {
* to a high number to prevent OS from dropping packets */
RCC_UDP_SND_BUF_SIZE = 2,
/** How large is the receiver ring buffer inside uvgRTP is
/** How large is the uvgRTP receiver ring buffer
*
* Default value is 4 MB
*
@ -356,4 +357,3 @@ enum RTP_CTX_CONFIGURATION_FLAGS {
};
extern thread_local rtp_error_t rtp_errno;
/// \endcond