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