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-2021 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 setByeHandler(TaskFunc* handlerTask, void* clientData,
70  Boolean handleActiveParticipantsOnly = True);
71  // Assigns a handler routine to be called if a "BYE" arrives.
72  // The handler is called once only; for subsequent "BYE"s,
73  // "setByeHandler()" would need to be called again.
74  // If "handleActiveParticipantsOnly" is True, then the handler is called
75  // only if the SSRC is for a known sender (if we have a "RTPSource"),
76  // or if the SSRC is for a known receiver (if we have a "RTPSink").
77  // This prevents (for example) the handler for a multicast receiver being
78  // called if some other multicast receiver happens to exit.
79  // If "handleActiveParticipantsOnly" is False, then the handler is called
80  // for any incoming RTCP "BYE".
81  // (To remove an existing "BYE" handler, call "setByeHandler()" again, with a "handlerTask" of NULL.)
82  void setByeWithReasonHandler(ByeWithReasonHandlerFunc* handlerTask, void* clientData,
83  Boolean handleActiveParticipantsOnly = True);
84  // Like "setByeHandler()", except that a string 'reason for the bye' (received as part of
85  // the RTCP "BYE" packet) is passed to the handler function (along with "clientData").
86  // (The 'reason' parameter to the handler function will be a dynamically-allocated string,
87  // or NULL, and should be delete[]d by the handler function.)
88  void setSRHandler(TaskFunc* handlerTask, void* clientData);
89  void setRRHandler(TaskFunc* handlerTask, void* clientData);
90  // Assigns a handler routine to be called if a "SR" or "RR" packet
91  // (respectively) arrives. Unlike "setByeHandler()", the handler will
92  // be called once for each incoming "SR" or "RR". (To turn off handling,
93  // call the function again with "handlerTask" (and "clientData") as NULL.)
94  void setSpecificRRHandler(struct sockaddr_storage const& fromAddress, Port fromPort,
95  TaskFunc* handlerTask, void* clientData);
96  // Like "setRRHandler()", but applies only to "RR" packets that come from
97  // a specific source address and port. (Note that if both a specific
98  // and a general "RR" handler function is set, then both will be called.)
99  void unsetSpecificRRHandler(struct sockaddr_storage const& fromAddress, Port fromPort); // equivalent to setSpecificRRHandler(..., NULL, NULL);
100  void setAppHandler(RTCPAppHandlerFunc* handlerTask, void* clientData);
101  // Assigns a handler routine to be called whenever an "APP" packet arrives. (To turn off
102  // handling, call the function again with "handlerTask" (and "clientData") as NULL.)
103  void sendAppPacket(u_int8_t subtype, char const* name,
104  u_int8_t* appDependentData, unsigned appDependentDataSize);
105  // Sends a custom RTCP "APP" packet to the peer(s). The parameters correspond to their
106  // respective fields as described in the RTP/RTCP definition (RFC 3550).
107  // Note that only the low-order 5 bits of "subtype" are used, and only the first 4 bytes
108  // of "name" are used. (If "name" has fewer than 4 bytes, or is NULL,
109  // then the remaining bytes are '\0'.)
110 
111  Groupsock* RTCPgs() const { return fRTCPInterface.gs(); }
112 
113  void setStreamSocket(int sockNum, unsigned char streamChannelId);
114  void addStreamSocket(int sockNum, unsigned char streamChannelId);
115  void removeStreamSocket(int sockNum, unsigned char streamChannelId) {
116  fRTCPInterface.removeStreamSocket(sockNum, streamChannelId);
117  }
118  // hacks to allow sending RTP over TCP (RFC 2236, section 10.12)
119 
121  void* handlerClientData) {
123  handlerClientData);
124  }
125 
126  void injectReport(u_int8_t const* packet, unsigned packetSize, struct sockaddr_storage const& fromAddress);
127  // Allows an outside party to inject an RTCP report (from other than the network interface)
128 
129 protected:
131  unsigned char const* cname,
132  RTPSink* sink, RTPSource* source,
133  Boolean isSSMTransmitter,
134  SRTPCryptographicContext* crypto);
135  // called only by createNew()
136  virtual ~RTCPInstance();
137 
138  virtual void noteArrivingRR(struct sockaddr_storage const& fromAddressAndPort,
139  int tcpSocketNum, unsigned char tcpStreamChannelId);
140 
142 
143 private:
144  // redefined virtual functions:
145  virtual Boolean isRTCPInstance() const;
146 
147 private:
149  void addSR();
150  void addRR();
151  void enqueueCommonReportPrefix(unsigned char packetType, u_int32_t SSRC,
152  unsigned numExtraWords = 0);
154  void enqueueReportBlock(RTPReceptionStats* receptionStats);
155  void addSDES();
156  void addBYE(char const* reason);
157 
159 
160  static void onExpire(RTCPInstance* instance);
161  void onExpire1();
162 
163  static void incomingReportHandler(RTCPInstance* instance, int /*mask*/);
164  void processIncomingReport(unsigned packetSize, struct sockaddr_storage const& fromAddressAndPort,
165  int tcpSocketNum, unsigned char tcpStreamChannelId);
166  void onReceive(int typeOfPacket, int totPacketSize, u_int32_t ssrc);
167 
168 private:
169  u_int8_t* fInBuf;
173  unsigned fTotSessionBW;
178 
180  RTCPMemberDatabase* fKnownMembers;
181  unsigned fOutgoingReportCount; // used for SSRC member aging
182 
183  double fAveRTCPSize;
188 
191  u_int32_t fLastReceivedSSRC;
196 
208 
209 public: // because this stuff is used by an external "C" function
210  void schedule(double nextTime);
211  void reschedule(double nextTime);
212  void sendReport();
213  void sendBYE(char const* reason = NULL);
214  int typeOfEvent() {return fTypeOfEvent;}
216  int packetType() {return fTypeOfPacket;}
220  void removeSSRC(u_int32_t ssrc, Boolean alsoRemoveStats);
221 };
222 
223 // RTCP packet types:
224 const unsigned char RTCP_PT_SR = 200;
225 const unsigned char RTCP_PT_RR = 201;
226 const unsigned char RTCP_PT_SDES = 202;
227 const unsigned char RTCP_PT_BYE = 203;
228 const unsigned char RTCP_PT_APP = 204;
229 const unsigned char RTCP_PT_RTPFB = 205; // Generic RTP Feedback [RFC4585]
230 const unsigned char RTCP_PT_PSFB = 206; // Payload-specific [RFC4585]
231 const unsigned char RTCP_PT_XR = 207; // extended report [RFC3611]
232 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.]
233 const unsigned char RTCP_PT_RSI = 209; // Receiver Summary Information [RFC5760]
234 const unsigned char RTCP_PT_TOKEN = 210; // Port Mapping [RFC6284]
235 const unsigned char RTCP_PT_IDMS = 211; // IDMS Settings [RFC7272]
236 
237 // SDES tags:
238 const unsigned char RTCP_SDES_END = 0;
239 const unsigned char RTCP_SDES_CNAME = 1;
240 const unsigned char RTCP_SDES_NAME = 2;
241 const unsigned char RTCP_SDES_EMAIL = 3;
242 const unsigned char RTCP_SDES_PHONE = 4;
243 const unsigned char RTCP_SDES_LOC = 5;
244 const unsigned char RTCP_SDES_TOOL = 6;
245 const unsigned char RTCP_SDES_NOTE = 7;
246 const unsigned char RTCP_SDES_PRIV = 8;
247 
248 #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:245
const unsigned char RTCP_SDES_END
Definition: RTCP.hh:238
const unsigned char RTCP_SDES_PHONE
Definition: RTCP.hh:242
const unsigned char RTCP_SDES_LOC
Definition: RTCP.hh:243
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:226
const unsigned char RTCP_PT_RTPFB
Definition: RTCP.hh:229
const unsigned char RTCP_SDES_CNAME
Definition: RTCP.hh:239
const unsigned char RTCP_PT_PSFB
Definition: RTCP.hh:230
const unsigned char RTCP_PT_APP
Definition: RTCP.hh:228
const unsigned char RTCP_SDES_PRIV
Definition: RTCP.hh:246
const unsigned char RTCP_PT_SR
Definition: RTCP.hh:224
const unsigned char RTCP_PT_AVB
Definition: RTCP.hh:232
const unsigned char RTCP_PT_IDMS
Definition: RTCP.hh:235
const unsigned char RTCP_PT_XR
Definition: RTCP.hh:231
const unsigned char RTCP_PT_TOKEN
Definition: RTCP.hh:234
const unsigned char RTCP_PT_RR
Definition: RTCP.hh:225
const unsigned char RTCP_SDES_EMAIL
Definition: RTCP.hh:241
const unsigned char RTCP_PT_BYE
Definition: RTCP.hh:227
const unsigned char RTCP_SDES_TOOL
Definition: RTCP.hh:244
const unsigned char RTCP_PT_RSI
Definition: RTCP.hh:233
const unsigned char RTCP_SDES_NAME
Definition: RTCP.hh:240
void AuxHandlerFunc(void *clientData, unsigned char *packet, unsigned &packetSize)
Definition: RTPInterface.hh:35
#define NULL
void TaskFunc(void *clientData)
Definition: Media.hh:50
char const * name() const
Definition: Media.hh:61
Boolean fIsSSMTransmitter
Definition: RTCP.hh:176
int receivedPacketSize()
Definition: RTCP.hh:217
void reschedule(double nextTime)
void enqueueReportBlock(RTPReceptionStats *receptionStats)
int fIsInitial
Definition: RTCP.hh:184
double fPrevReportTime
Definition: RTCP.hh:185
RTCPAppHandlerFunc * fAppHandlerTask
Definition: RTCP.hh:206
void incomingReportHandler1()
int fTypeOfPacket
Definition: RTCP.hh:193
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:183
void setByeWithReasonHandler(ByeWithReasonHandlerFunc *handlerTask, void *clientData, Boolean handleActiveParticipantsOnly=True)
RTCPMemberDatabase * fKnownMembers
Definition: RTCP.hh:180
void addBYE(char const *reason)
int fPrevNumMembers
Definition: RTCP.hh:187
SDESItem fCNAME
Definition: RTCP.hh:179
int fTypeOfEvent
Definition: RTCP.hh:192
void setByeHandler(TaskFunc *handlerTask, void *clientData, Boolean handleActiveParticipantsOnly=True)
Boolean addReport(Boolean alwaysAdd=False)
TaskFunc * fRRHandlerTask
Definition: RTCP.hh:203
void addStreamSocket(int sockNum, unsigned char streamChannelId)
OutPacketBuffer * fOutBuf
Definition: RTCP.hh:171
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:191
Groupsock * RTCPgs() const
Definition: RTCP.hh:111
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:174
int checkNewSSRC()
unsigned fOutgoingReportCount
Definition: RTCP.hh:181
SRTPCryptographicContext * fCrypto
Definition: RTCP.hh:177
virtual Boolean isRTCPInstance() const
void sendAppPacket(u_int8_t subtype, char const *name, u_int8_t *appDependentData, unsigned appDependentDataSize)
RTPSource * fSource
Definition: RTCP.hh:175
void onExpire1()
u_int8_t * fInBuf
Definition: RTCP.hh:169
AddressPortLookupTable * fSpecificRRHandlerTable
Definition: RTCP.hh:205
void setAppHandler(RTCPAppHandlerFunc *handlerTask, void *clientData)
ByeWithReasonHandlerFunc * fByeWithReasonHandlerTask
Definition: RTCP.hh:198
static void onExpire(RTCPInstance *instance)
void addSDES()
unsigned numMembers() const
void sendReport()
void setRRHandler(TaskFunc *handlerTask, void *clientData)
RTPInterface fRTCPInterface
Definition: RTCP.hh:172
void processIncomingReport(unsigned packetSize, struct sockaddr_storage const &fromAddressAndPort, int tcpSocketNum, unsigned char tcpStreamChannelId)
void sendBuiltPacket()
Boolean fHaveJustSentPacket
Definition: RTCP.hh:194
int fLastReceivedSize
Definition: RTCP.hh:190
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:120
void removeLastReceivedSSRC()
void setSRHandler(TaskFunc *handlerTask, void *clientData)
void * fByeHandlerClientData
Definition: RTCP.hh:199
virtual ~RTCPInstance()
int packetType()
Definition: RTCP.hh:216
void onReceive(int typeOfPacket, int totPacketSize, u_int32_t ssrc)
void setStreamSocket(int sockNum, unsigned char streamChannelId)
unsigned fTotSessionBW
Definition: RTCP.hh:173
void * fRRHandlerClientData
Definition: RTCP.hh:204
void * fSRHandlerClientData
Definition: RTCP.hh:202
int sentPacketSize()
Definition: RTCP.hh:215
void removeStreamSocket(int sockNum, unsigned char streamChannelId)
Definition: RTCP.hh:115
void enqueueCommonReportSuffix()
int typeOfEvent()
Definition: RTCP.hh:214
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:201
RTCPInstance(UsageEnvironment &env, Groupsock *RTPgs, unsigned totSessionBW, unsigned char const *cname, RTPSink *sink, RTPSource *source, Boolean isSSMTransmitter, SRTPCryptographicContext *crypto)
TaskFunc * fByeHandlerTask
Definition: RTCP.hh:197
unsigned fNumBytesAlreadyRead
Definition: RTCP.hh:170
unsigned fLastPacketSentSize
Definition: RTCP.hh:195
Boolean fByeHandleActiveParticipantsOnly
Definition: RTCP.hh:200
double fNextReportTime
Definition: RTCP.hh:186
void * fAppHandlerClientData
Definition: RTCP.hh:207
void sendBYE(char const *reason=NULL)
int fLastSentSize
Definition: RTCP.hh:189
void removeStreamSocket(int sockNum, unsigned char streamChannelId)
Groupsock * gs() const
Definition: RTPInterface.hh:48
void setAuxilliaryReadHandler(AuxHandlerFunc *handlerFunc, void *handlerClientData)
Definition: RTPInterface.hh:76
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