Go to the documentation of this file.
2This library is free software; you can redistribute it and/or modify it under
3the terms of the GNU Lesser General Public License as published by the
4Free Software Foundation; either version 3 of the License, or (at your
5option) any later version. (See <>.)
7This library is distributed in the hope that it will be useful, but WITHOUT
8ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
9FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
10more details.
12You should have received a copy of the GNU Lesser General Public License
13along with this library; if not, write to the Free Software Foundation, Inc.,
1451 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16// "liveMedia"
17// Copyright (c) 1996-2024 Live Networks, Inc. All rights reserved.
18// RTCP
19// C++ header
21#ifndef _RTCP_HH
22#define _RTCP_HH
24#ifndef _RTP_SINK_HH
25#include "RTPSink.hh"
27#ifndef _RTP_SOURCE_HH
28#include "RTPSource.hh"
34class SDESItem {
36 SDESItem(unsigned char tag, unsigned char const* value);
38 unsigned char const* data() const {return fData;}
39 unsigned totalSize() const;
42 unsigned char fData[2 + 0xFF]; // first 2 bytes are tag and length
45typedef void RTCPAppHandlerFunc(void* clientData,
46 u_int8_t subtype, u_int32_t nameBytes/*big-endian order*/,
47 u_int8_t* appDependentData, unsigned appDependentDataSize);
49class RTCPMemberDatabase; // forward
51typedef void ByeWithReasonHandlerFunc(void* clientData, char const* reason);
53class RTCPInstance: public Medium {
56 unsigned totSessionBW, /* in kbps */
57 unsigned char const* cname,
58 RTPSink* sink,
59 RTPSource* source,
60 Boolean isSSMTransmitter = False,
63 static Boolean lookupByName(UsageEnvironment& env, char const* instanceName,
64 RTCPInstance*& resultInstance);
66 unsigned numMembers() const;
67 unsigned totSessionBW() const { return fTotSessionBW; }
71 void setByeHandler(TaskFunc* handlerTask, void* clientData,
72 Boolean handleActiveParticipantsOnly = True);
73 // Assigns a handler routine to be called if a "BYE" arrives.
74 // The handler is called once only; for subsequent "BYE"s,
75 // "setByeHandler()" would need to be called again.
76 // If "handleActiveParticipantsOnly" is True, then the handler is called
77 // only if the SSRC is for a known sender (if we have a "RTPSource"),
78 // or if the SSRC is for a known receiver (if we have a "RTPSink").
79 // This prevents (for example) the handler for a multicast receiver being
80 // called if some other multicast receiver happens to exit.
81 // If "handleActiveParticipantsOnly" is False, then the handler is called
82 // for any incoming RTCP "BYE".
83 // (To remove an existing "BYE" handler, call "setByeHandler()" again, with a "handlerTask" of NULL.)
84 void setByeWithReasonHandler(ByeWithReasonHandlerFunc* handlerTask, void* clientData,
85 Boolean handleActiveParticipantsOnly = True);
86 // Like "setByeHandler()", except that a string 'reason for the bye' (received as part of
87 // the RTCP "BYE" packet) is passed to the handler function (along with "clientData").
88 // (The 'reason' parameter to the handler function will be a dynamically-allocated string,
89 // or NULL, and should be delete[]d by the handler function.)
90 void setSRHandler(TaskFunc* handlerTask, void* clientData);
91 void setRRHandler(TaskFunc* handlerTask, void* clientData);
92 // Assigns a handler routine to be called if a "SR" or "RR" packet
93 // (respectively) arrives. Unlike "setByeHandler()", the handler will
94 // be called once for each incoming "SR" or "RR". (To turn off handling,
95 // call the function again with "handlerTask" (and "clientData") as NULL.)
96 void setSpecificRRHandler(struct sockaddr_storage const& fromAddress, Port fromPort,
97 TaskFunc* handlerTask, void* clientData);
98 // Like "setRRHandler()", but applies only to "RR" packets that come from
99 // a specific source address and port. (Note that if both a specific
100 // and a general "RR" handler function is set, then both will be called.)
101 void unsetSpecificRRHandler(struct sockaddr_storage const& fromAddress, Port fromPort); // equivalent to setSpecificRRHandler(..., NULL, NULL);
102 void setAppHandler(RTCPAppHandlerFunc* handlerTask, void* clientData);
103 // Assigns a handler routine to be called whenever an "APP" packet arrives. (To turn off
104 // handling, call the function again with "handlerTask" (and "clientData") as NULL.)
105 void sendAppPacket(u_int8_t subtype, char const* name,
106 u_int8_t* appDependentData, unsigned appDependentDataSize);
107 // Sends a custom RTCP "APP" packet to the peer(s). The parameters correspond to their
108 // respective fields as described in the RTP/RTCP definition (RFC 3550).
109 // Note that only the low-order 5 bits of "subtype" are used, and only the first 4 bytes
110 // of "name" are used. (If "name" has fewer than 4 bytes, or is NULL,
111 // then the remaining bytes are '\0'.)
113 Groupsock* RTCPgs() const { return; }
115 void setStreamSocket(int sockNum, unsigned char streamChannelId, TLSState* tlsState);
116 void addStreamSocket(int sockNum, unsigned char streamChannelId, TLSState* tlsState);
117 void removeStreamSocket(int sockNum, unsigned char streamChannelId) {
118 fRTCPInterface.removeStreamSocket(sockNum, streamChannelId);
119 }
120 // hacks to allow sending RTP over TCP (RFC 2236, section 10.12)
123 void* handlerClientData) {
125 handlerClientData);
126 }
128 void injectReport(u_int8_t const* packet, unsigned packetSize, struct sockaddr_storage const& fromAddress);
129 // Allows an outside party to inject an RTCP report (from other than the network interface)
133 unsigned char const* cname,
134 RTPSink* sink, RTPSource* source,
135 Boolean isSSMTransmitter,
137 // called only by createNew()
138 virtual ~RTCPInstance();
140 virtual void noteArrivingRR(struct sockaddr_storage const& fromAddressAndPort,
141 int tcpSocketNum, unsigned char tcpStreamChannelId);
146 // redefined virtual functions:
147 virtual Boolean isRTCPInstance() const;
151 void addSR();
152 void addRR();
153 void enqueueCommonReportPrefix(unsigned char packetType, u_int32_t SSRC,
154 unsigned numExtraWords = 0);
157 void addSDES();
158 void addBYE(char const* reason);
162 static void onExpire(RTCPInstance* instance);
163 void onExpire1();
165 static void incomingReportHandler(RTCPInstance* instance, int /*mask*/);
166 void processIncomingReport(unsigned packetSize, struct sockaddr_storage const& fromAddressAndPort,
167 int tcpSocketNum, unsigned char tcpStreamChannelId);
168 void onReceive(int typeOfPacket, int totPacketSize, u_int32_t ssrc);
171 u_int8_t* fInBuf;
182 RTCPMemberDatabase* fKnownMembers;
183 unsigned fOutgoingReportCount; // used for SSRC member aging
211public: // because this stuff is used by an external "C" function
212 void schedule(double nextTime);
213 void reschedule(double nextTime);
215 void sendBYE(char const* reason = NULL);
216 int typeOfEvent() {return fTypeOfEvent;}
218 int packetType() {return fTypeOfPacket;}
222 void removeSSRC(u_int32_t ssrc, Boolean alsoRemoveStats);
225// RTCP packet types:
226const unsigned char RTCP_PT_SR = 200;
227const unsigned char RTCP_PT_RR = 201;
228const unsigned char RTCP_PT_SDES = 202;
229const unsigned char RTCP_PT_BYE = 203;
230const unsigned char RTCP_PT_APP = 204;
231const unsigned char RTCP_PT_RTPFB = 205; // Generic RTP Feedback [RFC4585]
232const unsigned char RTCP_PT_PSFB = 206; // Payload-specific [RFC4585]
233const unsigned char RTCP_PT_XR = 207; // extended report [RFC3611]
234const unsigned char RTCP_PT_AVB = 208; // AVB RTCP packet ["Standard for Layer 3 Transport Protocol for Time Sensitive Applications in Local Area Networks." Work in progress.]
235const unsigned char RTCP_PT_RSI = 209; // Receiver Summary Information [RFC5760]
236const unsigned char RTCP_PT_TOKEN = 210; // Port Mapping [RFC6284]
237const unsigned char RTCP_PT_IDMS = 211; // IDMS Settings [RFC7272]
239// SDES tags:
240const unsigned char RTCP_SDES_END = 0;
241const unsigned char RTCP_SDES_CNAME = 1;
242const unsigned char RTCP_SDES_NAME = 2;
243const unsigned char RTCP_SDES_EMAIL = 3;
244const unsigned char RTCP_SDES_PHONE = 4;
245const unsigned char RTCP_SDES_LOC = 5;
246const unsigned char RTCP_SDES_TOOL = 6;
247const unsigned char RTCP_SDES_NOTE = 7;
248const unsigned char RTCP_SDES_PRIV = 8;
const Boolean False
Definition: Boolean.hh:28
const Boolean True
Definition: Boolean.hh:31
unsigned char Boolean
Definition: Boolean.hh:25
void ByeWithReasonHandlerFunc(void *clientData, char const *reason)
Definition: RTCP.hh:51
const unsigned char RTCP_SDES_NOTE
Definition: RTCP.hh:247
const unsigned char RTCP_SDES_END
Definition: RTCP.hh:240
const unsigned char RTCP_SDES_PHONE
Definition: RTCP.hh:244
const unsigned char RTCP_SDES_LOC
Definition: RTCP.hh:245
void RTCPAppHandlerFunc(void *clientData, u_int8_t subtype, u_int32_t nameBytes, u_int8_t *appDependentData, unsigned appDependentDataSize)
Definition: RTCP.hh:45
const unsigned char RTCP_PT_SDES
Definition: RTCP.hh:228
const unsigned char RTCP_PT_RTPFB
Definition: RTCP.hh:231
const unsigned char RTCP_SDES_CNAME
Definition: RTCP.hh:241
const unsigned char RTCP_PT_PSFB
Definition: RTCP.hh:232
const unsigned char RTCP_PT_APP
Definition: RTCP.hh:230
const unsigned char RTCP_SDES_PRIV
Definition: RTCP.hh:248
const unsigned char RTCP_PT_SR
Definition: RTCP.hh:226
const unsigned char RTCP_PT_AVB
Definition: RTCP.hh:234
const unsigned char RTCP_PT_IDMS
Definition: RTCP.hh:237
const unsigned char RTCP_PT_XR
Definition: RTCP.hh:233
const unsigned char RTCP_PT_TOKEN
Definition: RTCP.hh:236
const unsigned char RTCP_PT_RR
Definition: RTCP.hh:227
const unsigned char RTCP_SDES_EMAIL
Definition: RTCP.hh:243
const unsigned char RTCP_PT_BYE
Definition: RTCP.hh:229
const unsigned char RTCP_SDES_TOOL
Definition: RTCP.hh:246
const unsigned char RTCP_PT_RSI
Definition: RTCP.hh:235
const unsigned char RTCP_SDES_NAME
Definition: RTCP.hh:242
void AuxHandlerFunc(void *clientData, unsigned char *packet, unsigned &packetSize)
Definition: RTPInterface.hh:38
#define NULL
void TaskFunc(void *clientData)
Definition: Media.hh:50
char const * name() const
Definition: Media.hh:61
Boolean fIsSSMTransmitter
Definition: RTCP.hh:178
int receivedPacketSize()
Definition: RTCP.hh:219
void reschedule(double nextTime)
void enqueueReportBlock(RTPReceptionStats *receptionStats)
int fIsInitial
Definition: RTCP.hh:186
double fPrevReportTime
Definition: RTCP.hh:187
RTCPAppHandlerFunc * fAppHandlerTask
Definition: RTCP.hh:208
void incomingReportHandler1()
int fTypeOfPacket
Definition: RTCP.hh:195
void setupForSRTCP()
void unsetSpecificRRHandler(struct sockaddr_storage const &fromAddress, Port fromPort)
void injectReport(u_int8_t const *packet, unsigned packetSize, struct sockaddr_storage const &fromAddress)
static RTCPInstance * createNew(UsageEnvironment &env, Groupsock *RTCPgs, unsigned totSessionBW, unsigned char const *cname, RTPSink *sink, RTPSource *source, Boolean isSSMTransmitter=False, SRTPCryptographicContext *crypto=NULL)
double fAveRTCPSize
Definition: RTCP.hh:185
void addStreamSocket(int sockNum, unsigned char streamChannelId, TLSState *tlsState)
void setByeWithReasonHandler(ByeWithReasonHandlerFunc *handlerTask, void *clientData, Boolean handleActiveParticipantsOnly=True)
RTCPMemberDatabase * fKnownMembers
Definition: RTCP.hh:182
void addBYE(char const *reason)
int fPrevNumMembers
Definition: RTCP.hh:189
Definition: RTCP.hh:181
int fTypeOfEvent
Definition: RTCP.hh:194
void setByeHandler(TaskFunc *handlerTask, void *clientData, Boolean handleActiveParticipantsOnly=True)
Boolean addReport(Boolean alwaysAdd=False)
TaskFunc * fRRHandlerTask
Definition: RTCP.hh:205
OutPacketBuffer * fOutBuf
Definition: RTCP.hh:173
void enqueueCommonReportPrefix(unsigned char packetType, u_int32_t SSRC, unsigned numExtraWords=0)
void setSpecificRRHandler(struct sockaddr_storage const &fromAddress, Port fromPort, TaskFunc *handlerTask, void *clientData)
u_int32_t fLastReceivedSSRC
Definition: RTCP.hh:193
static Boolean lookupByName(UsageEnvironment &env, char const *instanceName, RTCPInstance *&resultInstance)
virtual void noteArrivingRR(struct sockaddr_storage const &fromAddressAndPort, int tcpSocketNum, unsigned char tcpStreamChannelId)
RTPSink * fSink
Definition: RTCP.hh:176
int checkNewSSRC()
unsigned fOutgoingReportCount
Definition: RTCP.hh:183
SRTPCryptographicContext * fCrypto
Definition: RTCP.hh:179
virtual Boolean isRTCPInstance() const
void sendAppPacket(u_int8_t subtype, char const *name, u_int8_t *appDependentData, unsigned appDependentDataSize)
RTPSource * fSource
Definition: RTCP.hh:177
void onExpire1()
u_int8_t * fInBuf
Definition: RTCP.hh:171
AddressPortLookupTable * fSpecificRRHandlerTable
Definition: RTCP.hh:207
void setAppHandler(RTCPAppHandlerFunc *handlerTask, void *clientData)
ByeWithReasonHandlerFunc * fByeWithReasonHandlerTask
Definition: RTCP.hh:200
static void onExpire(RTCPInstance *instance)
void addSDES()
unsigned numMembers() const
void sendReport()
void setRRHandler(TaskFunc *handlerTask, void *clientData)
RTPInterface fRTCPInterface
Definition: RTCP.hh:174
void processIncomingReport(unsigned packetSize, struct sockaddr_storage const &fromAddressAndPort, int tcpSocketNum, unsigned char tcpStreamChannelId)
void sendBuiltPacket()
Boolean fHaveJustSentPacket
Definition: RTCP.hh:196
int fLastReceivedSize
Definition: RTCP.hh:192
void schedule(double nextTime)
void removeSSRC(u_int32_t ssrc, Boolean alsoRemoveStats)
static void incomingReportHandler(RTCPInstance *instance, int)
void setAuxilliaryReadHandler(AuxHandlerFunc *handlerFunc, void *handlerClientData)
Definition: RTCP.hh:122
void removeLastReceivedSSRC()
void setSRHandler(TaskFunc *handlerTask, void *clientData)
void * fByeHandlerClientData
Definition: RTCP.hh:201
virtual ~RTCPInstance()
int packetType()
Definition: RTCP.hh:218
void onReceive(int typeOfPacket, int totPacketSize, u_int32_t ssrc)
unsigned fTotSessionBW
Definition: RTCP.hh:175
void * fRRHandlerClientData
Definition: RTCP.hh:206
void * fSRHandlerClientData
Definition: RTCP.hh:204
int sentPacketSize()
Definition: RTCP.hh:217
void removeStreamSocket(int sockNum, unsigned char streamChannelId)
Definition: RTCP.hh:117
void enqueueCommonReportSuffix()
int typeOfEvent()
Definition: RTCP.hh:216
unsigned totSessionBW() const
Definition: RTCP.hh:67
TaskFunc * fSRHandlerTask
Definition: RTCP.hh:203
RTCPInstance(UsageEnvironment &env, Groupsock *RTPgs, unsigned totSessionBW, unsigned char const *cname, RTPSink *sink, RTPSource *source, Boolean isSSMTransmitter, SRTPCryptographicContext *crypto)
TaskFunc * fByeHandlerTask
Definition: RTCP.hh:199
unsigned fNumBytesAlreadyRead
Definition: RTCP.hh:172
unsigned fLastPacketSentSize
Definition: RTCP.hh:197
Boolean fByeHandleActiveParticipantsOnly
Definition: RTCP.hh:202
Groupsock * RTCPgs() const
Definition: RTCP.hh:113
double fNextReportTime
Definition: RTCP.hh:188
void * fAppHandlerClientData
Definition: RTCP.hh:209
void sendBYE(char const *reason=NULL)
int fLastSentSize
Definition: RTCP.hh:191
void setStreamSocket(int sockNum, unsigned char streamChannelId, TLSState *tlsState)
void removeStreamSocket(int sockNum, unsigned char streamChannelId)
void setAuxilliaryReadHandler(AuxHandlerFunc *handlerFunc, void *handlerClientData)
Definition: RTPInterface.hh:79
Groupsock * gs() const
Definition: RTPInterface.hh:51
Definition: RTCP.hh:34
unsigned char fData[2+0xFF]
Definition: RTCP.hh:42
SDESItem(unsigned char tag, unsigned char const *value)
unsigned totalSize() const
unsigned char const * data() const
Definition: RTCP.hh:38
void * packet