API: add gst_mixer_options_list_changed(), gst_mixer_mixer_changed() and gst_mixer_message_parse_options_list_changed...

Original commit message from CVS:
* docs/libs/gst-plugins-base-libs-sections.txt:
* gst-libs/gst/interfaces/mixer.c: (gst_mixer_option_changed),
(gst_mixer_options_list_changed), (gst_mixer_mixer_changed),
(gst_mixer_message_get_type),
(gst_mixer_message_parse_option_changed),
(gst_mixer_message_parse_options_list_changed):
* gst-libs/gst/interfaces/mixer.h: (GstMixerType),
(GST_MIXER_MESSAGE_OPTION_CHANGED),
(GST_MIXER_MESSAGE_OPTIONS_LIST_CHANGED),
(GST_MIXER_MESSAGE_MIXER_CHANGED):
API: add gst_mixer_options_list_changed(), gst_mixer_mixer_changed()
and gst_mixer_message_parse_options_list_changed(). Fixes #519916.

ChangeLog

@@ -1,3 +1,18 @@
+2008-03-03  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/libs/gst-plugins-base-libs-sections.txt:
+	* gst-libs/gst/interfaces/mixer.c: (gst_mixer_option_changed),
+	  (gst_mixer_options_list_changed), (gst_mixer_mixer_changed),
+	  (gst_mixer_message_get_type),
+	  (gst_mixer_message_parse_option_changed),
+	  (gst_mixer_message_parse_options_list_changed):
+	* gst-libs/gst/interfaces/mixer.h: (GstMixerType),
+	  (GST_MIXER_MESSAGE_OPTION_CHANGED),
+	  (GST_MIXER_MESSAGE_OPTIONS_LIST_CHANGED),
+	  (GST_MIXER_MESSAGE_MIXER_CHANGED):
+	  API: add gst_mixer_options_list_changed(), gst_mixer_mixer_changed()
+	  and gst_mixer_message_parse_options_list_changed(). Fixes #519916.
+
 2008-03-03  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* gst-libs/gst/interfaces/mixeroptions.c: (gst_mixer_options_init),

docs/libs/gst-plugins-base-libs-sections.txt

@@ -365,8 +365,11 @@ gst_mixer_mute_toggled
 gst_mixer_record_toggled
 gst_mixer_volume_changed
 gst_mixer_option_changed
+gst_mixer_options_list_changed
 gst_mixer_get_option
 
+gst_mixer_mixer_changed
+
 gst_mixer_get_mixer_flags
 
 gst_mixer_message_get_type
@@ -374,6 +377,7 @@ gst_mixer_message_parse_mute_toggled
 gst_mixer_message_parse_option_changed
 gst_mixer_message_parse_record_toggled
 gst_mixer_message_parse_volume_changed
+gst_mixer_message_parse_options_list_changed
 
 <SUBSECTION Standard>
 GstMixerClass

gst-libs/gst/interfaces/mixer.c

@@ -497,6 +497,82 @@ gst_mixer_option_changed (GstMixer * mixer,
   }
 }
 
+/**
+ * gst_mixer_options_list_changed:
+ * @mixer: the #GstMixer (a #GstElement) that owns the options 
+ * @opts: the GstMixerOptions whose list of values has changed
+ *
+ * This function is called by the mixer implementation to produce
+ * a notification message on the bus indicating that the list of possible
+ * options of a given options object has changed.
+ *
+ * The new options are not contained in the message on purpose. Applications
+ * should call gst_mixer_option_get_values() on @opts to make @opts update
+ * its internal state and obtain the new list of values.
+ *
+ * This function only works for GstElements that are implementing the
+ * GstMixer interface, and the element needs to have been provided a bus
+ * for this to work.
+ *
+ * Since: 0.10.18
+ */
+void
+gst_mixer_options_list_changed (GstMixer * mixer, GstMixerOptions * opts)
+{
+  GstStructure *s;
+  GstMessage *m;
+
+  g_return_if_fail (mixer != NULL);
+  g_return_if_fail (GST_IS_ELEMENT (mixer));
+  g_return_if_fail (opts != NULL);
+  g_return_if_fail (GST_IS_MIXER_OPTIONS (opts));
+
+  /* we do not include the new list here on purpose, so that the application
+   * has to use gst_mixer_options_get_values() to get the new list, which then
+   * allows the mixer options object to update the internal GList in a somewhat
+   * thread-safe way at least */
+  s = gst_structure_new (GST_MIXER_MESSAGE_NAME,
+      "type", G_TYPE_STRING, "options-list-changed",
+      "options", GST_TYPE_MIXER_OPTIONS, opts, NULL);
+
+  m = gst_message_new_element (GST_OBJECT (mixer), s);
+  if (gst_element_post_message (GST_ELEMENT (mixer), m) == FALSE) {
+    GST_WARNING ("This element has no bus, therefore no message sent!");
+  }
+}
+
+/**
+ * gst_mixer_mixer_changed:
+ * @mixer: the #GstMixer (a #GstElement) which has changed
+ *
+ * This function is called by the mixer implementation to produce
+ * a notification message on the bus indicating that the list of available
+ * mixer tracks for a given mixer object has changed. Applications should
+ * rebuild their interface when they receive this message.
+ *
+ * This function only works for GstElements that are implementing the
+ * GstMixer interface, and the element needs to have been provided a bus.
+ *
+ * Since: 0.10.18
+ */
+void
+gst_mixer_mixer_changed (GstMixer * mixer)
+{
+  GstStructure *s;
+  GstMessage *m;
+
+  g_return_if_fail (mixer != NULL);
+  g_return_if_fail (GST_IS_ELEMENT (mixer));
+
+  s = gst_structure_new (GST_MIXER_MESSAGE_NAME,
+      "type", G_TYPE_STRING, "mixer-changed", NULL);
+
+  m = gst_message_new_element (GST_OBJECT (mixer), s);
+  if (gst_element_post_message (GST_ELEMENT (mixer), m) == FALSE) {
+    GST_WARNING ("This element has no bus, therefore no message sent!");
+  }
+}
+
 static gboolean
 gst_mixer_message_is_mixer_message (GstMessage * message)
 {
@@ -545,6 +621,10 @@ gst_mixer_message_get_type (GstMessage * message)
     return GST_MIXER_MESSAGE_VOLUME_CHANGED;
   else if (g_str_equal (m_type, "option-changed"))
     return GST_MIXER_MESSAGE_OPTION_CHANGED;
+  else if (g_str_equal (m_type, "options-list-changed"))
+    return GST_MIXER_MESSAGE_OPTIONS_LIST_CHANGED;
+  else if (g_str_equal (m_type, "mixer-changed"))
+    return GST_MIXER_MESSAGE_MIXER_CHANGED;
 
   return GST_MIXER_MESSAGE_INVALID;
 }
