gio.DBusNames source code

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.DBusNames;
26 
27 private import gio.DBusConnection;
28 private import gio.c.functions;
29 public  import gio.c.types;
30 private import glib.Str;
31 private import gobject.Closure;
32 
33 
34 /** */
35 public struct DBusNames
36 {
37 
38 	/**
39 	 * Starts acquiring @name on the bus specified by @bus_type and calls
40 	 * @name_acquired_handler and @name_lost_handler when the name is
41 	 * acquired respectively lost. Callbacks will be invoked in the
42 	 * [thread-default main context][g-main-context-push-thread-default]
43 	 * of the thread you are calling this function from.
44 	 *
45 	 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
46 	 * callbacks will be invoked after calling this function - there are three
47 	 * possible cases:
48 	 *
49 	 * - @name_lost_handler with a %NULL connection (if a connection to the bus
50 	 * can't be made).
51 	 *
52 	 * - @bus_acquired_handler then @name_lost_handler (if the name can't be
53 	 * obtained)
54 	 *
55 	 * - @bus_acquired_handler then @name_acquired_handler (if the name was
56 	 * obtained).
57 	 *
58 	 * When you are done owning the name, just call g_bus_unown_name()
59 	 * with the owner id this function returns.
60 	 *
61 	 * If the name is acquired or lost (for example another application
62 	 * could acquire the name if you allow replacement or the application
63 	 * currently owning the name exits), the handlers are also invoked.
64 	 * If the #GDBusConnection that is used for attempting to own the name
65 	 * closes, then @name_lost_handler is invoked since it is no longer
66 	 * possible for other processes to access the process.
67 	 *
68 	 * You cannot use g_bus_own_name() several times for the same name (unless
69 	 * interleaved with calls to g_bus_unown_name()) - only the first call
70 	 * will work.
71 	 *
72 	 * Another guarantee is that invocations of @name_acquired_handler
73 	 * and @name_lost_handler are guaranteed to alternate; that
74 	 * is, if @name_acquired_handler is invoked then you are
75 	 * guaranteed that the next time one of the handlers is invoked, it
76 	 * will be @name_lost_handler. The reverse is also true.
77 	 *
78 	 * If you plan on exporting objects (using e.g.
79 	 * g_dbus_connection_register_object()), note that it is generally too late
80 	 * to export the objects in @name_acquired_handler. Instead, you can do this
81 	 * in @bus_acquired_handler since you are guaranteed that this will run
82 	 * before @name is requested from the bus.
83 	 *
84 	 * This behavior makes it very simple to write applications that wants
85 	 * to [own names][gdbus-owning-names] and export objects.
86 	 * Simply register objects to be exported in @bus_acquired_handler and
87 	 * unregister the objects (if any) in @name_lost_handler.
88 	 *
89 	 * Params:
90 	 *     busType = the type of bus to own a name on
91 	 *     name = the well-known name to own
92 	 *     flags = a set of flags from the #GBusNameOwnerFlags enumeration
93 	 *     busAcquiredHandler = handler to invoke when connected to the bus of type @bus_type or %NULL
94 	 *     nameAcquiredHandler = handler to invoke when @name is acquired or %NULL
95 	 *     nameLostHandler = handler to invoke when @name is lost or %NULL
96 	 *     userData = user data to pass to handlers
97 	 *     userDataFreeFunc = function for freeing @user_data or %NULL
98 	 *
99 	 * Returns: an identifier (never 0) that can be used with
100 	 *     g_bus_unown_name() to stop owning the name.
101 	 *
102 	 * Since: 2.26
103 	 */
104 	public static uint ownName(GBusType busType, string name, GBusNameOwnerFlags flags, GBusAcquiredCallback busAcquiredHandler, GBusNameAcquiredCallback nameAcquiredHandler, GBusNameLostCallback nameLostHandler, void* userData, GDestroyNotify userDataFreeFunc)
105 	{
106 		return g_bus_own_name(busType, Str.toStringz(name), flags, busAcquiredHandler, nameAcquiredHandler, nameLostHandler, userData, userDataFreeFunc);
107 	}
108 
109 	/**
110 	 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
111 	 * #GBusType.
112 	 *
113 	 * Params:
114 	 *     connection = a #GDBusConnection
115 	 *     name = the well-known name to own
116 	 *     flags = a set of flags from the #GBusNameOwnerFlags enumeration
117 	 *     nameAcquiredHandler = handler to invoke when @name is acquired or %NULL
118 	 *     nameLostHandler = handler to invoke when @name is lost or %NULL
119 	 *     userData = user data to pass to handlers
120 	 *     userDataFreeFunc = function for freeing @user_data or %NULL
121 	 *
122 	 * Returns: an identifier (never 0) that can be used with
123 	 *     g_bus_unown_name() to stop owning the name
124 	 *
125 	 * Since: 2.26
126 	 */
127 	public static uint ownNameOnConnection(DBusConnection connection, string name, GBusNameOwnerFlags flags, GBusNameAcquiredCallback nameAcquiredHandler, GBusNameLostCallback nameLostHandler, void* userData, GDestroyNotify userDataFreeFunc)
128 	{
129 		return g_bus_own_name_on_connection((connection is null) ? null : connection.getDBusConnectionStruct(), Str.toStringz(name), flags, nameAcquiredHandler, nameLostHandler, userData, userDataFreeFunc);
130 	}
131 
132 	/**
133 	 * Version of g_bus_own_name_on_connection() using closures instead of
134 	 * callbacks for easier binding in other languages.
135 	 *
136 	 * Params:
137 	 *     connection = a #GDBusConnection
138 	 *     name = the well-known name to own
139 	 *     flags = a set of flags from the #GBusNameOwnerFlags enumeration
140 	 *     nameAcquiredClosure = #GClosure to invoke when @name is
141 	 *         acquired or %NULL
142 	 *     nameLostClosure = #GClosure to invoke when @name is lost
143 	 *         or %NULL
144 	 *
145 	 * Returns: an identifier (never 0) that can be used with
146 	 *     g_bus_unown_name() to stop owning the name.
147 	 *
148 	 * Since: 2.26
149 	 */
150 	public static uint ownNameOnConnectionWithClosures(DBusConnection connection, string name, GBusNameOwnerFlags flags, Closure nameAcquiredClosure, Closure nameLostClosure)
151 	{
152 		return g_bus_own_name_on_connection_with_closures((connection is null) ? null : connection.getDBusConnectionStruct(), Str.toStringz(name), flags, (nameAcquiredClosure is null) ? null : nameAcquiredClosure.getClosureStruct(), (nameLostClosure is null) ? null : nameLostClosure.getClosureStruct());
153 	}
154 
155 	/**
156 	 * Version of g_bus_own_name() using closures instead of callbacks for
157 	 * easier binding in other languages.
158 	 *
159 	 * Params:
160 	 *     busType = the type of bus to own a name on
161 	 *     name = the well-known name to own
162 	 *     flags = a set of flags from the #GBusNameOwnerFlags enumeration
163 	 *     busAcquiredClosure = #GClosure to invoke when connected to
164 	 *         the bus of type @bus_type or %NULL
165 	 *     nameAcquiredClosure = #GClosure to invoke when @name is
166 	 *         acquired or %NULL
167 	 *     nameLostClosure = #GClosure to invoke when @name is lost or
168 	 *         %NULL
169 	 *
170 	 * Returns: an identifier (never 0) that can be used with
171 	 *     g_bus_unown_name() to stop owning the name.
172 	 *
173 	 * Since: 2.26
174 	 */
175 	public static uint ownNameWithClosures(GBusType busType, string name, GBusNameOwnerFlags flags, Closure busAcquiredClosure, Closure nameAcquiredClosure, Closure nameLostClosure)
176 	{
177 		return g_bus_own_name_with_closures(busType, Str.toStringz(name), flags, (busAcquiredClosure is null) ? null : busAcquiredClosure.getClosureStruct(), (nameAcquiredClosure is null) ? null : nameAcquiredClosure.getClosureStruct(), (nameLostClosure is null) ? null : nameLostClosure.getClosureStruct());
178 	}
179 
180 	/**
181 	 * Stops owning a name.
182 	 *
183 	 * Note that there may still be D-Bus traffic to process (relating to owning
184 	 * and unowning the name) in the current thread-default #GMainContext after
185 	 * this function has returned. You should continue to iterate the #GMainContext
186 	 * until the #GDestroyNotify function passed to g_bus_own_name() is called, in
187 	 * order to avoid memory leaks through callbacks queued on the #GMainContext
188 	 * after it’s stopped being iterated.
189 	 *
190 	 * Params:
191 	 *     ownerId = an identifier obtained from g_bus_own_name()
192 	 *
193 	 * Since: 2.26
194 	 */
195 	public static void unownName(uint ownerId)
196 	{
197 		g_bus_unown_name(ownerId);
198 	}
199 
200 	/**
201 	 * Stops watching a name.
202 	 *
203 	 * Note that there may still be D-Bus traffic to process (relating to watching
204 	 * and unwatching the name) in the current thread-default #GMainContext after
205 	 * this function has returned. You should continue to iterate the #GMainContext
206 	 * until the #GDestroyNotify function passed to g_bus_watch_name() is called, in
207 	 * order to avoid memory leaks through callbacks queued on the #GMainContext
208 	 * after it’s stopped being iterated.
209 	 *
210 	 * Params:
211 	 *     watcherId = An identifier obtained from g_bus_watch_name()
212 	 *
213 	 * Since: 2.26
214 	 */
215 	public static void unwatchName(uint watcherId)
216 	{
217 		g_bus_unwatch_name(watcherId);
218 	}
219 
220 	/**
221 	 * Starts watching @name on the bus specified by @bus_type and calls
222 	 * @name_appeared_handler and @name_vanished_handler when the name is
223 	 * known to have an owner respectively known to lose its
224 	 * owner. Callbacks will be invoked in the
225 	 * [thread-default main context][g-main-context-push-thread-default]
226 	 * of the thread you are calling this function from.
227 	 *
228 	 * You are guaranteed that one of the handlers will be invoked after
229 	 * calling this function. When you are done watching the name, just
230 	 * call g_bus_unwatch_name() with the watcher id this function
231 	 * returns.
232 	 *
233 	 * If the name vanishes or appears (for example the application owning
234 	 * the name could restart), the handlers are also invoked. If the
235 	 * #GDBusConnection that is used for watching the name disconnects, then
236 	 * @name_vanished_handler is invoked since it is no longer
237 	 * possible to access the name.
238 	 *
239 	 * Another guarantee is that invocations of @name_appeared_handler
240 	 * and @name_vanished_handler are guaranteed to alternate; that
241 	 * is, if @name_appeared_handler is invoked then you are
242 	 * guaranteed that the next time one of the handlers is invoked, it
243 	 * will be @name_vanished_handler. The reverse is also true.
244 	 *
245 	 * This behavior makes it very simple to write applications that want
246 	 * to take action when a certain [name exists][gdbus-watching-names].
247 	 * Basically, the application should create object proxies in
248 	 * @name_appeared_handler and destroy them again (if any) in
249 	 * @name_vanished_handler.
250 	 *
251 	 * Params:
252 	 *     busType = The type of bus to watch a name on.
253 	 *     name = The name (well-known or unique) to watch.
254 	 *     flags = Flags from the #GBusNameWatcherFlags enumeration.
255 	 *     nameAppearedHandler = Handler to invoke when @name is known to exist or %NULL.
256 	 *     nameVanishedHandler = Handler to invoke when @name is known to not exist or %NULL.
257 	 *     userData = User data to pass to handlers.
258 	 *     userDataFreeFunc = Function for freeing @user_data or %NULL.
259 	 *
260 	 * Returns: An identifier (never 0) that can be used with
261 	 *     g_bus_unwatch_name() to stop watching the name.
262 	 *
263 	 * Since: 2.26
264 	 */
265 	public static uint watchName(GBusType busType, string name, GBusNameWatcherFlags flags, GBusNameAppearedCallback nameAppearedHandler, GBusNameVanishedCallback nameVanishedHandler, void* userData, GDestroyNotify userDataFreeFunc)
266 	{
267 		return g_bus_watch_name(busType, Str.toStringz(name), flags, nameAppearedHandler, nameVanishedHandler, userData, userDataFreeFunc);
268 	}
269 
270 	/**
271 	 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
272 	 * #GBusType.
273 	 *
274 	 * Params:
275 	 *     connection = A #GDBusConnection.
276 	 *     name = The name (well-known or unique) to watch.
277 	 *     flags = Flags from the #GBusNameWatcherFlags enumeration.
278 	 *     nameAppearedHandler = Handler to invoke when @name is known to exist or %NULL.
279 	 *     nameVanishedHandler = Handler to invoke when @name is known to not exist or %NULL.
280 	 *     userData = User data to pass to handlers.
281 	 *     userDataFreeFunc = Function for freeing @user_data or %NULL.
282 	 *
283 	 * Returns: An identifier (never 0) that can be used with
284 	 *     g_bus_unwatch_name() to stop watching the name.
285 	 *
286 	 * Since: 2.26
287 	 */
288 	public static uint watchNameOnConnection(DBusConnection connection, string name, GBusNameWatcherFlags flags, GBusNameAppearedCallback nameAppearedHandler, GBusNameVanishedCallback nameVanishedHandler, void* userData, GDestroyNotify userDataFreeFunc)
289 	{
290 		return g_bus_watch_name_on_connection((connection is null) ? null : connection.getDBusConnectionStruct(), Str.toStringz(name), flags, nameAppearedHandler, nameVanishedHandler, userData, userDataFreeFunc);
291 	}
292 
293 	/**
294 	 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
295 	 * easier binding in other languages.
296 	 *
297 	 * Params:
298 	 *     connection = A #GDBusConnection.
299 	 *     name = The name (well-known or unique) to watch.
300 	 *     flags = Flags from the #GBusNameWatcherFlags enumeration.
301 	 *     nameAppearedClosure = #GClosure to invoke when @name is known
302 	 *         to exist or %NULL.
303 	 *     nameVanishedClosure = #GClosure to invoke when @name is known
304 	 *         to not exist or %NULL.
305 	 *
306 	 * Returns: An identifier (never 0) that can be used with
307 	 *     g_bus_unwatch_name() to stop watching the name.
308 	 *
309 	 * Since: 2.26
310 	 */
311 	public static uint watchNameOnConnectionWithClosures(DBusConnection connection, string name, GBusNameWatcherFlags flags, Closure nameAppearedClosure, Closure nameVanishedClosure)
312 	{
313 		return g_bus_watch_name_on_connection_with_closures((connection is null) ? null : connection.getDBusConnectionStruct(), Str.toStringz(name), flags, (nameAppearedClosure is null) ? null : nameAppearedClosure.getClosureStruct(), (nameVanishedClosure is null) ? null : nameVanishedClosure.getClosureStruct());
314 	}
315 
316 	/**
317 	 * Version of g_bus_watch_name() using closures instead of callbacks for
318 	 * easier binding in other languages.
319 	 *
320 	 * Params:
321 	 *     busType = The type of bus to watch a name on.
322 	 *     name = The name (well-known or unique) to watch.
323 	 *     flags = Flags from the #GBusNameWatcherFlags enumeration.
324 	 *     nameAppearedClosure = #GClosure to invoke when @name is known
325 	 *         to exist or %NULL.
326 	 *     nameVanishedClosure = #GClosure to invoke when @name is known
327 	 *         to not exist or %NULL.
328 	 *
329 	 * Returns: An identifier (never 0) that can be used with
330 	 *     g_bus_unwatch_name() to stop watching the name.
331 	 *
332 	 * Since: 2.26
333 	 */
334 	public static uint watchNameWithClosures(GBusType busType, string name, GBusNameWatcherFlags flags, Closure nameAppearedClosure, Closure nameVanishedClosure)
335 	{
336 		return g_bus_watch_name_with_closures(busType, Str.toStringz(name), flags, (nameAppearedClosure is null) ? null : nameAppearedClosure.getClosureStruct(), (nameVanishedClosure is null) ? null : nameVanishedClosure.getClosureStruct());
337 	}
338 }