IncomingDataQueue(3)

📦
version 2.0.9 · 4 versions
, in debian trixie, ubuntu noble, ubuntu questing

okay so bestie, welcome to IncomingDataQueue(3) — a Library Functions Manual page, section 3, and it's lowkey a big one, so buckle up. It's all about a queue for incoming RTP data packets in an RTP session. No cap. ✨

🎀 NAME 🎀

IncomingDataQueue — a Queue for incoming RTP data packets in an RTP session. that's the whole vibe. 💖

🌸 SYNOPSIS 🌸

#include <iqueue.h>

okay so the family tree situation: it Inherits IncomingDataQueueBase, and MembershipBookkeeping. And it's Inherited by RTPDataQueue. it's giving nepo baby but make it C++ inheritance. 💅

🦋 Classes 🦋

  • class SyncSourcesIterator — iterator through the list of synchronizations sources in this session. so you can loop through the sources, cute.

✨ Public Member Functions ✨

  • SyncSourcesIterator begin () — where the iterator starts.
  • SyncSourcesIterator end () — where it stops, classic.
  • const AppDataUnit * getData (uint32 stamp, const SyncSource *src=NULL) — Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer. note the exact default src=NULL.
  • bool isWaiting (const SyncSource *src=NULL) const — Determine if packets are waiting in the reception queue. the queue said "hold on".
  • uint32 getFirstTimestamp (const SyncSource *src=NULL) const — Get timestamp of first packet waiting in the queue.
  • void setMinValidPacketSequence (uint8 packets) — When receiving packets from a new source, it may be convenient to reject a first few packets before we are really sure the source is valid. trust issues, but make it RTP.
  • uint8 getDefaultMinValidPacketSequence () const — the default one.
  • uint8 getMinValidPacketSequence () const — Get the minimun number of consecutive packets that must be received from a source before accepting its data packets.
  • void setMaxPacketMisorder (uint16 packets) — how much out-of-order chaos we tolerate.
  • uint16 getDefaultMaxPacketMisorder () const
  • uint16 getMaxPacketMisorder () const
  • void setMaxPacketDropout (uint16 packets) — It also prevents packets sent after a restart of the source being immediately accepted.
  • uint16 getDefaultMaxPacketDropout () const
  • uint16 getMaxPacketDropout () const
  • void setInQueueCryptoContext (CryptoContext *cc) — Set input queue CryptoContext. 🔐
  • void removeInQueueCryptoContext (CryptoContext *cc) — Remove input queue CryptoContext.
  • CryptoContext * getInQueueCryptoContext (uint32 ssrc) — Get an input queue CryptoContext identified by SSRC. identified by the ssrc, bestie.

💜 Public Member Functions inherited from IncomingDataQueueBase 💜

  • size_t getDefaultMaxRecvPacketSize () const
  • size_t getMaxRecvPacketSize () const
  • void setMaxRecvPacketSize (size_t maxsize)

🌈 Public Member Functions inherited from RTPQueueBase 🌈

  • bool setPayloadFormat (const PayloadFormat &pf) — Set the payload format in use, for timing and payload type identification purposes.
  • uint32 getLocalSSRC () const
  • uint32 getCurrentRTPClockRate () const — Get the clock rate in RTP clock units (for instance, 8000 units per second for PCMU, or 90000 units per second for MP2T). yes those exact numbers, keep them.
  • PayloadType getCurrentPayloadType () const
  • timeval getInitialTime () const

⭐ Static Public Member Functions ⭐

  • static size_t getDefaultMembersSize ()

