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 gio.DBusObjectManagerClient;
26 
27 private import gio.AsyncInitableIF;
28 private import gio.AsyncInitableT;
29 private import gio.Cancellable;
30 private import gio.DBusConnection;
31 private import gio.DBusObjectManagerIF;
32 private import gio.DBusObjectManagerT;
33 private import gio.DBusObjectProxy;
34 private import gio.DBusProxy;
35 private import gio.InitableIF;
36 private import gio.InitableT;
37 private import gio.c.functions;
38 public  import gio.c.types;
39 private import glib.ConstructionException;
40 private import glib.ErrorG;
41 private import glib.GException;
42 private import glib.Str;
43 private import glib.Variant;
44 private import glib.c.functions;
45 private import gobject.ObjectG;
46 private import gobject.Signals;
47 private import std.algorithm;
48 
49 
50 /**
51  * #GDBusObjectManagerClient is used to create, monitor and delete object
52  * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
53  * code implementing the
54  * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
55  * interface).
56  * 
57  * Once an instance of this type has been created, you can connect to
58  * the #GDBusObjectManager::object-added and
59  * #GDBusObjectManager::object-removed signals and inspect the
60  * #GDBusObjectProxy objects returned by
61  * g_dbus_object_manager_get_objects().
62  * 
63  * If the name for a #GDBusObjectManagerClient is not owned by anyone at
64  * object construction time, the default behavior is to request the
65  * message bus to launch an owner for the name. This behavior can be
66  * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
67  * flag. It's also worth noting that this only works if the name of
68  * interest is activatable in the first place. E.g. in some cases it
69  * is not possible to launch an owner for the requested name. In this
70  * case, #GDBusObjectManagerClient object construction still succeeds but
71  * there will be no object proxies
72  * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
73  * the #GDBusObjectManagerClient:name-owner property is %NULL.
74  * 
75  * The owner of the requested name can come and go (for example
76  * consider a system service being restarted) – #GDBusObjectManagerClient
77  * handles this case too; simply connect to the #GObject::notify
78  * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
79  * property. When the name owner vanishes, the behavior is that
80  * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
81  * emission of the #GObject::notify signal) and then
82  * #GDBusObjectManager::object-removed signals are synthesized
83  * for all currently existing object proxies. Since
84  * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
85  * use this information to disambiguate a synthesized signal from a
86  * genuine signal caused by object removal on the remote
87  * #GDBusObjectManager. Similarly, when a new name owner appears,
88  * #GDBusObjectManager::object-added signals are synthesized
89  * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
90  * object proxies have been added, the #GDBusObjectManagerClient:name-owner
91  * is set to the new name owner (this includes emission of the
92  * #GObject::notify signal).  Furthermore, you are guaranteed that
93  * #GDBusObjectManagerClient:name-owner will alternate between a name owner
94  * (e.g. `:1.42`) and %NULL even in the case where
95  * the name of interest is atomically replaced
96  * 
97  * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
98  * instances. All signals (including the
99  * org.freedesktop.DBus.Properties::PropertiesChanged signal)
100  * delivered to #GDBusProxy instances are guaranteed to originate
101  * from the name owner. This guarantee along with the behavior
102  * described above, means that certain race conditions including the
103  * "half the proxy is from the old owner and the other half is from
104  * the new owner" problem cannot happen.
105  * 
106  * To avoid having the application connect to signals on the returned
107  * #GDBusObjectProxy and #GDBusProxy objects, the
108  * #GDBusObject::interface-added,
109  * #GDBusObject::interface-removed,
110  * #GDBusProxy::g-properties-changed and
111  * #GDBusProxy::g-signal signals
112  * are also emitted on the #GDBusObjectManagerClient instance managing these
113  * objects. The signals emitted are
114  * #GDBusObjectManager::interface-added,
115  * #GDBusObjectManager::interface-removed,
116  * #GDBusObjectManagerClient::interface-proxy-properties-changed and
117  * #GDBusObjectManagerClient::interface-proxy-signal.
118  * 
119  * Note that all callbacks and signals are emitted in the
120  * [thread-default main context][g-main-context-push-thread-default]
121  * that the #GDBusObjectManagerClient object was constructed
122  * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
123  * originating from the #GDBusObjectManagerClient object will be created in
124  * the same context and, consequently, will deliver signals in the
125  * same main loop.
126  *
127  * Since: 2.30
128  */
129 public class DBusObjectManagerClient : ObjectG, AsyncInitableIF, DBusObjectManagerIF, InitableIF
130 {
131 	/** the main Gtk struct */
132 	protected GDBusObjectManagerClient* gDBusObjectManagerClient;
133 
134 	/** Get the main Gtk struct */
135 	public GDBusObjectManagerClient* getDBusObjectManagerClientStruct(bool transferOwnership = false)
136 	{
137 		if (transferOwnership)
138 			ownedRef = false;
139 		return gDBusObjectManagerClient;
140 	}
141 
142 	/** the main Gtk struct as a void* */
143 	protected override void* getStruct()
144 	{
145 		return cast(void*)gDBusObjectManagerClient;
146 	}
147 
148 	/**
149 	 * Sets our main struct and passes it to the parent class.
150 	 */
151 	public this (GDBusObjectManagerClient* gDBusObjectManagerClient, bool ownedRef = false)
152 	{
153 		this.gDBusObjectManagerClient = gDBusObjectManagerClient;
154 		super(cast(GObject*)gDBusObjectManagerClient, ownedRef);
155 	}
156 
157 	// add the AsyncInitable capabilities
158 	mixin AsyncInitableT!(GDBusObjectManagerClient);
159 
160 	// add the DBusObjectManager capabilities
161 	mixin DBusObjectManagerT!(GDBusObjectManagerClient);
162 
163 	// add the Initable capabilities
164 	mixin InitableT!(GDBusObjectManagerClient);
165 
166 	/**
167 	 * Finishes an operation started with g_dbus_object_manager_client_new().
168 	 *
169 	 * Params:
170 	 *     res    = A GAsyncResult obtained from the GAsyncReadyCallback passed to the DBusObjectManager constructor.
171 	 *     forBus = If true finish an address.
172 	 *
173 	 * Throws: GException on failure.
174 	 * Throws: ConstructionException GTK+ fails to create the object.
175 	 *
176 	 * Since: 2.30
177 	 */
178 	public this (AsyncResultIF res, bool forBus = false)
179 	{
180 		GError* err = null;
181 		GDBusObjectManager* p;
182 
183 		if ( forBus )
184 		{
185 			p = g_dbus_object_manager_client_new_for_bus_finish((res is null) ? null : res.getAsyncResultStruct(), &err);
186 		}
187 		else
188 		{
189 			p = g_dbus_object_manager_client_new_finish((res is null) ? null : res.getAsyncResultStruct(), &err);
190 		}
191 
192 		if (err !is null)
193 		{
194 			throw new GException( new ErrorG(err) );
195 		}
196 
197 		if(p is null)
198 		{
199 			throw new ConstructionException("null returned by g_dbus_object_manager_client_new_finish((res is null) ? null : res.getAsyncResultStruct(), &err)");
200 		}
201 		this(cast(GDBusObjectManagerClient*) p, true);
202 	}
203 
204 	/**
205 	 */
206 
207 	/** */
208 	public static GType getType()
209 	{
210 		return g_dbus_object_manager_client_get_type();
211 	}
212 
213 	/**
214 	 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
215 	 * of a #GDBusConnection.
216 	 *
217 	 * This is a synchronous failable constructor - the calling thread is
218 	 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
219 	 * for the asynchronous version.
220 	 *
221 	 * Params:
222 	 *     busType = A #GBusType.
223 	 *     flags = Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
224 	 *     name = The owner of the control object (unique or well-known name).
225 	 *     objectPath = The object path of the control object.
226 	 *     getProxyTypeFunc = A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
227 	 *     getProxyTypeUserData = User data to pass to @get_proxy_type_func.
228 	 *     getProxyTypeDestroyNotify = Free function for @get_proxy_type_user_data or %NULL.
229 	 *     cancellable = A #GCancellable or %NULL
230 	 *
231 	 * Returns: A
232 	 *     #GDBusObjectManagerClient object or %NULL if @error is set. Free
233 	 *     with g_object_unref().
234 	 *
235 	 * Since: 2.30
236 	 *
237 	 * Throws: GException on failure.
238 	 * Throws: ConstructionException GTK+ fails to create the object.
239 	 */
240 	public this(GBusType busType, GDBusObjectManagerClientFlags flags, string name, string objectPath, GDBusProxyTypeFunc getProxyTypeFunc, void* getProxyTypeUserData, GDestroyNotify getProxyTypeDestroyNotify, Cancellable cancellable)
241 	{
242 		GError* err = null;
243 
244 		auto __p = g_dbus_object_manager_client_new_for_bus_sync(busType, flags, Str.toStringz(name), Str.toStringz(objectPath), getProxyTypeFunc, getProxyTypeUserData, getProxyTypeDestroyNotify, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
245 
246 		if (err !is null)
247 		{
248 			throw new GException( new ErrorG(err) );
249 		}
250 
251 		if(__p is null)
252 		{
253 			throw new ConstructionException("null returned by new_for_bus_sync");
254 		}
255 
256 		this(cast(GDBusObjectManagerClient*) __p, true);
257 	}
258 
259 	/**
260 	 * Creates a new #GDBusObjectManagerClient object.
261 	 *
262 	 * This is a synchronous failable constructor - the calling thread is
263 	 * blocked until a reply is received. See g_dbus_object_manager_client_new()
264 	 * for the asynchronous version.
265 	 *
266 	 * Params:
267 	 *     connection = A #GDBusConnection.
268 	 *     flags = Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
269 	 *     name = The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection.
270 	 *     objectPath = The object path of the control object.
271 	 *     getProxyTypeFunc = A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
272 	 *     getProxyTypeUserData = User data to pass to @get_proxy_type_func.
273 	 *     getProxyTypeDestroyNotify = Free function for @get_proxy_type_user_data or %NULL.
274 	 *     cancellable = A #GCancellable or %NULL
275 	 *
276 	 * Returns: A
277 	 *     #GDBusObjectManagerClient object or %NULL if @error is set. Free
278 	 *     with g_object_unref().
279 	 *
280 	 * Since: 2.30
281 	 *
282 	 * Throws: GException on failure.
283 	 * Throws: ConstructionException GTK+ fails to create the object.
284 	 */
285 	public this(DBusConnection connection, GDBusObjectManagerClientFlags flags, string name, string objectPath, GDBusProxyTypeFunc getProxyTypeFunc, void* getProxyTypeUserData, GDestroyNotify getProxyTypeDestroyNotify, Cancellable cancellable)
286 	{
287 		GError* err = null;
288 
289 		auto __p = g_dbus_object_manager_client_new_sync((connection is null) ? null : connection.getDBusConnectionStruct(), flags, Str.toStringz(name), Str.toStringz(objectPath), getProxyTypeFunc, getProxyTypeUserData, getProxyTypeDestroyNotify, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
290 
291 		if (err !is null)
292 		{
293 			throw new GException( new ErrorG(err) );
294 		}
295 
296 		if(__p is null)
297 		{
298 			throw new ConstructionException("null returned by new_sync");
299 		}
300 
301 		this(cast(GDBusObjectManagerClient*) __p, true);
302 	}
303 
304 	/**
305 	 * Asynchronously creates a new #GDBusObjectManagerClient object.
306 	 *
307 	 * This is an asynchronous failable constructor. When the result is
308 	 * ready, @callback will be invoked in the
309 	 * [thread-default main context][g-main-context-push-thread-default]
310 	 * of the thread you are calling this method from. You can
311 	 * then call g_dbus_object_manager_client_new_finish() to get the result. See
312 	 * g_dbus_object_manager_client_new_sync() for the synchronous version.
313 	 *
314 	 * Params:
315 	 *     connection = A #GDBusConnection.
316 	 *     flags = Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
317 	 *     name = The owner of the control object (unique or well-known name).
318 	 *     objectPath = The object path of the control object.
319 	 *     getProxyTypeFunc = A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
320 	 *     getProxyTypeUserData = User data to pass to @get_proxy_type_func.
321 	 *     getProxyTypeDestroyNotify = Free function for @get_proxy_type_user_data or %NULL.
322 	 *     cancellable = A #GCancellable or %NULL
323 	 *     callback = A #GAsyncReadyCallback to call when the request is satisfied.
324 	 *     userData = The data to pass to @callback.
325 	 *
326 	 * Since: 2.30
327 	 */
328 	public static void new_(DBusConnection connection, GDBusObjectManagerClientFlags flags, string name, string objectPath, GDBusProxyTypeFunc getProxyTypeFunc, void* getProxyTypeUserData, GDestroyNotify getProxyTypeDestroyNotify, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
329 	{
330 		g_dbus_object_manager_client_new((connection is null) ? null : connection.getDBusConnectionStruct(), flags, Str.toStringz(name), Str.toStringz(objectPath), getProxyTypeFunc, getProxyTypeUserData, getProxyTypeDestroyNotify, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
331 	}
332 
333 	/**
334 	 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
335 	 * #GDBusConnection.
336 	 *
337 	 * This is an asynchronous failable constructor. When the result is
338 	 * ready, @callback will be invoked in the
339 	 * [thread-default main loop][g-main-context-push-thread-default]
340 	 * of the thread you are calling this method from. You can
341 	 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
342 	 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
343 	 *
344 	 * Params:
345 	 *     busType = A #GBusType.
346 	 *     flags = Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
347 	 *     name = The owner of the control object (unique or well-known name).
348 	 *     objectPath = The object path of the control object.
349 	 *     getProxyTypeFunc = A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
350 	 *     getProxyTypeUserData = User data to pass to @get_proxy_type_func.
351 	 *     getProxyTypeDestroyNotify = Free function for @get_proxy_type_user_data or %NULL.
352 	 *     cancellable = A #GCancellable or %NULL
353 	 *     callback = A #GAsyncReadyCallback to call when the request is satisfied.
354 	 *     userData = The data to pass to @callback.
355 	 *
356 	 * Since: 2.30
357 	 */
358 	public static void newForBus(GBusType busType, GDBusObjectManagerClientFlags flags, string name, string objectPath, GDBusProxyTypeFunc getProxyTypeFunc, void* getProxyTypeUserData, GDestroyNotify getProxyTypeDestroyNotify, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
359 	{
360 		g_dbus_object_manager_client_new_for_bus(busType, flags, Str.toStringz(name), Str.toStringz(objectPath), getProxyTypeFunc, getProxyTypeUserData, getProxyTypeDestroyNotify, (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
361 	}
362 
363 	/**
364 	 * Gets the #GDBusConnection used by @manager.
365 	 *
366 	 * Returns: A #GDBusConnection object. Do not free,
367 	 *     the object belongs to @manager.
368 	 *
369 	 * Since: 2.30
370 	 */
371 	public DBusConnection getConnection()
372 	{
373 		auto __p = g_dbus_object_manager_client_get_connection(gDBusObjectManagerClient);
374 
375 		if(__p is null)
376 		{
377 			return null;
378 		}
379 
380 		return ObjectG.getDObject!(DBusConnection)(cast(GDBusConnection*) __p);
381 	}
382 
383 	/**
384 	 * Gets the flags that @manager was constructed with.
385 	 *
386 	 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
387 	 *     enumeration.
388 	 *
389 	 * Since: 2.30
390 	 */
391 	public GDBusObjectManagerClientFlags getFlags()
392 	{
393 		return g_dbus_object_manager_client_get_flags(gDBusObjectManagerClient);
394 	}
395 
396 	/**
397 	 * Gets the name that @manager is for, or %NULL if not a message bus
398 	 * connection.
399 	 *
400 	 * Returns: A unique or well-known name. Do not free, the string
401 	 *     belongs to @manager.
402 	 *
403 	 * Since: 2.30
404 	 */
405 	public string getName()
406 	{
407 		return Str.toString(g_dbus_object_manager_client_get_name(gDBusObjectManagerClient));
408 	}
409 
410 	/**
411 	 * The unique name that owns the name that @manager is for or %NULL if
412 	 * no-one currently owns that name. You can connect to the
413 	 * #GObject::notify signal to track changes to the
414 	 * #GDBusObjectManagerClient:name-owner property.
415 	 *
416 	 * Returns: The name owner or %NULL if no name owner
417 	 *     exists. Free with g_free().
418 	 *
419 	 * Since: 2.30
420 	 */
421 	public string getNameOwner()
422 	{
423 		auto retStr = g_dbus_object_manager_client_get_name_owner(gDBusObjectManagerClient);
424 
425 		scope(exit) Str.freeString(retStr);
426 		return Str.toString(retStr);
427 	}
428 
429 	/**
430 	 * Emitted when one or more D-Bus properties on proxy changes. The
431 	 * local cache has already been updated when this signal fires. Note
432 	 * that both @changed_properties and @invalidated_properties are
433 	 * guaranteed to never be %NULL (either may be empty though).
434 	 *
435 	 * This signal exists purely as a convenience to avoid having to
436 	 * connect signals to all interface proxies managed by @manager.
437 	 *
438 	 * This signal is emitted in the
439 	 * [thread-default main context][g-main-context-push-thread-default]
440 	 * that @manager was constructed in.
441 	 *
442 	 * Params:
443 	 *     objectProxy = The #GDBusObjectProxy on which an interface has properties that are changing.
444 	 *     interfaceProxy = The #GDBusProxy that has properties that are changing.
445 	 *     changedProperties = A #GVariant containing the properties that changed (type: `a{sv}`).
446 	 *     invalidatedProperties = A %NULL terminated
447 	 *         array of properties that were invalidated.
448 	 *
449 	 * Since: 2.30
450 	 */
451 	gulong addOnInterfaceProxyPropertiesChanged(void delegate(DBusObjectProxy, DBusProxy, Variant, string[], DBusObjectManagerClient) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
452 	{
453 		return Signals.connect(this, "interface-proxy-properties-changed", dlg, connectFlags ^ ConnectFlags.SWAPPED);
454 	}
455 
456 	/**
457 	 * Emitted when a D-Bus signal is received on @interface_proxy.
458 	 *
459 	 * This signal exists purely as a convenience to avoid having to
460 	 * connect signals to all interface proxies managed by @manager.
461 	 *
462 	 * This signal is emitted in the
463 	 * [thread-default main context][g-main-context-push-thread-default]
464 	 * that @manager was constructed in.
465 	 *
466 	 * Params:
467 	 *     objectProxy = The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
468 	 *     interfaceProxy = The #GDBusProxy that is emitting a D-Bus signal.
469 	 *     senderName = The sender of the signal or NULL if the connection is not a bus connection.
470 	 *     signalName = The signal name.
471 	 *     parameters = A #GVariant tuple with parameters for the signal.
472 	 *
473 	 * Since: 2.30
474 	 */
475 	gulong addOnInterfaceProxySignal(void delegate(DBusObjectProxy, DBusProxy, string, string, Variant, DBusObjectManagerClient) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
476 	{
477 		return Signals.connect(this, "interface-proxy-signal", dlg, connectFlags ^ ConnectFlags.SWAPPED);
478 	}
479 }