session: produce RTCP for all internal sources
[platform/upstream/gst-plugins-good.git] / gst / rtpmanager / rtpsession.h
1 /* GStreamer
2  * Copyright (C) <2007> Wim Taymans <wim.taymans@gmail.com>
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18  */
19
20 #ifndef __RTP_SESSION_H__
21 #define __RTP_SESSION_H__
22
23 #include <gst/gst.h>
24
25 #include "rtpsource.h"
26
27 typedef struct _RTPSession RTPSession;
28 typedef struct _RTPSessionClass RTPSessionClass;
29
30 #define RTP_TYPE_SESSION             (rtp_session_get_type())
31 #define RTP_SESSION(sess)            (G_TYPE_CHECK_INSTANCE_CAST((sess),RTP_TYPE_SESSION,RTPSession))
32 #define RTP_SESSION_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),RTP_TYPE_SESSION,RTPSessionClass))
33 #define RTP_IS_SESSION(sess)         (G_TYPE_CHECK_INSTANCE_TYPE((sess),RTP_TYPE_SESSION))
34 #define RTP_IS_SESSION_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),RTP_TYPE_SESSION))
35 #define RTP_SESSION_CAST(sess)       ((RTPSession *)(sess))
36
37 #define RTP_SESSION_LOCK(sess)     (g_mutex_lock (&(sess)->lock))
38 #define RTP_SESSION_UNLOCK(sess)   (g_mutex_unlock (&(sess)->lock))
39
40 /**
41  * RTPSessionProcessRTP:
42  * @sess: an #RTPSession
43  * @src: the #RTPSource
44  * @buffer: the RTP buffer ready for processing
45  * @user_data: user data specified when registering
46  *
47  * This callback will be called when @sess has @buffer ready for further
48  * processing. Processing the buffer typically includes decoding and displaying
49  * the buffer.
50  *
51  * Returns: a #GstFlowReturn.
52  */
53 typedef GstFlowReturn (*RTPSessionProcessRTP) (RTPSession *sess, RTPSource *src, GstBuffer *buffer, gpointer user_data);
54
55 /**
56  * RTPSessionSendRTP:
57  * @sess: an #RTPSession
58  * @src: the #RTPSource
59  * @buffer: the RTP buffer ready for sending
60  * @user_data: user data specified when registering
61  *
62  * This callback will be called when @sess has @buffer ready for sending to
63  * all listening participants in this session.
64  *
65  * Returns: a #GstFlowReturn.
66  */
67 typedef GstFlowReturn (*RTPSessionSendRTP) (RTPSession *sess, RTPSource *src, gpointer data, gpointer user_data);
68
69 /**
70  * RTPSessionSendRTCP:
71  * @sess: an #RTPSession
72  * @src: the #RTPSource
73  * @buffer: the RTCP buffer ready for sending
74  * @eos: if an EOS event should be pushed
75  * @user_data: user data specified when registering
76  *
77  * This callback will be called when @sess has @buffer ready for sending to
78  * all listening participants in this session.
79  *
80  * Returns: a #GstFlowReturn.
81  */
82 typedef GstFlowReturn (*RTPSessionSendRTCP) (RTPSession *sess, RTPSource *src, GstBuffer *buffer,
83     gboolean eos, gpointer user_data);
84
85 /**
86  * RTPSessionSyncRTCP:
87  * @sess: an #RTPSession
88  * @buffer: the RTCP buffer ready for synchronisation
89  * @user_data: user data specified when registering
90  *
91  * This callback will be called when @sess has an SR @buffer ready for doing
92  * synchronisation between streams.
93  *
94  * Returns: a #GstFlowReturn.
95  */
96 typedef GstFlowReturn (*RTPSessionSyncRTCP) (RTPSession *sess, GstBuffer *buffer, gpointer user_data);
97
98 /**
99  * RTPSessionClockRate:
100  * @sess: an #RTPSession
101  * @payload: the payload
102  * @user_data: user data specified when registering
103  *
104  * This callback will be called when @sess needs the clock-rate of @payload.
105  *
106  * Returns: the clock-rate of @pt.
107  */
108 typedef gint (*RTPSessionClockRate) (RTPSession *sess, guint8 payload, gpointer user_data);
109
110 /**
111  * RTPSessionReconsider:
112  * @sess: an #RTPSession
113  * @user_data: user data specified when registering
114  *
115  * This callback will be called when @sess needs to cancel the current timeout.
116  * The currently running timeout should be canceled and a new reporting interval
117  * should be requested from @sess.
118  */
119 typedef void (*RTPSessionReconsider) (RTPSession *sess, gpointer user_data);
120
121 /**
122  * RTPSessionRequestKeyUnit:
123  * @sess: an #RTPSession
124  * @all_headers: %TRUE if "all-headers" property should be set on the key unit
125  *  request
126  * @user_data: user data specified when registering
127 *
128  * Asks the encoder to produce a key unit as soon as possibly within the
129  * bandwidth constraints
130  */
131 typedef void (*RTPSessionRequestKeyUnit) (RTPSession *sess,
132     gboolean all_headers, gpointer user_data);
133
134 /**
135  * RTPSessionRequestTime:
136  * @sess: an #RTPSession
137  * @user_data: user data specified when registering
138  *
139  * This callback will be called when @sess needs the current time. The time
140  * should be returned as a #GstClockTime
141  */
142 typedef GstClockTime (*RTPSessionRequestTime) (RTPSession *sess,
143     gpointer user_data);
144
145 /**
146  * RTPSessionCallbacks:
147  * @RTPSessionProcessRTP: callback to process RTP packets
148  * @RTPSessionSendRTP: callback for sending RTP packets
149  * @RTPSessionSendRTCP: callback for sending RTCP packets
150  * @RTPSessionSyncRTCP: callback for handling SR packets
151  * @RTPSessionReconsider: callback for reconsidering the timeout
152  * @RTPSessionRequestKeyUnit: callback for requesting a new key unit
153  *
154  * These callbacks can be installed on the session manager to get notification
155  * when RTP and RTCP packets are ready for further processing. These callbacks
156  * are not implemented with signals for performance reasons.
157  */
158 typedef struct {
159   RTPSessionProcessRTP  process_rtp;
160   RTPSessionSendRTP     send_rtp;
161   RTPSessionSyncRTCP    sync_rtcp;
162   RTPSessionSendRTCP    send_rtcp;
163   RTPSessionClockRate   clock_rate;
164   RTPSessionReconsider  reconsider;
165   RTPSessionRequestKeyUnit request_key_unit;
166   RTPSessionRequestTime request_time;
167 } RTPSessionCallbacks;
168
169 /**
170  * RTPSession:
171  * @lock: lock to protect the session
172  * @source: the source of this session
173  * @ssrcs: Hashtable of sources indexed by SSRC
174  * @num_sources: the number of sources
175  * @activecount: the number of active sources
176  * @callbacks: callbacks
177  * @user_data: user data passed in callbacks
178  * @stats: session statistics
179  *
180  * The RTP session manager object
181  */
182 struct _RTPSession {
183   GObject       object;
184
185   GMutex        lock;
186
187   guint         header_len;
188   guint         mtu;
189
190   GstStructure *sdes;
191
192   guint         probation;
193
194   /* bandwidths */
195   gboolean     recalc_bandwidth;
196   guint        bandwidth;
197   gdouble      rtcp_bandwidth;
198   guint        rtcp_rr_bandwidth;
199   guint        rtcp_rs_bandwidth;
200
201   RTPSource    *source;
202   guint32       suggested_ssrc;
203
204   /* for sender/receiver counting */
205   guint32       key;
206   guint32       mask_idx;
207   guint32       mask;
208   GHashTable   *ssrcs[32];
209   guint         total_sources;
210
211   GstClockTime  next_rtcp_check_time;
212   GstClockTime  last_rtcp_send_time;
213   GstClockTime  start_time;
214   gboolean      first_rtcp;
215   gboolean      allow_early;
216
217   GstClockTime  next_early_rtcp_time;
218
219   gboolean      scheduled_bye;
220
221   RTPSessionCallbacks   callbacks;
222   gpointer              process_rtp_user_data;
223   gpointer              send_rtp_user_data;
224   gpointer              send_rtcp_user_data;
225   gpointer              sync_rtcp_user_data;
226   gpointer              clock_rate_user_data;
227   gpointer              reconsider_user_data;
228   gpointer              request_key_unit_user_data;
229   gpointer              request_time_user_data;
230
231   RTPSessionStats stats;
232
233   gboolean      change_ssrc;
234   gboolean      favor_new;
235   GstClockTime  rtcp_feedback_retention_window;
236   guint         rtcp_immediate_feedback_threshold;
237
238   GstClockTime last_keyframe_request;
239   gboolean     last_keyframe_all_headers;
240 };
241
242 /**
243  * RTPSessionClass:
244  * @on_new_ssrc: emited when a new source is found
245  * @on_bye_ssrc: emited when a source is gone
246  *
247  * The session class.
248  */
249 struct _RTPSessionClass {
250   GObjectClass   parent_class;
251
252   /* action signals */
253   RTPSource* (*get_source_by_ssrc) (RTPSession *sess, guint32 ssrc);
254
255   /* signals */
256   void (*on_new_ssrc)       (RTPSession *sess, RTPSource *source);
257   void (*on_ssrc_collision) (RTPSession *sess, RTPSource *source);
258   void (*on_ssrc_validated) (RTPSession *sess, RTPSource *source);
259   void (*on_ssrc_active)    (RTPSession *sess, RTPSource *source);
260   void (*on_ssrc_sdes)      (RTPSession *sess, RTPSource *source);
261   void (*on_bye_ssrc)       (RTPSession *sess, RTPSource *source);
262   void (*on_bye_timeout)    (RTPSession *sess, RTPSource *source);
263   void (*on_timeout)        (RTPSession *sess, RTPSource *source);
264   void (*on_sender_timeout) (RTPSession *sess, RTPSource *source);
265   gboolean (*on_sending_rtcp) (RTPSession *sess, GstBuffer *buffer,
266       gboolean early);
267   void (*on_feedback_rtcp)  (RTPSession *sess, guint type, guint fbtype,
268       guint sender_ssrc, guint media_ssrc, GstBuffer *fci);
269   void (*send_rtcp)         (RTPSession *sess, GstClockTimeDiff max_delay);
270 };
271
272 GType rtp_session_get_type (void);
273
274 /* create and configure */
275 RTPSession*     rtp_session_new           (void);
276 void            rtp_session_set_callbacks          (RTPSession *sess,
277                                                     RTPSessionCallbacks *callbacks,
278                                                     gpointer user_data);
279 void            rtp_session_set_process_rtp_callback   (RTPSession * sess,
280                                                     RTPSessionProcessRTP callback,
281                                                     gpointer user_data);
282 void            rtp_session_set_send_rtp_callback  (RTPSession * sess,
283                                                     RTPSessionSendRTP callback,
284                                                     gpointer user_data);
285 void            rtp_session_set_send_rtcp_callback   (RTPSession * sess,
286                                                     RTPSessionSendRTCP callback,
287                                                     gpointer user_data);
288 void            rtp_session_set_sync_rtcp_callback   (RTPSession * sess,
289                                                     RTPSessionSyncRTCP callback,
290                                                     gpointer user_data);
291 void            rtp_session_set_clock_rate_callback   (RTPSession * sess,
292                                                     RTPSessionClockRate callback,
293                                                     gpointer user_data);
294 void            rtp_session_set_reconsider_callback (RTPSession * sess,
295                                                     RTPSessionReconsider callback,
296                                                     gpointer user_data);
297 void            rtp_session_set_request_time_callback (RTPSession * sess,
298                                                     RTPSessionRequestTime callback,
299                                                     gpointer user_data);
300
301 void            rtp_session_set_bandwidth          (RTPSession *sess, gdouble bandwidth);
302 gdouble         rtp_session_get_bandwidth          (RTPSession *sess);
303 void            rtp_session_set_rtcp_fraction      (RTPSession *sess, gdouble fraction);
304 gdouble         rtp_session_get_rtcp_fraction      (RTPSession *sess);
305
306 GstStructure *  rtp_session_get_sdes_struct        (RTPSession *sess);
307 void            rtp_session_set_sdes_struct        (RTPSession *sess, const GstStructure *sdes);
308
309 /* handling sources */
310 guint32         rtp_session_suggest_ssrc           (RTPSession *sess);
311
312 gboolean        rtp_session_add_source             (RTPSession *sess, RTPSource *src);
313 guint           rtp_session_get_num_sources        (RTPSession *sess);
314 guint           rtp_session_get_num_active_sources (RTPSession *sess);
315 RTPSource*      rtp_session_get_source_by_ssrc     (RTPSession *sess, guint32 ssrc);
316 RTPSource*      rtp_session_create_source          (RTPSession *sess);
317
318 /* processing packets from receivers */
319 GstFlowReturn   rtp_session_process_rtp            (RTPSession *sess, GstBuffer *buffer,
320                                                     GstClockTime current_time,
321                                                     GstClockTime running_time);
322 GstFlowReturn   rtp_session_process_rtcp           (RTPSession *sess, GstBuffer *buffer,
323                                                     GstClockTime current_time,
324                                                     guint64 ntpnstime);
325
326 /* processing packets for sending */
327 void            rtp_session_update_send_caps       (RTPSession *sess, GstCaps *caps);
328 GstFlowReturn   rtp_session_send_rtp               (RTPSession *sess, gpointer data, gboolean is_list,
329                                                     GstClockTime current_time, GstClockTime running_time);
330
331 /* scheduling bye */
332 void            rtp_session_mark_all_bye           (RTPSession *sess, const gchar *reason);
333 GstFlowReturn   rtp_session_schedule_bye           (RTPSession *sess, GstClockTime current_time);
334
335 /* get interval for next RTCP interval */
336 GstClockTime    rtp_session_next_timeout           (RTPSession *sess, GstClockTime current_time);
337 GstFlowReturn   rtp_session_on_timeout             (RTPSession *sess, GstClockTime current_time,
338                                                     guint64 ntpnstime, GstClockTime running_time);
339
340 /* request the transmittion of an early RTCP packet */
341 void            rtp_session_request_early_rtcp     (RTPSession * sess, GstClockTime current_time,
342                                                     GstClockTimeDiff max_delay);
343
344 /* Notify session of a request for a new key unit */
345 gboolean        rtp_session_request_key_unit       (RTPSession * sess,
346                                                     guint32 ssrc,
347                                                     GstClockTime now,
348                                                     gboolean fir,
349                                                     gint count);
350
351 #endif /* __RTP_SESSION_H__ */