gst/rtpmanager/gstrtpdtmfmux.c

   1 /* RTP DTMF muxer element for GStreamer
   2  *
   3  * gstrtpdtmfmux.c:
   4  *
   5  * Copyright (C) <2007> Nokia Corporation.
   6  *   Contact: Zeeshan Ali <zeeshan.ali@nokia.com>
   7  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   8  *               2000,2005 Wim Taymans <wim@fluendo.com>
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Library General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Library General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Library General Public
  21  * License along with this library; if not, write to the
  22  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23  * Boston, MA 02111-1307, USA.
  24  */
  25
  26 /**
  27  * SECTION:element-rtpdtmfmux
  28  * @see_also: rtpdtmfsrc, dtmfsrc
  29  *
  30  * The RTPDTMFMuxer mixes/muxes RTP DTMF stream(s) into other RTP
  31  * streams. It does exactly what it's parent (RTPMuxer) does, except
  32  * that it allows upstream peer elements to request exclusive access
  33  * to the stream, which is required by the RTP DTMF standards (see RFC
  34  * 2833, section 3.2, para 1 for details). The peer upstream element
  35  * requests the acquisition and release of a stream lock beginning
  36  * using custom downstream gstreamer events. To request the acquisition
  37  * of the lock, the peer element must send an event of type
  38  * GST_EVENT_CUSTOM_DOWNSTREAM_OOB, having a
  39  * structure of name "stream-lock" with only one boolean field:
  40  * "lock". If this field is set to TRUE, the request is for the
  41  * acquisition of the lock, otherwise it is for release of the lock.
  42  *
  43  * For example, the following code in an upstream peer element
  44  * requests the acquisition of the stream lock:
  45  *
  46  * <programlisting>
  47  * GstEvent *event;
  48  * GstStructure *structure;
  49  * GstPad *srcpad;
  50  *
  51  * ... /\* srcpad initialization goes here \*\/
  52  *
  53  * structure = gst_structure_new ("stream-lock",
  54  *                    "lock", G_TYPE_BOOLEAN, TRUE, NULL);
  55  *
  56  * event = gst_event_new_custom (GST_EVENT_CUSTOM_DOWNSTREAM_OOB, structure);
  57  * gst_pad_push_event (dtmfsrc->srcpad, event);
  58  * </programlisting>
  59  *
  60  */
  61
  62 #ifdef HAVE_CONFIG_H
  63 #include "config.h"
  64 #endif
  65
  66 #include <gst/gst.h>
  67 #include <string.h>
  68
  69 #include "gstrtpdtmfmux.h"
  70
  71 GST_DEBUG_CATEGORY_STATIC (gst_rtp_dtmf_mux_debug);
  72 #define GST_CAT_DEFAULT gst_rtp_dtmf_mux_debug
  73
  74 /* elementfactory information */
  75 static const GstElementDetails gst_rtp_dtmf_mux_details =
  76 GST_ELEMENT_DETAILS ("RTP muxer",
  77     "Codec/Muxer",
  78     "mixes RTP DTMF streams into other RTP streams",
  79     "Zeeshan Ali <first.last@nokia.com>");
  80
  81 enum
  82 {
  83   SIGNAL_LOCKING_STREAM,
  84   SIGNAL_UNLOCKED_STREAM,
  85   LAST_SIGNAL
  86 };
  87
  88 static guint gst_rtpdtmfmux_signals[LAST_SIGNAL] = { 0 };
  89
  90 static void gst_rtp_dtmf_mux_dispose (GObject * object);
  91
  92 static void gst_rtp_dtmf_mux_release_pad (GstElement * element, GstPad * pad);
  93
  94 static gboolean gst_rtp_dtmf_mux_sink_event (GstPad * pad, GstEvent * event);
  95 static GstFlowReturn gst_rtp_dtmf_mux_chain (GstPad * pad, GstBuffer * buffer);
  96
  97 GST_BOILERPLATE (GstRTPDTMFMux, gst_rtp_dtmf_mux, GstRTPMux, GST_TYPE_RTP_MUX);
  98
  99 static void
 100 gst_rtp_dtmf_mux_init (GstRTPDTMFMux * object, GstRTPDTMFMuxClass * g_class)
 101 {
 102 }
 103
 104 static void
 105 gst_rtp_dtmf_mux_base_init (gpointer g_class)
 106 {
 107   GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
 108
 109   gst_element_class_set_details (element_class, &gst_rtp_dtmf_mux_details);
 110 }
 111
 112 static void
 113 gst_rtp_dtmf_mux_class_init (GstRTPDTMFMuxClass * klass)
 114 {
 115   GObjectClass *gobject_class;
 116   GstElementClass *gstelement_class;
 117   GstRTPMuxClass *gstrtpmux_class;
 118
 119   gobject_class = (GObjectClass *) klass;
 120   gstelement_class = (GstElementClass *) klass;
 121   gstrtpmux_class = (GstRTPMuxClass *) klass;
 122
 123   gst_rtpdtmfmux_signals[SIGNAL_LOCKING_STREAM] =
 124       g_signal_new ("locking", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 125       G_STRUCT_OFFSET (GstRTPDTMFMuxClass, locking), NULL, NULL,
 126       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 127
 128   gst_rtpdtmfmux_signals[SIGNAL_UNLOCKED_STREAM] =
 129       g_signal_new ("unlocked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 130       G_STRUCT_OFFSET (GstRTPDTMFMuxClass, unlocked), NULL, NULL,
 131       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 132
 133   gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_rtp_dtmf_mux_dispose);
 134   gstelement_class->release_pad =
 135       GST_DEBUG_FUNCPTR (gst_rtp_dtmf_mux_release_pad);
 136   gstrtpmux_class->chain_func = GST_DEBUG_FUNCPTR (gst_rtp_dtmf_mux_chain);
 137   gstrtpmux_class->sink_event_func =
 138       GST_DEBUG_FUNCPTR (gst_rtp_dtmf_mux_sink_event);
 139 }
 140
 141 static void
 142 gst_rtp_dtmf_mux_dispose (GObject * object)
 143 {
 144   GstRTPDTMFMux *mux;
 145
 146   mux = GST_RTP_DTMF_MUX (object);
 147
 148   GST_OBJECT_LOCK (mux);
 149   if (mux->special_pad != NULL) {
 150     gst_object_unref (mux->special_pad);
 151     mux->special_pad = NULL;
 152   }
 153   GST_OBJECT_UNLOCK (mux);
 154
 155   G_OBJECT_CLASS (parent_class)->dispose (object);
 156 }
 157
 158 static GstFlowReturn
 159 gst_rtp_dtmf_mux_chain (GstPad * pad, GstBuffer * buffer)
 160 {
 161   GstRTPDTMFMux *mux;
 162   GstFlowReturn ret;
 163
 164   mux = GST_RTP_DTMF_MUX (gst_pad_get_parent (pad));
 165
 166   GST_OBJECT_LOCK (mux);
 167   if (mux->special_pad != NULL && mux->special_pad != pad) {
 168     /* Drop the buffer */
 169     gst_buffer_unref (buffer);
 170     ret = GST_FLOW_OK;
 171     GST_OBJECT_UNLOCK (mux);
 172   }
 173
 174   else {
 175     GST_OBJECT_UNLOCK (mux);
 176     if (parent_class->chain_func)
 177       ret = parent_class->chain_func (pad, buffer);
 178     else {
 179       gst_buffer_unref (buffer);
 180       ret = GST_FLOW_ERROR;
 181     }
 182   }
 183
 184   gst_object_unref (mux);
 185   return ret;
 186 }
 187
 188 static void
 189 gst_rtp_dtmf_mux_lock_stream (GstRTPDTMFMux * mux, GstPad * pad)
 190 {
 191   if (mux->special_pad != NULL)
 192     GST_WARNING_OBJECT (mux,
 193         "Stream lock already acquired by pad %s",
 194         GST_ELEMENT_NAME (mux->special_pad));
 195
 196   else {
 197     GST_DEBUG_OBJECT (mux,
 198         "Stream lock acquired by pad %s", GST_ELEMENT_NAME (pad));
 199     mux->special_pad = gst_object_ref (pad);
 200   }
 201 }
 202
 203 static void
 204 gst_rtp_dtmf_mux_unlock_stream (GstRTPDTMFMux * mux, GstPad * pad)
 205 {
 206   if (mux->special_pad == NULL)
 207     GST_WARNING_OBJECT (mux, "Stream lock not acquired, can't release it");
 208
 209   else if (pad != mux->special_pad)
 210     GST_WARNING_OBJECT (mux,
 211         "pad %s attempted to release Stream lock"
 212         " which was acquired by pad %s", GST_ELEMENT_NAME (pad),
 213         GST_ELEMENT_NAME (mux->special_pad));
 214   else {
 215     GST_DEBUG_OBJECT (mux,
 216         "Stream lock released by pad %s", GST_ELEMENT_NAME (mux->special_pad));
 217     gst_object_unref (mux->special_pad);
 218     mux->special_pad = NULL;
 219   }
 220 }
 221
 222 static gboolean
 223 gst_rtp_dtmf_mux_handle_stream_lock_event (GstRTPDTMFMux * mux, GstPad * pad,
 224     const GstStructure * event_structure)
 225 {
 226   gboolean lock;
 227
 228   if (!gst_structure_get_boolean (event_structure, "lock", &lock))
 229     return FALSE;
 230
 231   if (lock)
 232     g_signal_emit (G_OBJECT (mux),
 233         gst_rtpdtmfmux_signals[SIGNAL_LOCKING_STREAM], 0, pad);
 234
 235   GST_OBJECT_LOCK (mux);
 236   if (lock)
 237     gst_rtp_dtmf_mux_lock_stream (mux, pad);
 238   else
 239     gst_rtp_dtmf_mux_unlock_stream (mux, pad);
 240   GST_OBJECT_UNLOCK (mux);
 241
 242   if (!lock)
 243     g_signal_emit (G_OBJECT (mux),
 244         gst_rtpdtmfmux_signals[SIGNAL_UNLOCKED_STREAM], 0, pad);
 245
 246   return TRUE;
 247 }
 248
 249 static gboolean
 250 gst_rtp_dtmf_mux_handle_downstream_event (GstRTPDTMFMux * mux,
 251     GstPad * pad, GstEvent * event)
 252 {
 253   const GstStructure *structure;
 254   gboolean ret = FALSE;
 255
 256   structure = gst_event_get_structure (event);
 257   /* FIXME: is this event generic enough to be given a generic name? */
 258   if (structure && gst_structure_has_name (structure, "stream-lock"))
 259     ret = gst_rtp_dtmf_mux_handle_stream_lock_event (mux, pad, structure);
 260
 261   return ret;
 262 }
 263
 264 static gboolean
 265 gst_rtp_dtmf_mux_ignore_event (GstPad * pad, GstEvent * event)
 266 {
 267   gboolean ret;
 268
 269   if (parent_class->sink_event_func)
 270     /* Give the parent a chance to handle the event first */
 271     ret = parent_class->sink_event_func (pad, event);
 272
 273   else
 274     ret = gst_pad_event_default (pad, event);
 275
 276   return ret;
 277 }
 278
 279 static gboolean
 280 gst_rtp_dtmf_mux_sink_event (GstPad * pad, GstEvent * event)
 281 {
 282   GstRTPDTMFMux *mux;
 283   GstEventType type;
 284   gboolean ret = FALSE;
 285
 286   type = event ? GST_EVENT_TYPE (event) : GST_EVENT_UNKNOWN;
 287
 288   mux = (GstRTPDTMFMux *) gst_pad_get_parent (pad);
 289
 290   switch (type) {
 291     case GST_EVENT_CUSTOM_DOWNSTREAM_OOB:
 292       ret = gst_rtp_dtmf_mux_handle_downstream_event (mux, pad, event);
 293       gst_event_unref (event);
 294       break;
 295     default:
 296       ret = gst_rtp_dtmf_mux_ignore_event (pad, event);
 297       break;
 298   }
 299
 300   gst_object_unref (mux);
 301   return ret;
 302 }
 303
 304 static void
 305 gst_rtp_dtmf_mux_release_pad (GstElement * element, GstPad * pad)
 306 {
 307   GstRTPDTMFMux *mux = GST_RTP_DTMF_MUX (element);
 308
 309   GST_OBJECT_LOCK (mux);
 310   if (mux->special_pad == pad) {
 311     gst_object_unref (mux->special_pad);
 312     mux->special_pad = NULL;
 313   }
 314   GST_OBJECT_UNLOCK (mux);
 315
 316   GST_CALL_PARENT (GST_ELEMENT_CLASS, release_pad, (element, pad));
 317 }
 318
 319 gboolean
 320 gst_rtp_dtmf_mux_plugin_init (GstPlugin * plugin)
 321 {
 322   GST_DEBUG_CATEGORY_INIT (gst_rtp_dtmf_mux_debug, "rtpdtmfmux", 0,
 323       "rtp dtmf muxer");
 324
 325   return gst_element_register (plugin, "rtpdtmfmux", GST_RANK_NONE,
 326       GST_TYPE_RTP_DTMF_MUX);
 327 }