🔥 Protected Member Functions 🔥

  • IncomingDataQueue (uint32 size) — constructor, protected, we'll get to it below.
  • virtual ~IncomingDataQueue () — destructor, also protected.
  • bool checkSSRCInIncomingRTPPkt (SyncSourceLink &sourceLink, bool is_new, InetAddress &na, tpport_t tp) — Apply collision and loop detection and correction algorithm when receiving RTP data packets. collision + loop detection is doing the absolute most and it should.
  • void setSourceExpirationPeriod (uint8 intervals) — Set the number of RTCP intervals that the stack will wait to change the state of a source from stateActive to stateInactive, or to delete the source after being in stateInactive.
  • virtual size_t takeInDataPacket () — This function is used by the service thread to process the next incoming packet and place it in the receive list.
  • void renewLocalSSRC ()
  • IncomingDataQueue::IncomingRTPPktLink * getWaiting (uint32 timestamp, const SyncSource *src=NULL) — This is used to fetch a packet in the receive queue and to expire packets older than the current timestamp. expired packets, gone, blocked, unfollowed.
  • bool recordReception (SyncSourceLink &srcLink, const IncomingRTPPkt &pkt, const timeval recvtime) — Log reception of a new RTP packet from this source.
  • void recordExtraction (const IncomingRTPPkt &pkt) — Log extraction of a packet from this source from the scheduled reception queue.
  • void purgeIncomingQueue ()
  • virtual void onNewSyncSource (const SyncSource &) — Virtual called when a new synchronization source has joined the session. new source just joined the group chat.
  • virtual bool onRTPPacketRecv (IncomingRTPPkt &) — A virtual function to support parsing of arriving packets to determine if they should be kept in the queue and to dispatch events.
  • virtual void onExpireRecv (IncomingRTPPkt &) — A hook to filter packets in the receive queue that are being expired.
  • virtual bool onSRTPPacketError (IncomingRTPPkt &pkt, int32 errorCode) — A hook that gets called if the decoding of an incoming SRTP was erroneous. something went wrong decoding, and it tells you.
  • virtual bool end2EndDelayed (IncomingRTPPktLink &)
  • bool insertRecvPacket (IncomingRTPPktLink *packetLink) — Insert a just received packet in the queue (both general and source specific queues).
  • virtual size_t recvData (unsigned char *buffer, size_t length, InetHostAddress &host, tpport_t &port)=0 — This function performs the physical I/O for reading a packet from the source. pure virtual, =0, so you have to implement it.
  • virtual size_t getNextDataPacketSize () const =0 — also pure virtual =0.

💖 Protected Member Functions inherited from IncomingDataQueueBase 💖

  • IncomingDataQueueBase ()
  • virtual ~IncomingDataQueueBase ()

🧚 Protected Member Functions inherited from RTPQueueBase 🧚

  • RTPQueueBase (uint32 *ssrc=NULL)
  • void setLocalSSRC (uint32 ssrc)
  • uint32 getLocalSSRCNetwork () const
  • virtual ~RTPQueueBase ()
  • virtual size_t dispatchBYE (const std::string &) — A plugin point for posting of BYE messages. bye bestie 👋

🍓 Protected Member Functions inherited from MembershipBookkeeping 🍓

  • MembershipBookkeeping (uint32 initialSize=defaultMembersHashSize) — The initial size is a hint to allocate the resources needed in order to keep the members' identifiers and associated information.
  • virtual ~MembershipBookkeeping () — Purges all RTPSource structures created during the session, as well as the hash table and the list of sources. everything gets cleared out.
  • SyncSourceLink * getLink (const SyncSource &source) const
  • bool isMine (const SyncSource &source) const — Get whether a synchronization source is recorded in this membership controller.
  • bool isRegistered (uint32 ssrc) — Returns whether there is already a synchronizacion source with 'ssrc' SSRC identifier.
  • SyncSourceLink * getSourceBySSRC (uint32 ssrc, bool &created) — Get the description of a source by its ssrc identifier.
  • bool BYESource (uint32 ssrc) — Mark the source identified by ssrc as having sent a BYE packet.
  • bool removeSource (uint32 ssrc) — Remove the description of the source identified by ssrc
  • SyncSourceLink * getFirst ()
  • SyncSourceLink * getLast ()
  • uint32 getMembersCount ()
  • void setMembersCount (uint32 n)
  • uint32 getSendersCount ()
  • size_t getDefaultMembersHashSize ()

