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 gstreamerc.gstreamer;
29 public  import gstreamerc.gstreamertypes;
30 
31 
32 /**
33  * #GstMiniObject is a simple structure that can be used to implement refcounted
34  * types.
35  * 
36  * Subclasses will include #GstMiniObject as the first member in their structure
37  * and then call gst_mini_object_init() to initialize the #GstMiniObject fields.
38  * 
39  * gst_mini_object_ref() and gst_mini_object_unref() increment and decrement the
40  * refcount respectively. When the refcount of a mini-object reaches 0, the
41  * dispose function is called first and when this returns %TRUE, the free
42  * function of the miniobject is called.
43  * 
44  * A copy can be made with gst_mini_object_copy().
45  * 
46  * gst_mini_object_is_writable() will return %TRUE when the refcount of the
47  * object is exactly 1, meaning the current caller has the only reference to the
48  * object. gst_mini_object_make_writable() will return a writable version of the
49  * object, which might be a new copy when the refcount was not 1.
50  * 
51  * Opaque data can be associated with a #GstMiniObject with
52  * gst_mini_object_set_qdata() and gst_mini_object_get_qdata(). The data is
53  * meant to be specific to the particular object and is not automatically copied
54  * with gst_mini_object_copy() or similar methods.
55  * 
56  * A weak reference can be added and remove with gst_mini_object_weak_ref()
57  * and gst_mini_object_weak_unref() respectively.
58  */
59 public class MiniObject
60 {
61 	/** the main Gtk struct */
62 	protected GstMiniObject* gstMiniObject;
63 	protected bool ownedRef;
64 
65 	/** Get the main Gtk struct */
66 	public GstMiniObject* getMiniObjectStruct()
67 	{
68 		return gstMiniObject;
69 	}
70 
71 	/** the main Gtk struct as a void* */
72 	protected void* getStruct()
73 	{
74 		return cast(void*)gstMiniObject;
75 	}
76 
77 	/**
78 	 * Sets our main struct and passes it to the parent class.
79 	 */
80 	public this (GstMiniObject* gstMiniObject, bool ownedRef = false)
81 	{
82 		this.gstMiniObject = gstMiniObject;
83 		this.ownedRef = ownedRef;
84 	}
85 
86 
87 	/**
88 	 * Creates a copy of the mini-object.
89 	 *
90 	 * MT safe
91 	 *
92 	 * Return: the new mini-object.
93 	 */
94 	public MiniObject copy()
95 	{
96 		auto p = gst_mini_object_copy(gstMiniObject);
97 		
98 		if(p is null)
99 		{
100 			return null;
101 		}
102 		
103 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) p, true);
104 	}
105 
106 	/**
107 	 * This function gets back user data pointers stored via
108 	 * gst_mini_object_set_qdata().
109 	 *
110 	 * Params:
111 	 *     quark = A #GQuark, naming the user data pointer
112 	 *
113 	 * Return: The user data pointer set, or
114 	 *     %NULL
115 	 */
116 	public void* getQdata(GQuark quark)
117 	{
118 		return gst_mini_object_get_qdata(gstMiniObject, quark);
119 	}
120 
121 	/**
122 	 * Initializes a mini-object with the desired type and copy/dispose/free
123 	 * functions.
124 	 *
125 	 * Params:
126 	 *     flags = initial #GstMiniObjectFlags
127 	 *     type = the #GType of the mini-object to create
128 	 *     copyFunc = the copy function, or %NULL
129 	 *     disposeFunc = the dispose function, or %NULL
130 	 *     freeFunc = the free function or %NULL
131 	 */
132 	public void init(uint flags, GType type, GstMiniObjectCopyFunction copyFunc, GstMiniObjectDisposeFunction disposeFunc, GstMiniObjectFreeFunction freeFunc)
133 	{
134 		gst_mini_object_init(gstMiniObject, flags, type, copyFunc, disposeFunc, freeFunc);
135 	}
136 
137 	/**
138 	 * If @mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE
139 	 * lock on @object is the only one, this means that changes to the object will
140 	 * not be visible to any other object.
141 	 *
142 	 * If the LOCKABLE flag is not set, check if the refcount of @mini_object is
143 	 * exactly 1, meaning that no other reference exists to the object and that the
144 	 * object is therefore writable.
145 	 *
146 	 * Modification of a mini-object should only be done after verifying that it
147 	 * is writable.
148 	 *
149 	 * Return: %TRUE if the object is writable.
150 	 */
151 	public bool isWritable()
152 	{
153 		return gst_mini_object_is_writable(gstMiniObject) != 0;
154 	}
155 
156 	/**
157 	 * Lock the mini-object with the specified access mode in @flags.
158 	 *
159 	 * Params:
160 	 *     flags = #GstLockFlags
161 	 *
162 	 * Return: %TRUE if @object could be locked.
163 	 */
164 	public bool lock(GstLockFlags flags)
165 	{
166 		return gst_mini_object_lock(gstMiniObject, flags) != 0;
167 	}
168 
169 	/**
170 	 * Checks if a mini-object is writable.  If not, a writable copy is made and
171 	 * returned.  This gives away the reference to the original mini object,
172 	 * and returns a reference to the new object.
173 	 *
174 	 * MT safe
175 	 *
176 	 * Return: a mini-object (possibly the same pointer) that
177 	 *     is writable.
178 	 */
179 	public MiniObject makeWritable()
180 	{
181 		auto p = gst_mini_object_make_writable(gstMiniObject);
182 		
183 		if(p is null)
184 		{
185 			return null;
186 		}
187 		
188 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) p, true);
189 	}
190 
191 	/**
192 	 * Increase the reference count of the mini-object.
193 	 *
194 	 * Note that the refcount affects the writability
195 	 * of @mini-object, see gst_mini_object_is_writable(). It is
196 	 * important to note that keeping additional references to
197 	 * GstMiniObject instances can potentially increase the number
198 	 * of memcpy operations in a pipeline, especially if the miniobject
199 	 * is a #GstBuffer.
200 	 *
201 	 * Return: the mini-object.
202 	 */
203 	public MiniObject doref()
204 	{
205 		auto p = gst_mini_object_ref(gstMiniObject);
206 		
207 		if(p is null)
208 		{
209 			return null;
210 		}
211 		
212 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) p, true);
213 	}
214 
215 	/**
216 	 * This sets an opaque, named pointer on a miniobject.
217 	 * The name is specified through a #GQuark (retrieved e.g. via
218 	 * g_quark_from_static_string()), and the pointer
219 	 * can be gotten back from the @object with gst_mini_object_get_qdata()
220 	 * until the @object is disposed.
221 	 * Setting a previously set user data pointer, overrides (frees)
222 	 * the old pointer set, using %NULL as pointer essentially
223 	 * removes the data stored.
224 	 *
225 	 * @destroy may be specified which is called with @data as argument
226 	 * when the @object is disposed, or the data is being overwritten by
227 	 * a call to gst_mini_object_set_qdata() with the same @quark.
228 	 *
229 	 * Params:
230 	 *     quark = A #GQuark, naming the user data pointer
231 	 *     data = An opaque user data pointer
232 	 *     destroy = Function to invoke with @data as argument, when @data
233 	 *         needs to be freed
234 	 */
235 	public void setQdata(GQuark quark, void* data, GDestroyNotify destroy)
236 	{
237 		gst_mini_object_set_qdata(gstMiniObject, quark, data, destroy);
238 	}
239 
240 	/**
241 	 * This function gets back user data pointers stored via gst_mini_object_set_qdata()
242 	 * and removes the data from @object without invoking its destroy() function (if
243 	 * any was set).
244 	 *
245 	 * Params:
246 	 *     quark = A #GQuark, naming the user data pointer
247 	 *
248 	 * Return: The user data pointer set, or
249 	 *     %NULL
250 	 */
251 	public void* stealQdata(GQuark quark)
252 	{
253 		return gst_mini_object_steal_qdata(gstMiniObject, quark);
254 	}
255 
256 	/**
257 	 * Unlock the mini-object with the specified access mode in @flags.
258 	 *
259 	 * Params:
260 	 *     flags = #GstLockFlags
261 	 */
262 	public void unlock(GstLockFlags flags)
263 	{
264 		gst_mini_object_unlock(gstMiniObject, flags);
265 	}
266 
267 	/**
268 	 * Decreases the reference count of the mini-object, possibly freeing
269 	 * the mini-object.
270 	 */
271 	public void unref()
272 	{
273 		gst_mini_object_unref(gstMiniObject);
274 	}
275 
276 	/**
277 	 * Adds a weak reference callback to a mini object. Weak references are
278 	 * used for notification when a mini object is finalized. They are called
279 	 * "weak references" because they allow you to safely hold a pointer
280 	 * to the mini object without calling gst_mini_object_ref()
281 	 * (gst_mini_object_ref() adds a strong reference, that is, forces the object
282 	 * to stay alive).
283 	 *
284 	 * Params:
285 	 *     notify = callback to invoke before the mini object is freed
286 	 *     data = extra data to pass to notify
287 	 */
288 	public void weakRef(GstMiniObjectNotify notify, void* data)
289 	{
290 		gst_mini_object_weak_ref(gstMiniObject, notify, data);
291 	}
292 
293 	/**
294 	 * Removes a weak reference callback from a mini object.
295 	 *
296 	 * Params:
297 	 *     notify = callback to search for
298 	 *     data = data to search for
299 	 */
300 	public void weakUnref(GstMiniObjectNotify notify, void* data)
301 	{
302 		gst_mini_object_weak_unref(gstMiniObject, notify, data);
303 	}
304 
305 	/**
306 	 * Atomically modifies a pointer to point to a new mini-object.
307 	 * The reference count of @olddata is decreased and the reference count of
308 	 * @newdata is increased.
309 	 *
310 	 * Either @newdata and the value pointed to by @olddata may be %NULL.
311 	 *
312 	 * Params:
313 	 *     olddata = pointer to a pointer to a
314 	 *         mini-object to be replaced
315 	 *     newdata = pointer to new mini-object
316 	 *
317 	 * Return: %TRUE if @newdata was different from @olddata
318 	 */
319 	public static bool replace(ref MiniObject olddata, MiniObject newdata)
320 	{
321 		GstMiniObject* outolddata = olddata.getMiniObjectStruct();
322 		
323 		auto p = gst_mini_object_replace(&outolddata, (newdata is null) ? null : newdata.getMiniObjectStruct()) != 0;
324 		
325 		olddata = ObjectG.getDObject!(MiniObject)(outolddata);
326 		
327 		return p;
328 	}
329 
330 	/**
331 	 * Replace the current #GstMiniObject pointer to by @olddata with %NULL and
332 	 * return the old value.
333 	 *
334 	 * Params:
335 	 *     olddata = pointer to a pointer to a mini-object to
336 	 *         be stolen
337 	 *
338 	 * Return: the #GstMiniObject at @oldata
339 	 */
340 	public static MiniObject steal(ref MiniObject olddata)
341 	{
342 		GstMiniObject* outolddata = olddata.getMiniObjectStruct();
343 		
344 		auto p = gst_mini_object_steal(&outolddata);
345 		
346 		olddata = ObjectG.getDObject!(MiniObject)(outolddata);
347 		
348 		if(p is null)
349 		{
350 			return null;
351 		}
352 		
353 		return ObjectG.getDObject!(MiniObject)(cast(GstMiniObject*) p);
354 	}
355 
356 	/**
357 	 * Modifies a pointer to point to a new mini-object. The modification
358 	 * is done atomically. This version is similar to gst_mini_object_replace()
359 	 * except that it does not increase the refcount of @newdata and thus
360 	 * takes ownership of @newdata.
361 	 *
362 	 * Either @newdata and the value pointed to by @olddata may be %NULL.
363 	 *
364 	 * Params:
365 	 *     olddata = pointer to a pointer to a mini-object to
366 	 *         be replaced
367 	 *     newdata = pointer to new mini-object
368 	 *
369 	 * Return: %TRUE if @newdata was different from @olddata
370 	 */
371 	public static bool take(ref MiniObject olddata, MiniObject newdata)
372 	{
373 		GstMiniObject* outolddata = olddata.getMiniObjectStruct();
374 		
375 		auto p = gst_mini_object_take(&outolddata, (newdata is null) ? null : newdata.getMiniObjectStruct()) != 0;
376 		
377 		olddata = ObjectG.getDObject!(MiniObject)(outolddata);
378 		
379 		return p;
380 	}
381 }