--- name: "IncomingDataQueue" section: "3" platform: "linux" package: "libccrtp-doc" version: "2.0.9-4.1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/IncomingDataQueue" --- # IncomingDataQueue(3) Queue for incoming RTP data packets in an RTP session. ## NAME IncomingDataQueue - Queue for incoming RTP data packets in an RTP session. ## SYNOPSIS `#include ` Inherits **IncomingDataQueueBase**, and **MembershipBookkeeping**. Inherited by **RTPDataQueue**. ### Classes class **SyncSourcesIterator**\ iterator through the list of synchronizations sources in this session ### Public Member Functions **SyncSourcesIterator** **begin** ()\ **SyncSourcesIterator** **end** ()\ 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. bool **isWaiting** (const **SyncSource** \*src=NULL) const\ Determine if packets are waiting in the reception queue. 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. uint8 **getDefaultMinValidPacketSequence** () const\ 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)\ 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. 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). **PayloadType** **getCurrentPayloadType** () const\ timeval **getInitialTime** () const\ ### Static Public Member Functions static size\_t **getDefaultMembersSize** ()\ ### Protected Member Functions **IncomingDataQueue** (uint32 size)\ virtual **~IncomingDataQueue** ()\ 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. 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. 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. 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. 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. virtual size\_t **getNextDataPacketSize** () const =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. 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. **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. 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. **Author** Federico Montesino Pouzols fedemp@altern.org ## Constructor & Destructor Documentation ### IncomingDataQueue::IncomingDataQueue (uint32 size)` [protected]` **Parameters** *size* initial size of the membership table. ### virtual IncomingDataQueue::~IncomingDataQueue ()` [inline]`, ` [protected]`, ` [virtual]` ## Member Function Documentation ### SyncSourcesIterator IncomingDataQueue::begin ()` [inline]` ### bool IncomingDataQueue::checkSSRCInIncomingRTPPkt (SyncSourceLink & sourceLink, bool is\_new, InetAddress & na, tpport\_t tp)` [protected]` Apply collision and loop detection and correction algorithm when receiving RTP data packets. Follows section 8.2 in draft-ietf-avt-rtp-new. **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. ### SyncSourcesIterator IncomingDataQueue::end ()` [inline]` ### virtual bool IncomingDataQueue::end2EndDelayed (IncomingRTPPktLink &)` [inline]`, ` [protected]`, ` [virtual]` ### 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]` ### uint16 IncomingDataQueue::getDefaultMaxPacketMisorder () const` [inline]` ### static size\_t IncomingDataQueue::getDefaultMembersSize ()` [inline]`, ` [static]` ### uint8 IncomingDataQueue::getDefaultMinValidPacketSequence () const` [inline]` ### uint32 IncomingDataQueue::getFirstTimestamp (const SyncSource \* src = `NULL`) const Get timestamp of first packet waiting in the queue. **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]` ### uint16 IncomingDataQueue::getMaxPacketMisorder () const` [inline]` ### 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 \>**. ### IncomingDataQueue::IncomingRTPPktLink \* IncomingDataQueue::getWaiting (uint32 timestamp, const SyncSource \* src = `NULL`)` [protected]` This is used to fetch a packet in the receive queue and to expire packets older than the current timestamp. **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 ### bool IncomingDataQueue::insertRecvPacket (IncomingRTPPktLink \* packetLink)` [protected]` 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. **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. **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. **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. **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. 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. **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]` ### 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. ### bool IncomingDataQueue::recordReception (SyncSourceLink & srcLink, const IncomingRTPPkt & pkt, const timeval recvtime)` [protected]` 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. **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. **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]` ### 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. **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. **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 ### std::list\ IncomingDataQueue::cryptoContexts` [protected]` ### Mutex IncomingDataQueue::cryptoMutex` [mutable]`, ` [protected]` ### const uint16 IncomingDataQueue::defaultMaxPacketDropout` [static]`, ` [protected]` ### const uint16 IncomingDataQueue::defaultMaxPacketMisorder` [static]`, ` [protected]` ### const size\_t IncomingDataQueue::defaultMembersSize` [static]`, ` [protected]` ### const uint8 IncomingDataQueue::defaultMinValidPacketSequence` [static]`, ` [protected]` ### uint16 IncomingDataQueue::maxPacketDropout` [protected]` ### uint16 IncomingDataQueue::maxPacketMisorder` [protected]` ### uint8 IncomingDataQueue::minValidPacketSequence` [protected]` ### IncomingRTPPktLink\* IncomingDataQueue::recvFirst` [protected]` ### IncomingRTPPktLink \* IncomingDataQueue::recvLast` [protected]` ### ThreadLock IncomingDataQueue::recvLock` [mutable]`, ` [protected]` ### uint8 IncomingDataQueue::sourceExpirationPeriod` [protected]` ## Author Generated automatically by Doxygen for ccRTP from the source code.