@@ -720,3 +800,36 @@ gst_mixer_message_parse_option_changed (GstMessage * message,
   if (value)
     *value = gst_structure_get_string (s, "value");
 }
+
+/**
+ * gst_mixer_message_parse_options_list_changed:
+ * @message: A volume-changed change notification message.
+ * @options: Pointer to hold a GstMixerOptions object, or NULL.
+ *
+ * Extracts the GstMixerOptions whose value list has changed from an
+ * options-list-changed bus notification message.
+ *
+ * The options object returned remains valid until the message is freed. You
+ * do not need to unref it.
+ *
+ * Since: 0.10.18
+ */
+void
+gst_mixer_message_parse_options_list_changed (GstMessage * message,
+    GstMixerOptions ** options)
+{
+  const GstStructure *s;
+
+  g_return_if_fail (gst_mixer_message_is_mixer_message (message));
+  g_return_if_fail (GST_MIXER_MESSAGE_HAS_TYPE (message, OPTIONS_LIST_CHANGED));
+
+  s = gst_message_get_structure (message);
+
+  if (options) {
+    const GValue *v = gst_structure_get_value (s, "options");
+
+    g_return_if_fail (v != NULL);
+    *options = (GstMixerOptions *) g_value_get_object (v);
+    g_return_if_fail (GST_IS_MIXER_OPTIONS (*options));
+  }
+}

gst-libs/gst/interfaces/mixer.h

@@ -60,6 +60,12 @@ typedef enum
  * @GST_MIXER_MESSAGE_RECORD_TOGGLED: A record-toggled GstMixer message
  * @GST_MIXER_MESSAGE_VOLUME_CHANGED: A volume-changed GstMixer message
  * @GST_MIXER_MESSAGE_OPTION_CHANGED: An option-changed GstMixer message
+ * @GST_MIXER_MESSAGE_OPTIONS_LIST_CHANGED: An options-list-changed
+ *     GstMixer message, posted when the list of available options for a
+ *     GstMixerOptions object has changed (Since: 0.10.18)
+ * @GST_MIXER_MESSAGE_MIXER_CHANGED: A mixer-changed GstMixer message, posted
+ *     when the list of available mixer tracks has changed. The application
+ *     should re-build its interface in this case (Since: 0.10.18)
  * 
  * An enumeration for the type of a GstMixer message received on the bus
  *
@@ -71,7 +77,9 @@ typedef enum
   GST_MIXER_MESSAGE_MUTE_TOGGLED,
   GST_MIXER_MESSAGE_RECORD_TOGGLED,
   GST_MIXER_MESSAGE_VOLUME_CHANGED,
-  GST_MIXER_MESSAGE_OPTION_CHANGED
+  GST_MIXER_MESSAGE_OPTION_CHANGED,
+  GST_MIXER_MESSAGE_OPTIONS_LIST_CHANGED,
+  GST_MIXER_MESSAGE_MIXER_CHANGED
 } GstMixerMessageType;
 
 /**
@@ -183,6 +191,12 @@ void            gst_mixer_option_changed (GstMixer      *mixer,
                                           GstMixerOptions *opts,
                                           gchar         *value);
 
+void            gst_mixer_mixer_changed   (GstMixer        *mixer);
+
+void            gst_mixer_options_list_changed (GstMixer        *mixer,
+                                                GstMixerOptions *opts);
+
+
 GstMixerFlags   gst_mixer_get_mixer_flags (GstMixer *mixer);
 
 /* Functions for recognising and parsing GstMixerMessages on the bus */
@@ -200,6 +214,8 @@ void            gst_mixer_message_parse_volume_changed (GstMessage *message,
 void            gst_mixer_message_parse_option_changed (GstMessage *message,
                                                         GstMixerOptions **options,
                                                         const gchar **value);
+void            gst_mixer_message_parse_options_list_changed (GstMessage *message,
+                                                              GstMixerOptions **options);
 
 G_END_DECLS