🌟 Protected Member Functions inherited from SyncSourceHandler 🌟

  • SyncSourceHandler ()
  • virtual ~SyncSourceHandler ()
  • void * getLink (const SyncSource &source) const — This requires SyncSource - SyncSourceHandler friendship. friendship, the C++ kind.
  • void setLink (SyncSource &source, void *link)
  • void setParticipant (SyncSource &source, Participant &p)
  • void setState (SyncSource &source, SyncSource::State ns)
  • void setSender (SyncSource &source, bool active)
  • void setDataTransportPort (SyncSource &source, tpport_t p)
  • void setControlTransportPort (SyncSource &source, tpport_t p)
  • void setNetworkAddress (SyncSource &source, InetAddress addr)

🌸 Protected Member Functions inherited from ParticipantHandler 🌸

  • ParticipantHandler ()
  • virtual ~ParticipantHandler ()
  • void setSDESItem (Participant *part, SDESItemType item, const std::string &val)
  • void setPRIVPrefix (Participant *part, const std::string val)

🦋 Protected Member Functions inherited from ApplicationHandler 🦋

  • ApplicationHandler ()
  • virtual ~ApplicationHandler ()
  • void addParticipant (RTPApplication &app, Participant &part)
  • void removeParticipant (RTPApplication &app, RTPApplication::ParticipantLink *pl)

👑 Protected Member Functions inherited from ConflictHandler 👑

  • ConflictHandler ()
  • virtual ~ConflictHandler ()
  • ConflictingTransportAddress * searchDataConflict (InetAddress na, tpport_t dtp)
  • ConflictingTransportAddress * searchControlConflict (InetAddress na, tpport_t ctp)
  • void updateConflict (ConflictingTransportAddress &ca)
  • void addConflict (const InetAddress &na, tpport_t dtp, tpport_t ctp)

💅 Protected Attributes 💅

  • ThreadLock recvLock
  • IncomingRTPPktLink * recvFirst
  • IncomingRTPPktLink * recvLast
  • uint8 minValidPacketSequence
  • uint16 maxPacketMisorder
  • uint16 maxPacketDropout
  • uint8 sourceExpirationPeriod
  • Mutex cryptoMutex
  • std::list< CryptoContext * > cryptoContexts

🌈 Protected Attributes inherited from ConflictHandler 🌈

  • ConflictingTransportAddress * firstConflict
  • ConflictingTransportAddress * lastConflict

⭐ Static Protected Attributes ⭐

  • static const uint8 defaultMinValidPacketSequence
  • static const uint16 defaultMaxPacketMisorder
  • static const uint16 defaultMaxPacketDropout
  • static const size_t defaultMembersSize

💫 Static Protected Attributes inherited from MembershipBookkeeping 💫

  • static const size_t defaultMembersHashSize
  • static const uint32 SEQNUMMOD

🌈 Detailed Description 🌈

Queue for incoming RTP data packets in an RTP session. that's literally the whole thing, and honestly? iconic. 💖

✍️ Author

Federico Montesino Pouzols fedemp@altern.org ty for your service, king. 🫶

🛠️ Constructor & Destructor Documentation 🛠️

🎀 IncomingDataQueue::IncomingDataQueue (uint32 size) [protected] 🎀

Parameters:

  • size — initial size of the membership table. that's the hint for how big the membership table starts out.

🎀 virtual IncomingDataQueue::~IncomingDataQueue () [inline], [protected], [virtual] 🎀

and that's the destructor — inline, protected, virtual, the whole trio. no parameters listed, so there's nothing else to spill. 💜

hang tight bestie, this page is long and it comes in 3 parts — and this was part 1. more incoming ✨

💖 MEMBER FUNCTION DOCUMENTATION 💖

okay bestie, this is the big one — every single member function, no skips, we're doing the whole thing ✨

SyncSourcesIterator IncomingDataQueue::begin () [inline]

