1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.MiniObject;
26 
27 private import gobject.ObjectG;
28 private import gstreamer.c.functions;
29 public  import gstreamer.c.types;
30 private import gtkd.Loader;
31 
32 
33 /**
34  * #GstMiniObject is a simple structure that can be used to implement refcounted
35  * types.
36  * 
37  * Subclasses will include #GstMiniObject as the first member in their structure
38  * and then call gst_mini_object_init() to initialize the #GstMiniObject fields.
39  * 
40  * gst_mini_object_ref() and gst_mini_object_unref() increment and decrement the
41  * refcount respectively. When the refcount of a mini-object reaches 0, the
42  * dispose function is called first and when this returns %TRUE, the free
43  * function of the miniobject is called.
44  * 
45  * A copy can be made with gst_mini_object_copy().
46  * 
47  * gst_mini_object_is_writable() will return %TRUE when the refcount of the
48  * object is exactly 1 and there is no parent or a single parent exists and is
49  * writable itself, meaning the current caller has the only reference to the
50  * object. gst_mini_object_make_writable() will return a writable version of
51  * the object, which might be a new copy when the refcount was not 1.
52  * 
53  * Opaque data can be associated with a #GstMiniObject with
54  * gst_mini_object_set_qdata() and gst_mini_object_get_qdata(). The data is
55  * meant to be specific to the particular object and is not automatically copied
56  * with gst_mini_object_copy() or similar methods.
57  * 
58  * A weak reference can be added and remove with gst_mini_object_weak_ref()
59  * and gst_mini_object_weak_unref() respectively.
60  */
61 public class MiniObject
62 {
63 	/** the main Gtk struct */
64 	protected GstMiniObject* gstMiniObject;
65 	protected bool ownedRef;
66 
67 	/** Get the main Gtk struct */
68 	public GstMiniObject* getMiniObjectStruct(bool transferOwnership = false)
69 	{
70 		if (transferOwnership)
71 			ownedRef = false;
72 		return gstMiniObject;
73 	}
74 
75 	/** the main Gtk struct as a void* */
76 	protected void* getStruct()
77 	{
78 		return cast(void*)gstMiniObject;
79 	}
80 
81 	/**
82 	 * Sets our main struct and passes it to the parent class.
83 	 */
84 	public this (GstMiniObject* gstMiniObject, bool ownedRef = false)
85 	{
86 		this.gstMiniObject = gstMiniObject;
87 		this.ownedRef = ownedRef;
88 	}
89 
90 	~this ()
91 	{
92 		if ( Linker.isLoaded(LIBRARY_GSTREAMER) && ownedRef )
93 			gst_mini_object_unref(gstMiniObject);
94 	}
95 
96 
97 	/**
98 	 * This adds @parent as a parent for @object. Having one ore more parents affects the
99 	 * writability of @object: if a @parent is not writable, @object is also not
100 	 * writable, regardless of its refcount. @object is only writable if all
101 	 * the parents are writable and its own refcount is exactly 1.
102 	 *
103 	 * Note: This function does not take ownership of @parent and also does not
104 	 * take an additional reference. It is the responsibility of the caller to
105 	 * remove the parent again at a later time.
106 	 *
107 	 * Params:
108 	 *     parent = a parent #GstMiniObject
109 	 *
110 	 * Since: 1.16
111 	 */
112 	public void addParent(MiniObject parent)
113 	{
114 		gst_mini_object_add_parent(gstMiniObject, (parent is null) ? null : parent.getMiniObjectStruct());
115 	}
116 
117 	/**
118 	 * Creates a copy of the mini-object.
119 	 *
120 	 * MT safe
121 	 *
122 	 * Returns: the new mini-object if copying is
123 	 *     possible, %NULL otherwise.
124 	 */
125 	public MiniObject copy()
126 	{
127 		auto __p = gst_mini_object_copy(gstMiniObject);
128 
129 		if(__p is null)
130 		{
131 			return null;
132 		}
133 
134 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) __p, true);
135 	}
136 
137 	/**
138 	 * This function gets back user data pointers stored via
139 	 * gst_mini_object_set_qdata().
140 	 *
141 	 * Params:
142 	 *     quark = A #GQuark, naming the user data pointer
143 	 *
144 	 * Returns: The user data pointer set, or
145 	 *     %NULL
146 	 */
147 	public void* getQdata(GQuark quark)
148 	{
149 		return gst_mini_object_get_qdata(gstMiniObject, quark);
150 	}
151 
152 	/**
153 	 * Initializes a mini-object with the desired type and copy/dispose/free
154 	 * functions.
155 	 *
156 	 * Params:
157 	 *     flags = initial #GstMiniObjectFlags
158 	 *     type = the #GType of the mini-object to create
159 	 *     copyFunc = the copy function, or %NULL
160 	 *     disposeFunc = the dispose function, or %NULL
161 	 *     freeFunc = the free function or %NULL
162 	 */
163 	public void init(uint flags, GType type, GstMiniObjectCopyFunction copyFunc, GstMiniObjectDisposeFunction disposeFunc, GstMiniObjectFreeFunction freeFunc)
164 	{
165 		gst_mini_object_init(gstMiniObject, flags, type, copyFunc, disposeFunc, freeFunc);
166 	}
167 
168 	/**
169 	 * If @mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE
170 	 * lock on @object is the only one, this means that changes to the object will
171 	 * not be visible to any other object.
172 	 *
173 	 * If the LOCKABLE flag is not set, check if the refcount of @mini_object is
174 	 * exactly 1, meaning that no other reference exists to the object and that the
175 	 * object is therefore writable.
176 	 *
177 	 * Modification of a mini-object should only be done after verifying that it
178 	 * is writable.
179 	 *
180 	 * Returns: %TRUE if the object is writable.
181 	 */
182 	public bool isWritable()
183 	{
184 		return gst_mini_object_is_writable(gstMiniObject) != 0;
185 	}
186 
187 	/**
188 	 * Lock the mini-object with the specified access mode in @flags.
189 	 *
190 	 * Params:
191 	 *     flags = #GstLockFlags
192 	 *
193 	 * Returns: %TRUE if @object could be locked.
194 	 */
195 	public bool lock(GstLockFlags flags)
196 	{
197 		return gst_mini_object_lock(gstMiniObject, flags) != 0;
198 	}
199 
200 	/**
201 	 * Checks if a mini-object is writable.  If not, a writable copy is made and
202 	 * returned.  This gives away the reference to the original mini object,
203 	 * and returns a reference to the new object.
204 	 *
205 	 * MT safe
206 	 *
207 	 * Returns: a mini-object (possibly the same pointer) that
208 	 *     is writable.
209 	 */
210 	public MiniObject makeWritable()
211 	{
212 		auto __p = gst_mini_object_make_writable(gstMiniObject);
213 
214 		if(__p is null)
215 		{
216 			return null;
217 		}
218 
219 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) __p, true);
220 	}
221 
222 	alias doref = ref_;
223 	/**
224 	 * Increase the reference count of the mini-object.
225 	 *
226 	 * Note that the refcount affects the writability
227 	 * of @mini-object, see gst_mini_object_is_writable(). It is
228 	 * important to note that keeping additional references to
229 	 * GstMiniObject instances can potentially increase the number
230 	 * of memcpy operations in a pipeline, especially if the miniobject
231 	 * is a #GstBuffer.
232 	 *
233 	 * Returns: the mini-object.
234 	 */
235 	public MiniObject ref_()
236 	{
237 		auto __p = gst_mini_object_ref(gstMiniObject);
238 
239 		if(__p is null)
240 		{
241 			return null;
242 		}
243 
244 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) __p, true);
245 	}
246 
247 	/**
248 	 * This removes @parent as a parent for @object. See
249 	 * gst_mini_object_add_parent().
250 	 *
251 	 * Params:
252 	 *     parent = a parent #GstMiniObject
253 	 *
254 	 * Since: 1.16
255 	 */
256 	public void removeParent(MiniObject parent)
257 	{
258 		gst_mini_object_remove_parent(gstMiniObject, (parent is null) ? null : parent.getMiniObjectStruct());
259 	}
260 
261 	/**
262 	 * This sets an opaque, named pointer on a miniobject.
263 	 * The name is specified through a #GQuark (retrieved e.g. via
264 	 * g_quark_from_static_string()), and the pointer
265 	 * can be gotten back from the @object with gst_mini_object_get_qdata()
266 	 * until the @object is disposed.
267 	 * Setting a previously set user data pointer, overrides (frees)
268 	 * the old pointer set, using %NULL as pointer essentially
269 	 * removes the data stored.
270 	 *
271 	 * @destroy may be specified which is called with @data as argument
272 	 * when the @object is disposed, or the data is being overwritten by
273 	 * a call to gst_mini_object_set_qdata() with the same @quark.
274 	 *
275 	 * Params:
276 	 *     quark = A #GQuark, naming the user data pointer
277 	 *     data = An opaque user data pointer
278 	 *     destroy = Function to invoke with @data as argument, when @data
279 	 *         needs to be freed
280 	 */
281 	public void setQdata(GQuark quark, void* data, GDestroyNotify destroy)
282 	{
283 		gst_mini_object_set_qdata(gstMiniObject, quark, data, destroy);
284 	}
285 
286 	/**
287 	 * This function gets back user data pointers stored via gst_mini_object_set_qdata()
288 	 * and removes the data from @object without invoking its `destroy()` function (if
289 	 * any was set).
290 	 *
291 	 * Params:
292 	 *     quark = A #GQuark, naming the user data pointer
293 	 *
294 	 * Returns: The user data pointer set, or
295 	 *     %NULL
296 	 */
297 	public void* stealQdata(GQuark quark)
298 	{
299 		return gst_mini_object_steal_qdata(gstMiniObject, quark);
300 	}
301 
302 	/**
303 	 * Unlock the mini-object with the specified access mode in @flags.
304 	 *
305 	 * Params:
306 	 *     flags = #GstLockFlags
307 	 */
308 	public void unlock(GstLockFlags flags)
309 	{
310 		gst_mini_object_unlock(gstMiniObject, flags);
311 	}
312 
313 	/**
314 	 * Decreases the reference count of the mini-object, possibly freeing
315 	 * the mini-object.
316 	 */
317 	public void unref()
318 	{
319 		gst_mini_object_unref(gstMiniObject);
320 	}
321 
322 	/**
323 	 * Adds a weak reference callback to a mini object. Weak references are
324 	 * used for notification when a mini object is finalized. They are called
325 	 * "weak references" because they allow you to safely hold a pointer
326 	 * to the mini object without calling gst_mini_object_ref()
327 	 * (gst_mini_object_ref() adds a strong reference, that is, forces the object
328 	 * to stay alive).
329 	 *
330 	 * Params:
331 	 *     notify = callback to invoke before the mini object is freed
332 	 *     data = extra data to pass to notify
333 	 */
334 	public void weakRef(GstMiniObjectNotify notify, void* data)
335 	{
336 		gst_mini_object_weak_ref(gstMiniObject, notify, data);
337 	}
338 
339 	/**
340 	 * Removes a weak reference callback from a mini object.
341 	 *
342 	 * Params:
343 	 *     notify = callback to search for
344 	 *     data = data to search for
345 	 */
346 	public void weakUnref(GstMiniObjectNotify notify, void* data)
347 	{
348 		gst_mini_object_weak_unref(gstMiniObject, notify, data);
349 	}
350 
351 	/**
352 	 * Atomically modifies a pointer to point to a new mini-object.
353 	 * The reference count of @olddata is decreased and the reference count of
354 	 * @newdata is increased.
355 	 *
356 	 * Either @newdata and the value pointed to by @olddata may be %NULL.
357 	 *
358 	 * Params:
359 	 *     olddata = pointer to a pointer to a
360 	 *         mini-object to be replaced
361 	 *     newdata = pointer to new mini-object
362 	 *
363 	 * Returns: %TRUE if @newdata was different from @olddata
364 	 */
365 	public static bool replace(ref MiniObject olddata, MiniObject newdata)
366 	{
367 		GstMiniObject* outolddata = olddata.getMiniObjectStruct();
368 
369 		auto __p = gst_mini_object_replace(&outolddata, (newdata is null) ? null : newdata.getMiniObjectStruct()) != 0;
370 
371 		olddata = ObjectG.getDObject!(MiniObject)(outolddata);
372 
373 		return __p;
374 	}
375 
376 	/**
377 	 * Replace the current #GstMiniObject pointer to by @olddata with %NULL and
378 	 * return the old value.
379 	 *
380 	 * Params:
381 	 *     olddata = pointer to a pointer to a mini-object to
382 	 *         be stolen
383 	 *
384 	 * Returns: the #GstMiniObject at @oldata
385 	 */
386 	public static MiniObject steal(ref MiniObject olddata)
387 	{
388 		GstMiniObject* outolddata = olddata.getMiniObjectStruct();
389 
390 		auto __p = gst_mini_object_steal(&outolddata);
391 
392 		olddata = ObjectG.getDObject!(MiniObject)(outolddata);
393 
394 		if(__p is null)
395 		{
396 			return null;
397 		}
398 
399 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) __p);
400 	}
401 
402 	/**
403 	 * Modifies a pointer to point to a new mini-object. The modification
404 	 * is done atomically. This version is similar to gst_mini_object_replace()
405 	 * except that it does not increase the refcount of @newdata and thus
406 	 * takes ownership of @newdata.
407 	 *
408 	 * Either @newdata and the value pointed to by @olddata may be %NULL.
409 	 *
410 	 * Params:
411 	 *     olddata = pointer to a pointer to a mini-object to
412 	 *         be replaced
413 	 *     newdata = pointer to new mini-object
414 	 *
415 	 * Returns: %TRUE if @newdata was different from @olddata
416 	 */
417 	public static bool take(ref MiniObject olddata, MiniObject newdata)
418 	{
419 		GstMiniObject* outolddata = olddata.getMiniObjectStruct();
420 
421 		auto __p = gst_mini_object_take(&outolddata, (newdata is null) ? null : newdata.getMiniObjectStruct()) != 0;
422 
423 		olddata = ObjectG.getDObject!(MiniObject)(outolddata);
424 
425 		return __p;
426 	}
427 }