docs: convert NULL, TRUE, and FALSE to %NULL, %TRUE, and %FALSE
[platform/upstream/gstreamer.git] / gst / gstelement.h
index 263c573..408d10c 100644 (file)
@@ -16,8 +16,8 @@
  *
  * You should have received a copy of the GNU Library General Public
  * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
  */
 
 
@@ -127,8 +127,6 @@ typedef enum {
  * @elem: a #GstElement to return the target state for.
  *
  * This macro returns the target #GstState of the element.
- *
- * Since: 0.10.13
  */
 #define GST_STATE_TARGET(elem)          (GST_ELEMENT_CAST(elem)->target_state)
 
@@ -214,7 +212,7 @@ typedef enum {
  *   </para></listitem>
  *   <listitem><para>
  *     The pipeline selects a #GstClock and distributes this to all the children
- *     before setting them to PLAYING. This means that it is only alowed to
+ *     before setting them to PLAYING. This means that it is only allowed to
  *     synchronize on the #GstClock in the PLAYING state.
  *   </para></listitem>
  *   <listitem><para>
@@ -313,11 +311,9 @@ typedef enum /*< flags=0 >*/
 
 /**
  * GstElementFlags:
- * @GST_ELEMENT_FLAG_UNPARENTING: Child is being removed from the parent bin.
- *  gst_bin_remove() on a child already being removed immediately returns FALSE
  * @GST_ELEMENT_FLAG_LOCKED_STATE: ignore state changes from parent
  * @GST_ELEMENT_FLAG_SINK: the element is a sink
- * @GST_ELEMENT_FLAG_SOURCE: the element is a source. Since 0.10.31
+ * @GST_ELEMENT_FLAG_SOURCE: the element is a source.
  * @GST_ELEMENT_FLAG_PROVIDE_CLOCK: the element can provide a clock
  * @GST_ELEMENT_FLAG_REQUIRE_CLOCK: the element requires a clock
  * @GST_ELEMENT_FLAG_INDEXABLE: the element can use an index
@@ -327,13 +323,12 @@ typedef enum /*< flags=0 >*/
  */
 typedef enum
 {
-  GST_ELEMENT_FLAG_UNPARENTING    = (GST_OBJECT_FLAG_LAST << 0),
-  GST_ELEMENT_FLAG_LOCKED_STATE   = (GST_OBJECT_FLAG_LAST << 1),
-  GST_ELEMENT_FLAG_SINK           = (GST_OBJECT_FLAG_LAST << 2),
-  GST_ELEMENT_FLAG_SOURCE         = (GST_OBJECT_FLAG_LAST << 3),
-  GST_ELEMENT_FLAG_PROVIDE_CLOCK  = (GST_OBJECT_FLAG_LAST << 4),
-  GST_ELEMENT_FLAG_REQUIRE_CLOCK  = (GST_OBJECT_FLAG_LAST << 5),
-  GST_ELEMENT_FLAG_INDEXABLE      = (GST_OBJECT_FLAG_LAST << 6),
+  GST_ELEMENT_FLAG_LOCKED_STATE   = (GST_OBJECT_FLAG_LAST << 0),
+  GST_ELEMENT_FLAG_SINK           = (GST_OBJECT_FLAG_LAST << 1),
+  GST_ELEMENT_FLAG_SOURCE         = (GST_OBJECT_FLAG_LAST << 2),
+  GST_ELEMENT_FLAG_PROVIDE_CLOCK  = (GST_OBJECT_FLAG_LAST << 3),
+  GST_ELEMENT_FLAG_REQUIRE_CLOCK  = (GST_OBJECT_FLAG_LAST << 4),
+  GST_ELEMENT_FLAG_INDEXABLE      = (GST_OBJECT_FLAG_LAST << 5),
   /* padding */
   GST_ELEMENT_FLAG_LAST           = (GST_OBJECT_FLAG_LAST << 10)
 } GstElementFlags;
@@ -394,8 +389,6 @@ typedef enum
  *
  * This macro returns the start_time of the @elem. The start_time is the
  * running_time of the pipeline when the element went to PAUSED.
- *
- * Since: 0.10.24
  */
 #define GST_ELEMENT_START_TIME(elem)            (GST_ELEMENT_CAST(elem)->start_time)
 
@@ -467,8 +460,6 @@ G_STMT_START {                                                          \
  * the application of something noteworthy that is not an error.
  * The pipeline will post a info message and the
  * application will be informed.
- *
- * Since: 0.10.12
  */
 #define GST_ELEMENT_INFO(el, domain, code, text, debug)                 \
 G_STMT_START {                                                          \
@@ -535,11 +526,11 @@ G_STMT_START {                                                          \
  * state will yield the running_time against the clock.
  * @start_time: the running_time of the last PAUSED state
  * @numpads: number of pads of the element, includes both source and sink pads.
- * @pads: list of pads
+ * @pads: (element-type Gst.Pad): list of pads
  * @numsrcpads: number of source pads of the element.
- * @srcpads: list of source pads
+ * @srcpads: (element-type Gst.Pad): list of source pads
  * @numsinkpads: number of sink pads of the element.
- * @sinkpads: list of sink pads
+ * @sinkpads: (element-type Gst.Pad): list of sink pads
  * @pads_cookie: updated whenever the a pad is added or removed
  *
  * GStreamer element abstract base class.
@@ -600,6 +591,9 @@ struct _GstElement
  * @send_event: send a #GstEvent to the element
  * @query: perform a #GstQuery on the element
  * @state_changed: called immediately after a new state was set.
+ * @post_message: called when a message is posted on the element. Chain up to
+ *                the parent class' handler to have it posted on the bus.
+ * @set_context: set a #GstContext on the element
  *
  * GStreamer element class. Override the vmethods to implement the element
  * functionality.
@@ -654,8 +648,12 @@ struct _GstElementClass
 
   gboolean              (*query)                (GstElement *element, GstQuery *query);
 
+  gboolean              (*post_message)         (GstElement *element, GstMessage *message);
+
+  void                  (*set_context)          (GstElement *element, GstContext *context);
+
   /*< private >*/
-  gpointer _gst_reserved[GST_PADDING_LARGE];
+  gpointer _gst_reserved[GST_PADDING_LARGE-2];
 };
 
 /* element class pad templates */
@@ -693,7 +691,7 @@ GType                   gst_element_get_type            (void);
  *
  * Returns a copy of the name of @elem.
  * Caller should g_free() the return value after usage.
- * For a nameless element, this returns NULL, which you can safely g_free()
+ * For a nameless element, this returns %NULL, which you can safely g_free()
  * as well.
  *
  * Returns: (transfer full): the name of @elem. g_free() after usage. MT safe.
@@ -742,6 +740,9 @@ GstClockTime            gst_element_get_start_time      (GstElement *element);
 void                    gst_element_set_bus             (GstElement * element, GstBus * bus);
 GstBus *                gst_element_get_bus             (GstElement * element);
 
+/* context */
+void                    gst_element_set_context         (GstElement * element, GstContext * context);
+
 /* pad management */
 gboolean                gst_element_add_pad             (GstElement *element, GstPad *pad);
 gboolean                gst_element_remove_pad          (GstElement *element, GstPad *pad);
@@ -761,7 +762,7 @@ GstIterator *           gst_element_iterate_sink_pads   (GstElement * element);
 gboolean                gst_element_send_event          (GstElement *element, GstEvent *event);
 gboolean                gst_element_seek                (GstElement *element, gdouble rate,
                                                          GstFormat format, GstSeekFlags flags,
-                                                         GstSeekType cur_type, gint64 cur,
+                                                         GstSeekType start_type, gint64 start,
                                                          GstSeekType stop_type, gint64 stop);
 gboolean                gst_element_query               (GstElement *element, GstQuery *query);
 
@@ -770,7 +771,7 @@ gboolean                gst_element_post_message        (GstElement * element, G
 
 /* error handling */
 /* gcc versions < 3.3 warn about NULL being passed as format to printf */
-#if (defined(GST_USING_PRINTF_EXTENSION) || !defined(__GNUC__) || (__GNUC__ < 3) || (__GNUC__ == 3 && __GNUC_MINOR__ < 3))
+#if (!defined(__GNUC__) || (__GNUC__ < 3) || (__GNUC__ == 3 && __GNUC_MINOR__ < 3))
 gchar *                 _gst_element_error_printf       (const gchar *format, ...);
 #else
 gchar *                 _gst_element_error_printf       (const gchar *format, ...) G_GNUC_PRINTF (1, 2);