live
RTCP.hh
Go to the documentation of this file.
1 /**********
2 This library is free software; you can redistribute it and/or modify it under
3 the terms of the GNU Lesser General Public License as published by the
4 Free Software Foundation; either version 3 of the License, or (at your
5 option) any later version. (See <http://www.gnu.org/copyleft/lesser.html>.)
6 
7 This library is distributed in the hope that it will be useful, but WITHOUT
8 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
9 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
10 more details.
11 
12 You should have received a copy of the GNU Lesser General Public License
13 along with this library; if not, write to the Free Software Foundation, Inc.,
14 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15 **********/
16 // "liveMedia"
17 // Copyright (c) 1996-2022 Live Networks, Inc. All rights reserved.
18 // RTCP
19 // C++ header
20 
21 #ifndef _RTCP_HH
22 #define _RTCP_HH
23 
24 #ifndef _RTP_SINK_HH
25 #include "RTPSink.hh"
26 #endif
27 #ifndef _RTP_SOURCE_HH
28 #include "RTPSource.hh"
29 #endif
30 #ifndef _SRTP_CRYPTOGRAPHIC_CONTEXT_HH
32 #endif
33 
34 class SDESItem {
35 public:
36  SDESItem(unsigned char tag, unsigned char const* value);
37 
38  unsigned char const* data() const {return fData;}
39  unsigned totalSize() const;
40 
41 private:
42  unsigned char fData[2 + 0xFF]; // first 2 bytes are tag and length
43 };
44 
45 typedef void RTCPAppHandlerFunc(void* clientData,
46  u_int8_t subtype, u_int32_t nameBytes/*big-endian order*/,
47  u_int8_t* appDependentData, unsigned appDependentDataSize);
48 
49 class RTCPMemberDatabase; // forward
50 
51 typedef void ByeWithReasonHandlerFunc(void* clientData, char const* reason);
52 
53 class RTCPInstance: public Medium {
54 public:
56  unsigned totSessionBW, /* in kbps */
57  unsigned char const* cname,
58  RTPSink* sink,
59  RTPSource* source,
60  Boolean isSSMTransmitter = False,
61  SRTPCryptographicContext* crypto = NULL);
62 
63  static Boolean lookupByName(UsageEnvironment& env, char const* instanceName,
64  RTCPInstance*& resultInstance);
65 
66  unsigned numMembers() const;
67  unsigned totSessionBW() const { return fTotSessionBW; }
68 
69  void setupForSRTCP();
70 
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'.)
112 
113  Groupsock* RTCPgs() const { return fRTCPInterface.gs(); }
114 
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)
121 
123  void* handlerClientData) {
125  handlerClientData);
126  }
127 
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)
130 
131 protected:
133  unsigned char const* cname,
134  RTPSink* sink, RTPSource* source,
135  Boolean isSSMTransmitter,
136  SRTPCryptographicContext* crypto);
137  // called only by createNew()
138  virtual ~RTCPInstance();
139 
140  virtual void noteArrivingRR(struct sockaddr_storage const& fromAddressAndPort,
141  int tcpSocketNum, unsigned char tcpStreamChannelId);
142 
144 
145 private:
146  // redefined virtual functions:
147  virtual Boolean isRTCPInstance() const;
148 
149 private:
151  void addSR();
152  void addRR();
153  void enqueueCommonReportPrefix(unsigned char packetType, u_int32_t SSRC,
154  unsigned numExtraWords = 0);
156  void enqueueReportBlock(RTPReceptionStats* receptionStats);
157  void addSDES();
158  void addBYE(char const* reason);
159 
161 
162  static void onExpire(RTCPInstance* instance);
163  void onExpire1();
164 
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);
169 
170 private:
171  u_int8_t* fInBuf;
175  unsigned fTotSessionBW;
180 
182  RTCPMemberDatabase* fKnownMembers;
183  unsigned fOutgoingReportCount; // used for SSRC member aging
184 
185  double fAveRTCPSize;
190 
193  u_int32_t fLastReceivedSSRC;
198 
210 
211 public: // because this stuff is used by an external "C" function
212  void schedule(double nextTime);
213  void reschedule(double nextTime);
214  void sendReport();
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);
223 };
224 
225 // RTCP packet types:
226 const unsigned char RTCP_PT_SR = 200;
227 const unsigned char RTCP_PT_RR = 201;
228 const unsigned char RTCP_PT_SDES = 202;
229 const unsigned char RTCP_PT_BYE = 203;
230 const unsigned char RTCP_PT_APP = 204;
231 const unsigned char RTCP_PT_RTPFB = 205; // Generic RTP Feedback [RFC4585]
232 const unsigned char RTCP_PT_PSFB = 206; // Payload-specific [RFC4585]
233 const unsigned char RTCP_PT_XR = 207; // extended report [RFC3611]
234 const 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.]
235 const unsigned char RTCP_PT_RSI = 209; // Receiver Summary Information [RFC5760]
236 const unsigned char RTCP_PT_TOKEN = 210; // Port Mapping [RFC6284]
237 const unsigned char RTCP_PT_IDMS = 211; // IDMS Settings [RFC7272]
238 
239 // SDES tags:
240 const unsigned char RTCP_SDES_END = 0;
241 const unsigned char RTCP_SDES_CNAME = 1;
242 const unsigned char RTCP_SDES_NAME = 2;
243 const unsigned char RTCP_SDES_EMAIL = 3;
244 const unsigned char RTCP_SDES_PHONE = 4;
245 const unsigned char RTCP_SDES_LOC = 5;
246 const unsigned char RTCP_SDES_TOOL = 6;
247 const unsigned char RTCP_SDES_NOTE = 7;
248 const unsigned char RTCP_SDES_PRIV = 8;
249 
250 #endif
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)
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
SDESItem fCNAME
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
Groupsock * RTCPgs() const
Definition: RTCP.hh:113
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
static RTCPInstance * createNew(UsageEnvironment &env, Groupsock *RTCPgs, unsigned totSessionBW, unsigned char const *cname, RTPSink *sink, RTPSource *source, Boolean isSSMTransmitter=False, SRTPCryptographicContext *crypto=NULL)
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
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)
Groupsock * gs() const
Definition: RTPInterface.hh:51
void setAuxilliaryReadHandler(AuxHandlerFunc *handlerFunc, void *handlerClientData)
Definition: RTPInterface.hh:79
Definition: RTCP.hh:34
unsigned char fData[2+0xFF]
Definition: RTCP.hh:42
unsigned char const * data() const
Definition: RTCP.hh:38
SDESItem(unsigned char tag, unsigned char const *value)
unsigned totalSize() const
void * packet