(no description here, she's just vibing 🦋)

This one applies the collision and loop detection and correction algorithm when receiving RTP data packets. It follows section 8.2 in draft-ietf-avt-rtp-new. literally the whole protocol-boss move 💅

Parameters

  • sourceLink — link to the source object.
  • is_new — whether the source has been just recorded.
  • na — data packet network address.
  • tp — data packet source transport port.

Returns whether the packet must not be discarded. (yes, read that twice, the double negative is real 😭)

SyncSourcesIterator IncomingDataQueue::end () [inline]

(no description, carry on 🎀)

(no description given, she's a mystery 🌸)

const AppDataUnit * IncomingDataQueue::getData (uint32 stamp, const SyncSource * src = NULL)

Retreive data from a specific timestamped packet if such a packet is currently available in the receive buffer. ✨

Parameters

  • stamp — Data unit timestamp.
  • src — Optional synchronization source selector.

Returns data retrieved from the reception buffer.

Return values

  • null pointer if no packet with such timestamp is available.

Examples audiorx.cpp, rtpduphello.cpp, rtphello.cpp, and rtplisten.cpp.

uint16 IncomingDataQueue::getDefaultMaxPacketDropout () const [inline]

(no description, just a getter doing getter things 💜)

uint16 IncomingDataQueue::getDefaultMaxPacketMisorder () const [inline]

(no description 🦋)

static size_t IncomingDataQueue::getDefaultMembersSize () [inline], [static]

(no description ⭐)

uint8 IncomingDataQueue::getDefaultMinValidPacketSequence () const [inline]

(no description 🌸)

uint32 IncomingDataQueue::getFirstTimestamp (const SyncSource * src = NULL) const

Get timestamp of first packet waiting in the queue. the OG timestamp bestie 👑

Parameters

  • src — optional source selector.

Returns timestamp of first arrival packet.

Examples audiorx.cpp, rtpduphello.cpp, rtphello.cpp, and rtplisten.cpp.

CryptoContext * IncomingDataQueue::getInQueueCryptoContext (uint32 ssrc)

Get an input queue CryptoContext identified by SSRC. 🔐

Parameters

  • ssrc — Request CryptoContext for this incoming SSRC

Returns Pointer to CryptoContext of the SSRC of NULL if no context available for this SSRC.

uint16 IncomingDataQueue::getMaxPacketDropout () const [inline]

(no description 💅)

uint16 IncomingDataQueue::getMaxPacketMisorder () const [inline]

(no description 🎀)

uint8 IncomingDataQueue::getMinValidPacketSequence () const [inline]

Get the minimun number of consecutive packets that must be received from a source before accepting its data packets.

virtual size_t IncomingDataQueue::getNextDataPacketSize () const [protected], [pure virtual]

Implemented in RTPDuplex, TRTPSessionBase< RTPDataChannel, RTCPChannel, ServiceQueue >, and TRTPSessionBase< DualRTPUDPIPv4Channel, DualRTPUDPIPv4Channel, AVPQueue >.

This is used to fetch a packet in the receive queue and to expire packets older than the current timestamp. bye felicia to the old ones 👋

Returns packet buffer object for current timestamp if found.

Parameters

  • timestamp — timestamp requested.
  • src — optional source selector
Note — if found, the packet is removed from the reception queue

Insert a just received packet in the queue (both general and source specific queues). If the packet was already in the queue (same SSRC and sequence number), it is not inserted but deleted. no duplicates allowed, periodt 💀

Parameters

  • packetLink — link to a packet just received and generally validated and processed by onRTPPacketRecv.

Returns whether the packet was successfully inserted.

Return values

  • false when the packet is duplicated (there is already a packet from the same source with the same timestamp).
  • true when the packet is not duplicated.

bool IncomingDataQueue::isWaiting (const SyncSource * src = NULL) const

Determine if packets are waiting in the reception queue. vibe check on the queue 🫶

Parameters

  • src — Optional synchronization source selector.

Returns True if packets are waiting.

virtual void IncomingDataQueue::onExpireRecv (IncomingRTPPkt &) [inline], [protected], [virtual]

A hook to filter packets in the receive queue that are being expired. This hook may be used to do some application specific processing on expired packets before they are deleted. last-chance era ✨

Parameters

  • packet expired from the recv queue.

virtual void IncomingDataQueue::onNewSyncSource (const SyncSource &) [inline], [protected], [virtual]

Virtual called when a new synchronization source has joined the session. new bestie just walked in 🎉

Parameters

  • new synchronization source

Examples rtplisten.cpp.

virtual bool IncomingDataQueue::onRTPPacketRecv (IncomingRTPPkt &) [inline], [protected], [virtual]

A virtual function to support parsing of arriving packets to determine if they should be kept in the queue and to dispatch events. A generic header validity check (as specified in RFC 1889) is performed on every incoming packet. If the generic check completes successfully, this method is called before the packet is actually inserted into the reception queue. so real — the packet doesn't get in until this girl says so 💅

May be used to perform additional validity checks or to do some application specific processing.

Parameters

  • packet just received.

Returns true if packet is kept in the incoming packets queue.

virtual bool IncomingDataQueue::onSRTPPacketError (IncomingRTPPkt & pkt, int32 errorCode) [inline], [protected], [virtual]

A hook that gets called if the decoding of an incoming SRTP was erroneous. uh oh 😭

Parameters

  • pkt — The SRTP packet with error.
  • errorCode — The error code: -1 - SRTP authentication failure, -2 - replay check failed

Returns True: put the packet in incoming queue for further processing by the applications; false: dismiss packet. The default implementation returns false.

void IncomingDataQueue::purgeIncomingQueue () [protected]

(no description — she just purges 💀)

void IncomingDataQueue::recordExtraction (const IncomingRTPPkt & pkt) [protected]

Log extraction of a packet from this source from the scheduled reception queue. 📝

Parameters

  • pkt — Packet extracted from the queue.

Log reception of a new RTP packet from this source. Usually updates data such as the packet counter, the expected sequence number for the next packet and the time the last packet was received at. keeping receipts, literally 🧾

Parameters

  • srcLink — Link structure for the synchronization source of this packet.
  • pkt — Packet just created and to be logged.
  • recvtime — Reception time.

Returns whether, according to the source state and statistics, the packet is considered valid and must be inserted in the incoming packets queue.

virtual size_t IncomingDataQueue::recvData (unsigned char * buffer, size_t length, InetHostAddress & host, tpport_t & port) [protected], [pure virtual]

This function performs the physical I/O for reading a packet from the source. It is a virtual that is overridden in the derived class. the actual hands-on-grabbing-the-bytes moment 🔥

Returns number of bytes read.

Parameters

  • buffer of read packet.
  • length of data to read.
  • host address of source.
  • port number of source.

Implemented in RTPDuplex, TRTPSessionBase< RTPDataChannel, RTCPChannel, ServiceQueue >, and TRTPSessionBase< DualRTPUDPIPv4Channel, DualRTPUDPIPv4Channel, AVPQueue >.

void IncomingDataQueue::removeInQueueCryptoContext (CryptoContext * cc)

Remove input queue CryptoContext. The endQueue method (provided by RTPQueue) also deletes all registered CryptoContexts.

Parameters

  • cc — Pointer to initialized CryptoContext to remove. If pointer if NULL then delete the whole queue

void IncomingDataQueue::renewLocalSSRC () [protected], [virtual]

Reimplemented from RTPQueueBase.

Reimplemented in RTPDataQueue.

void IncomingDataQueue::setInQueueCryptoContext (CryptoContext * cc)

Set input queue CryptoContext. The endQueue method (provided by RTPQueue) deletes all registered CryptoContexts.

Parameters

  • cc — Pointer to initialized CryptoContext.

void IncomingDataQueue::setMaxPacketDropout (uint16 packets) [inline]

It also prevents packets sent after a restart of the source being immediately accepted. 🛑

void IncomingDataQueue::setMaxPacketMisorder (uint16 packets) [inline]

(no description 🌈)

void IncomingDataQueue::setMinValidPacketSequence (uint8 packets) [inline]

When receiving packets from a new source, it may be convenient to reject a first few packets before we are really sure the source is valid. This method sets how many data packets must be received in sequence before the source is considered valid and the stack starts to accept its packets. trust issues but make it protocol ✋

Note - the default (see defaultMinValidPacketSequence()) value for this parameter is 0, so that no packets are rejected (data packets are accepted from the first one). - this validation is performed after the generic header validation and the additional validation done in onRTPPacketRecv(). - if any valid RTCP packet is received from this source, it will be immediatly considered valid regardless of the number of sequential data packets received.

Parameters

  • packets — number of sequential packet required

void IncomingDataQueue::setSourceExpirationPeriod (uint8 intervals) [inline], [protected]

Set the number of RTCP intervals that the stack will wait to change the state of a source from stateActive to stateInactive, or to delete the source after being in stateInactive. Note that this value should be uniform accross all participants and SHOULD be fixed for a particular profile. consistency is key bestie 👑

Parameters

  • intervals — number of RTCP report intervals
Note - If RTCP is not being used, the RTCP interval is assumed to be the default: 5 seconds. - The default for this value is, as RECOMMENDED, 5.

virtual size_t IncomingDataQueue::takeInDataPacket () [protected], [virtual]

This function is used by the service thread to process the next incoming packet and place it in the receive list. 🫶

Returns number of payload bytes received. <0 if error.

Reimplemented in SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >.

Member Data Documentation 💖

okay bestie, this is the data-member part. Doxygen gave us the exact types and qualifiers but literally no descriptions for these, so we're keeping every detail and not inventing behavior. no cap. 🫶

  • std::list<CryptoContext *> IncomingDataQueue::cryptoContexts — [protected]. It's a std::list of CryptoContext * pointers, protected. That's the entire tea. ✨
  • Mutex IncomingDataQueue::cryptoMutex — [mutable], [protected]. A Mutex, mutable and protected. The docs said "that's it," so we respect it. 💅
  • const uint16 IncomingDataQueue::defaultMaxPacketDropout — [static], [protected]. const uint16, static, protected. A whole default, locked down. 🎀
  • const uint16 IncomingDataQueue::defaultMaxPacketMisorder — [static], [protected]. const uint16, static, protected. Default max packet misorder, doing its default thing. 🌸
  • const size_t IncomingDataQueue::defaultMembersSize — [static], [protected]. const size_t, static, protected. Size default, but make it protected. 👑
  • const uint8 IncomingDataQueue::defaultMinValidPacketSequence — [static], [protected]. const uint8, static, protected. The name is long, the type is small, the qualifiers are real. 😭
  • uint16 IncomingDataQueue::maxPacketDropout — [protected]. uint16, protected. No const, no static, just vibes and protection. 💜
  • uint16 IncomingDataQueue::maxPacketMisorder — [protected]. uint16, protected. Max misorder, but make it protected. 🦋
  • uint8 IncomingDataQueue::minValidPacketSequence — [protected]. uint8, protected. Tiny type, big name energy. ⭐
  • IncomingRTPPktLink* IncomingDataQueue::recvFirst — [protected]. A pointer to IncomingRTPPktLink, protected. First recv link, apparently. 🔥
  • IncomingRTPPktLink * IncomingDataQueue::recvLast — [protected]. Same pointer energy, protected. Last recv link, literally. 🙈
  • ThreadLock IncomingDataQueue::recvLock — [mutable], [protected]. A mutable protected ThreadLock. Lock it up, bestie. 💅
  • uint8 IncomingDataQueue::sourceExpirationPeriod — [protected]. uint8, protected. Source expiration period, tiny type and all. 🍓

Author 👑

This page was generated automatically by Doxygen for ccRTP from the source code. So the author credit is Doxygen + ccRTP, and that's iconic. 💖

okay bye bestie! This came from ccRTP and it's IncomingDataQueue(3). The footer didn't show a date, so no fake date — just love, no cap. 🫶✨

📦 where this page comes from