Remove 0.10-related documentation and "Since" markers
[platform/upstream/gstreamer.git] / gst / gstbin.h
1 /* GStreamer
2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3  *                    2000 Wim Taymans <wtay@chello.be>
4  *
5  * gstbin.h: Header for GstBin container object
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Library General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Library General Public License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20  * Boston, MA 02111-1307, USA.
21  */
22
23
24 #ifndef __GST_BIN_H__
25 #define __GST_BIN_H__
26
27 #include <gst/gstelement.h>
28 #include <gst/gstiterator.h>
29 #include <gst/gstbus.h>
30
31 G_BEGIN_DECLS
32
33 #define GST_TYPE_BIN             (gst_bin_get_type ())
34 #define GST_IS_BIN(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BIN))
35 #define GST_IS_BIN_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BIN))
36 #define GST_BIN_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BIN, GstBinClass))
37 #define GST_BIN(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BIN, GstBin))
38 #define GST_BIN_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BIN, GstBinClass))
39 #define GST_BIN_CAST(obj)        ((GstBin*)(obj))
40
41 /**
42  * GstBinFlags:
43  * @GST_BIN_FLAG_LAST: the last enum in the series of flags for bins.
44  * Derived classes can use this as first value in a list of flags.
45  *
46  * GstBinFlags are a set of flags specific to bins. Most are set/used
47  * internally. They can be checked using the GST_OBJECT_FLAG_IS_SET () macro,
48  * and (un)set using GST_OBJECT_FLAG_SET () and GST_OBJECT_FLAG_UNSET ().
49  */
50 typedef enum {
51   /* padding */
52   GST_BIN_FLAG_LAST             = (GST_ELEMENT_FLAG_LAST << 5)
53 } GstBinFlags;
54
55 typedef struct _GstBin GstBin;
56 typedef struct _GstBinClass GstBinClass;
57 typedef struct _GstBinPrivate GstBinPrivate;
58
59 /**
60  * GST_BIN_NUMCHILDREN:
61  * @bin: a #GstBin
62  *
63  * Gets the number of children in a bin.
64  */
65 #define GST_BIN_NUMCHILDREN(bin)        (GST_BIN_CAST(bin)->numchildren)
66 /**
67  * GST_BIN_CHILDREN:
68  * @bin: a #GstBin
69  *
70  * Gets the list with children in a bin.
71  */
72 #define GST_BIN_CHILDREN(bin)           (GST_BIN_CAST(bin)->children)
73 /**
74  * GST_BIN_CHILDREN_COOKIE:
75  * @bin: a #GstBin
76  *
77  * Gets the children cookie that watches the children list.
78  */
79 #define GST_BIN_CHILDREN_COOKIE(bin)    (GST_BIN_CAST(bin)->children_cookie)
80
81 /**
82  * GstBin:
83  * @numchildren: the number of children in this bin
84  * @children: (element-type Gst.Element): the list of children in this bin
85  * @children_cookie: updated whenever @children changes
86  * @child_bus: internal bus for handling child messages
87  * @messages: (element-type Gst.Message): queued and cached messages
88  * @polling: the bin is currently calculating its state
89  * @state_dirty: the bin needs to recalculate its state (deprecated)
90  * @clock_dirty: the bin needs to select a new clock
91  * @provided_clock: the last clock selected
92  * @clock_provider: the element that provided @provided_clock
93  *
94  * The GstBin base class. Subclasses can access these fields provided
95  * the LOCK is taken.
96  */
97 struct _GstBin {
98   GstElement     element;
99
100   /*< public >*/ /* with LOCK */
101   /* our children, subclass are supposed to update these
102    * fields to reflect their state with _iterate_*() */
103   gint           numchildren;
104   GList         *children;
105   guint32        children_cookie;
106
107   GstBus        *child_bus;
108   GList         *messages;
109
110   gboolean       polling;
111   gboolean       state_dirty;
112
113   gboolean       clock_dirty;
114   GstClock      *provided_clock;
115   GstElement    *clock_provider;
116
117   /*< private >*/
118   GstBinPrivate *priv;
119
120   gpointer _gst_reserved[GST_PADDING];
121 };
122
123 /**
124  * GstBinClass:
125  * @parent_class: bin parent class
126  * @add_element: method to add an element to a bin
127  * @remove_element: method to remove an element from a bin
128  * @handle_message: method to handle a message from the children
129  *
130  * Subclasses can override the @add_element and @remove_element to
131  * update the list of children in the bin.
132  *
133  * The @handle_message method can be overridden to implement custom
134  * message handling.  @handle_message takes ownership of the message, just like
135  * #gst_element_post_message.
136  */
137 struct _GstBinClass {
138   GstElementClass parent_class;
139
140   /*< private >*/
141   GThreadPool  *pool;
142
143   /* signals */
144   void          (*element_added)        (GstBin *bin, GstElement *child);
145   void          (*element_removed)      (GstBin *bin, GstElement *child);
146
147   /*< public >*/
148   /* virtual methods for subclasses */
149   gboolean      (*add_element)          (GstBin *bin, GstElement *element);
150   gboolean      (*remove_element)       (GstBin *bin, GstElement *element);
151
152   void          (*handle_message)       (GstBin *bin, GstMessage *message);
153
154   /*< private >*/
155   /* signal */
156   gboolean      (*do_latency)           (GstBin *bin);
157
158   /*< private >*/
159   gpointer _gst_reserved[GST_PADDING];
160 };
161
162 GType           gst_bin_get_type                (void);
163 GstElement*     gst_bin_new                     (const gchar *name);
164
165 /* add and remove elements from the bin */
166 gboolean        gst_bin_add                     (GstBin *bin, GstElement *element);
167 gboolean        gst_bin_remove                  (GstBin *bin, GstElement *element);
168
169 /* retrieve a single child */
170 GstElement*     gst_bin_get_by_name              (GstBin *bin, const gchar *name);
171 GstElement*     gst_bin_get_by_name_recurse_up   (GstBin *bin, const gchar *name);
172 GstElement*     gst_bin_get_by_interface         (GstBin *bin, GType iface);
173
174 /* retrieve multiple children */
175 GstIterator*    gst_bin_iterate_elements         (GstBin *bin);
176 GstIterator*    gst_bin_iterate_sorted           (GstBin *bin);
177 GstIterator*    gst_bin_iterate_recurse          (GstBin *bin);
178
179 GstIterator*    gst_bin_iterate_sinks            (GstBin *bin);
180 GstIterator*    gst_bin_iterate_sources          (GstBin *bin);
181 GstIterator*    gst_bin_iterate_all_by_interface (GstBin *bin, GType iface);
182
183 /* latency */
184 gboolean        gst_bin_recalculate_latency      (GstBin * bin);
185
186
187 G_END_DECLS
188
189
190 #endif /* __GST_BIN_H__ */