Merge remote-tracking branch 'origin/0.10'
[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., 59 Temple Place - Suite 330,
17  * Boston, MA 02111-1307, 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  * @src: the #RTPSource
89  * @buffer: the RTCP buffer ready for synchronisation
90  * @user_data: user data specified when registering
91  *
92  * This callback will be called when @sess has an SR @buffer ready for doing
93  * synchronisation between streams.
94  *
95  * Returns: a #GstFlowReturn.
96  */
97 typedef GstFlowReturn (*RTPSessionSyncRTCP) (RTPSession *sess, RTPSource *src, GstBuffer *buffer, gpointer user_data);
98
99 /**
100  * RTPSessionClockRate:
101  * @sess: an #RTPSession
102  * @payload: the payload
103  * @user_data: user data specified when registering
104  *
105  * This callback will be called when @sess needs the clock-rate of @payload.
106  *
107  * Returns: the clock-rate of @pt.
108  */
109 typedef gint (*RTPSessionClockRate) (RTPSession *sess, guint8 payload, gpointer user_data);
110
111 /**
112  * RTPSessionReconsider:
113  * @sess: an #RTPSession
114  * @user_data: user data specified when registering
115  *
116  * This callback will be called when @sess needs to cancel the current timeout. 
117  * The currently running timeout should be canceled and a new reporting interval
118  * should be requested from @sess.
119  */
120 typedef void (*RTPSessionReconsider) (RTPSession *sess, gpointer user_data);
121
122 /**
123  * RTPSessionRequestKeyUnit:
124  * @sess: an #RTPSession
125  * @all_headers: %TRUE if "all-headers" property should be set on the key unit
126  *  request
127  * @user_data: user data specified when registering
128 *
129  * Asks the encoder to produce a key unit as soon as possibly within the
130  * bandwidth constraints
131  */
132 typedef void (*RTPSessionRequestKeyUnit) (RTPSession *sess,
133     gboolean all_headers, gpointer user_data);
134
135 /**
136  * RTPSessionRequestTime:
137  * @sess: an #RTPSession
138  * @user_data: user data specified when registering
139  *
140  * This callback will be called when @sess needs the current time. The time
141  * should be returned as a #GstClockTime
142  */
143 typedef GstClockTime (*RTPSessionRequestTime) (RTPSession *sess,
144     gpointer user_data);
145
146 /**
147  * RTPSessionCallbacks:
148  * @RTPSessionProcessRTP: callback to process RTP packets
149  * @RTPSessionSendRTP: callback for sending RTP packets
150  * @RTPSessionSendRTCP: callback for sending RTCP packets
151  * @RTPSessionSyncRTCP: callback for handling SR packets
152  * @RTPSessionReconsider: callback for reconsidering the timeout
153  * @RTPSessionRequestKeyUnit: callback for requesting a new key unit
154  *
155  * These callbacks can be installed on the session manager to get notification
156  * when RTP and RTCP packets are ready for further processing. These callbacks
157  * are not implemented with signals for performance reasons.
158  */
159 typedef struct {
160   RTPSessionProcessRTP  process_rtp;
161   RTPSessionSendRTP     send_rtp;
162   RTPSessionSyncRTCP    sync_rtcp;
163   RTPSessionSendRTCP    send_rtcp;
164   RTPSessionClockRate   clock_rate;
165   RTPSessionReconsider  reconsider;
166   RTPSessionRequestKeyUnit request_key_unit;
167   RTPSessionRequestTime request_time;
168 } RTPSessionCallbacks;
169
170 /**
171  * RTPSession:
172  * @lock: lock to protect the session
173  * @source: the source of this session
174  * @ssrcs: Hashtable of sources indexed by SSRC
175  * @cnames: Hashtable of sources indexed by CNAME
176  * @num_sources: the number of sources
177  * @activecount: the number of active sources
178  * @callbacks: callbacks
179  * @user_data: user data passed in callbacks
180  * @stats: session statistics
181  *
182  * The RTP session manager object
183  */
184 struct _RTPSession {
185   GObject       object;
186
187   GMutex        lock;
188
189   guint         header_len;
190   guint         mtu;
191
192   /* bandwidths */
193   gboolean     recalc_bandwidth;
194   guint        bandwidth;
195   gdouble      rtcp_bandwidth;
196   guint        rtcp_rr_bandwidth;
197   guint        rtcp_rs_bandwidth;
198
199   RTPSource    *source;
200
201   /* for sender/receiver counting */
202   guint32       key;
203   guint32       mask_idx;
204   guint32       mask;
205   GHashTable   *ssrcs[32];
206   GHashTable   *cnames;
207   guint         total_sources;
208
209   GstClockTime  next_rtcp_check_time;
210   GstClockTime  last_rtcp_send_time;
211   GstClockTime  start_time;
212   gboolean      first_rtcp;
213   gboolean      allow_early;
214
215   GstClockTime  next_early_rtcp_time;
216
217   gchar        *bye_reason;
218   gboolean      sent_bye;
219
220   RTPSessionCallbacks   callbacks;
221   gpointer              process_rtp_user_data;
222   gpointer              send_rtp_user_data;
223   gpointer              send_rtcp_user_data;
224   gpointer              sync_rtcp_user_data;
225   gpointer              clock_rate_user_data;
226   gpointer              reconsider_user_data;
227   gpointer              request_key_unit_user_data;
228   gpointer              request_time_user_data;
229
230   RTPSessionStats stats;
231
232   gboolean      change_ssrc;
233   gboolean      favor_new;
234   GstClockTime  rtcp_feedback_retention_window;
235   guint         rtcp_immediate_feedback_threshold;
236
237   GstClockTime last_keyframe_request;
238   gboolean     last_keyframe_all_headers;
239 };
240
241 /**
242  * RTPSessionClass:
243  * @on_new_ssrc: emited when a new source is found
244  * @on_bye_ssrc: emited when a source is gone
245  *
246  * The session class.
247  */
248 struct _RTPSessionClass {
249   GObjectClass   parent_class;
250
251   /* action signals */
252   RTPSource* (*get_source_by_ssrc) (RTPSession *sess, guint32 ssrc);
253
254   /* signals */
255   void (*on_new_ssrc)       (RTPSession *sess, RTPSource *source);
256   void (*on_ssrc_collision) (RTPSession *sess, RTPSource *source);
257   void (*on_ssrc_validated) (RTPSession *sess, RTPSource *source);
258   void (*on_ssrc_active)    (RTPSession *sess, RTPSource *source);
259   void (*on_ssrc_sdes)      (RTPSession *sess, RTPSource *source);
260   void (*on_bye_ssrc)       (RTPSession *sess, RTPSource *source);
261   void (*on_bye_timeout)    (RTPSession *sess, RTPSource *source);
262   void (*on_timeout)        (RTPSession *sess, RTPSource *source);
263   void (*on_sender_timeout) (RTPSession *sess, RTPSource *source);
264   gboolean (*on_sending_rtcp) (RTPSession *sess, GstBuffer *buffer,
265       gboolean early);
266   void (*on_feedback_rtcp)  (RTPSession *sess, guint type, guint fbtype,
267       guint sender_ssrc, guint media_ssrc, GstBuffer *fci);
268   void (*send_rtcp)         (RTPSession *sess, GstClockTimeDiff max_delay);
269 };
270
271 GType rtp_session_get_type (void);
272
273 /* create and configure */
274 RTPSession*     rtp_session_new           (void);
275 void            rtp_session_set_callbacks          (RTPSession *sess,
276                                                     RTPSessionCallbacks *callbacks,
277                                                     gpointer user_data);
278 void            rtp_session_set_process_rtp_callback   (RTPSession * sess,
279                                                     RTPSessionProcessRTP callback,
280                                                     gpointer user_data);
281 void            rtp_session_set_send_rtp_callback  (RTPSession * sess,
282                                                     RTPSessionSendRTP callback,
283                                                     gpointer user_data);
284 void            rtp_session_set_send_rtcp_callback   (RTPSession * sess,
285                                                     RTPSessionSendRTCP callback,
286                                                     gpointer user_data);
287 void            rtp_session_set_sync_rtcp_callback   (RTPSession * sess,
288                                                     RTPSessionSyncRTCP callback,
289                                                     gpointer user_data);
290 void            rtp_session_set_clock_rate_callback   (RTPSession * sess,
291                                                     RTPSessionClockRate callback,
292                                                     gpointer user_data);
293 void            rtp_session_set_reconsider_callback (RTPSession * sess,
294                                                     RTPSessionReconsider callback,
295                                                     gpointer user_data);
296 void            rtp_session_set_request_time_callback (RTPSession * sess,
297                                                     RTPSessionRequestTime callback,
298                                                     gpointer user_data);
299
300 void            rtp_session_set_bandwidth          (RTPSession *sess, gdouble bandwidth);
301 gdouble         rtp_session_get_bandwidth          (RTPSession *sess);
302 void            rtp_session_set_rtcp_fraction      (RTPSession *sess, gdouble fraction);
303 gdouble         rtp_session_get_rtcp_fraction      (RTPSession *sess);
304
305 gboolean        rtp_session_set_sdes_string        (RTPSession *sess, GstRTCPSDESType type,
306                                                     const gchar *cname);
307 gchar*          rtp_session_get_sdes_string        (RTPSession *sess, GstRTCPSDESType type);
308
309 GstStructure *  rtp_session_get_sdes_struct        (RTPSession *sess);
310 void            rtp_session_set_sdes_struct        (RTPSession *sess, const GstStructure *sdes);
311
312 /* handling sources */
313 RTPSource*      rtp_session_get_internal_source    (RTPSession *sess);
314
315 void            rtp_session_set_internal_ssrc      (RTPSession *sess, guint32 ssrc);
316 guint32         rtp_session_get_internal_ssrc      (RTPSession *sess);
317
318 gboolean        rtp_session_add_source             (RTPSession *sess, RTPSource *src);
319 guint           rtp_session_get_num_sources        (RTPSession *sess);
320 guint           rtp_session_get_num_active_sources (RTPSession *sess);
321 RTPSource*      rtp_session_get_source_by_ssrc     (RTPSession *sess, guint32 ssrc);
322 RTPSource*      rtp_session_get_source_by_cname    (RTPSession *sess, const gchar *cname);
323 RTPSource*      rtp_session_create_source          (RTPSession *sess);
324
325 /* processing packets from receivers */
326 GstFlowReturn   rtp_session_process_rtp            (RTPSession *sess, GstBuffer *buffer,
327                                                     GstClockTime current_time,
328                                                     GstClockTime running_time);
329 GstFlowReturn   rtp_session_process_rtcp           (RTPSession *sess, GstBuffer *buffer,
330                                                     GstClockTime current_time,
331                                                     guint64 ntpnstime);
332
333 /* processing packets for sending */
334 GstFlowReturn   rtp_session_send_rtp               (RTPSession *sess, gpointer data, gboolean is_list,
335                                                     GstClockTime current_time, GstClockTime running_time);
336
337 /* stopping the session */
338 GstFlowReturn   rtp_session_schedule_bye           (RTPSession *sess, const gchar *reason,
339                                                     GstClockTime current_time);
340
341 /* get interval for next RTCP interval */
342 GstClockTime    rtp_session_next_timeout           (RTPSession *sess, GstClockTime current_time);
343 GstFlowReturn   rtp_session_on_timeout             (RTPSession *sess, GstClockTime current_time,
344                                                     guint64 ntpnstime, GstClockTime running_time);
345
346 /* request the transmittion of an early RTCP packet */
347 void            rtp_session_request_early_rtcp     (RTPSession * sess, GstClockTime current_time,
348                                                     GstClockTimeDiff max_delay);
349
350 /* Notify session of a request for a new key unit */
351 gboolean        rtp_session_request_key_unit       (RTPSession * sess,
352                                                     guint32 ssrc,
353                                                     GstClockTime now,
354                                                     gboolean fir,
355                                                     gint count);
356
357 #endif /* __RTP_SESSION_H__ */