parts of the patch submitted in bug #113913
[platform/upstream/gstreamer.git] / docs / gst / tmpl / gstobject.sgml
1 <!-- ##### SECTION Title ##### -->
2 GstObject
3
4 <!-- ##### SECTION Short_Description ##### -->
5 Basis for the GST object hierarchy.
6
7 <!-- ##### SECTION Long_Description ##### -->
8 <para>
9 GstObject provides a root for the object hierarchy tree filed in by the
10 GST library.  It is currently a thin wrapper on top of
11 <classname>GObject</classname>. It is an abstract class that is not
12 very usable on its own.
13 </para>
14
15 <para>
16 GstObject gives us basic refcounting, parenting functionality and locking. 
17 </para>
18 <para>
19 gst_object_set_name() and gst_object_get_name() are used to set/get the name of the 
20 object.
21 </para>
22
23 <!-- ##### SECTION See_Also ##### -->
24 <para>
25
26 </para>
27
28 <!-- ##### ENUM GstObjectFlags ##### -->
29 <para>
30 Flags for an object
31 </para>
32
33 @GST_DESTROYED: The object is flagged for destruction
34 @GST_FLOATING: The object is created but has no parent yet to manage it
35 @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
36
37 <!-- ##### STRUCT GstObject ##### -->
38 <para>
39 The GstObject
40 </para>
41
42
43 <!-- ##### SIGNAL GstObject::deep-notify ##### -->
44 <para>
45 The deep notify signal is used to be notified of property changes.
46 it is typically attached to the toplevel bin to receive notifications
47 from all the elements contained in that bin.
48 </para>
49
50 @gstobject: the object which received the signal.
51 @arg1: the object that originated the signal
52 @arg2: the property that changed
53
54 <!-- ##### SIGNAL GstObject::object-saved ##### -->
55 <para>
56 Is trigered whenever a new object is saved to XML. You can connect to
57 this signal to insert custom XML tags into the core XML.
58 </para>
59
60 @gstobject: the object which received the signal.
61 @arg1: the xmlNodePtr of the parent node
62
63 <!-- ##### SIGNAL GstObject::parent-set ##### -->
64 <para>
65 Is emitted when the parent of an object is set.
66 </para>
67
68 @gstobject: the object which received the signal.
69 @arg1: the new parent
70
71 <!-- ##### SIGNAL GstObject::parent-unset ##### -->
72 <para>
73 Is emitted when the parent of an object is unset.
74 </para>
75
76 @gstobject: the object which received the signal.
77 @arg1: the old parent
78
79 <!-- ##### ARG GstObject:name ##### -->
80 <para>
81 The name of the object
82 </para>
83
84 <!-- ##### MACRO GST_FLAGS ##### -->
85 <para>
86 This macro returns the entire set of flags for the object.
87 </para>
88
89 @obj: Object to return flags for.
90
91
92 <!-- ##### MACRO GST_FLAG_IS_SET ##### -->
93 <para>
94 This macro checks to see if the given flag is set.
95 </para>
96
97 @obj: GstSrc to check for flag in.
98 @flag: Flag to check for, must be a single bit in guint32.
99
100
101 <!-- ##### MACRO GST_FLAG_SET ##### -->
102 <para>
103 This macro sets the given bits.
104 </para>
105
106 @obj: Object to set flag in.
107 @flag: Flag to set, can by any number of bits in guint32.
108
109
110 <!-- ##### MACRO GST_FLAG_UNSET ##### -->
111 <para>
112 This macro usets the given bits.
113 </para>
114
115 @obj: Object to unset flag in.
116 @flag: Flag to set, must be a single bit in guint32.
117
118
119 <!-- ##### MACRO GST_LOCK ##### -->
120 <para>
121 This macro will obtain a lock on the object, making serialization
122 possible.
123 </para>
124
125 @obj: Object to lock.
126
127
128 <!-- ##### MACRO GST_TRYLOCK ##### -->
129 <para>
130 This macro will try to obtain a lock on the object, but will return with
131 FALSE if it can't get it immediately.
132 </para>
133
134 @obj: Object to try to get a lock on.
135
136
137 <!-- ##### MACRO GST_UNLOCK ##### -->
138 <para>
139 This macro releases a lock on the object.
140 </para>
141
142 @obj: Object to unlock.
143
144
145 <!-- ##### MACRO GST_GET_LOCK ##### -->
146 <para>
147 Acquire a reference to the mutex of this object.
148 </para>
149
150 @obj: Object to get the mutex of.
151
152
153 <!-- ##### MACRO GST_OBJECT_PARENT ##### -->
154 <para>
155 Get the parent of this object
156 </para>
157
158 @obj: Object to get the parent of.
159
160
161 <!-- ##### MACRO GST_OBJECT_NAME ##### -->
162 <para>
163 Get the name of this object
164 </para>
165
166 @obj: Object to get the name of.
167
168
169 <!-- ##### MACRO GST_OBJECT_FLOATING ##### -->
170 <para>
171 Check if the object is floating.
172 </para>
173
174 @obj: The Object to check
175
176
177 <!-- ##### MACRO GST_OBJECT_DESTROYED ##### -->
178 <para>
179 Check if the object has been destroyed.
180 </para>
181
182 @obj: The Object to check
183
184
185 <!-- ##### FUNCTION gst_object_check_uniqueness ##### -->
186 <para>
187
188 </para>
189
190 @list: 
191 @name: 
192 @Returns: 
193
194
195 <!-- ##### FUNCTION gst_object_set_parent ##### -->
196 <para>
197
198 </para>
199
200 @object: 
201 @parent: 
202
203
204 <!-- ##### FUNCTION gst_object_get_parent ##### -->
205 <para>
206
207 </para>
208
209 @object: 
210 @Returns: 
211
212
213 <!-- ##### FUNCTION gst_object_set_name ##### -->
214 <para>
215
216 </para>
217
218 @object: 
219 @name: 
220
221
222 <!-- ##### FUNCTION gst_object_get_name ##### -->
223 <para>
224
225 </para>
226
227 @object: 
228 @Returns: 
229
230
231 <!-- ##### FUNCTION gst_object_unparent ##### -->
232 <para>
233
234 </para>
235
236 @object: 
237
238
239 <!-- ##### FUNCTION gst_object_ref ##### -->
240 <para>
241
242 </para>
243
244 @object: the object
245 @Returns: 
246
247
248 <!-- ##### FUNCTION gst_object_unref ##### -->
249 <para>
250
251 </para>
252
253 @object: the object
254
255
256 <!-- ##### FUNCTION gst_object_replace ##### -->
257 <para>
258
259 </para>
260
261 @oldobj: 
262 @newobj: 
263
264
265 <!-- ##### FUNCTION gst_object_sink ##### -->
266 <para>
267
268 </para>
269
270 @object: the object
271
272
273 <!-- ##### FUNCTION gst_object_save_thyself ##### -->
274 <para>
275
276 </para>
277
278 @object: 
279 @parent: 
280 @Returns: 
281
282
283 <!-- ##### FUNCTION gst_object_restore_thyself ##### -->
284 <para>
285
286 </para>
287
288 @object: 
289 @self: 
290
291
292 <!-- ##### FUNCTION gst_object_get_path_string ##### -->
293 <para>
294
295 </para>
296
297 @object: 
298 @Returns: 
299
300
301 <!-- ##### FUNCTION gst_object_default_deep_notify ##### -->
302 <para>
303
304 </para>
305
306 @object: 
307 @orig: 
308 @pspec: 
309 @excluded_props: 
310
311
312 <!-- ##### FUNCTION gst_class_signal_emit_by_name ##### -->
313 <para>
314
315 </para>
316
317 @object: 
318 @name: 
319 @self: 
320
321
322 <!-- ##### FUNCTION gst_class_signal_connect ##### -->
323 <para>
324
325 </para>
326
327 @klass: 
328 @name: 
329 @func: 
330 @func_data: 
331 @Returns: 
332
333