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.DBusUtilities;
26 
27 private import gio.AsyncResultIF;
28 private import gio.Cancellable;
29 private import gio.IOStream;
30 private import gio.c.functions;
31 public  import gio.c.types;
32 private import glib.ErrorG;
33 private import glib.GException;
34 private import glib.MemorySlice;
35 private import glib.Str;
36 private import glib.Variant;
37 private import glib.VariantType;
38 private import gobject.ObjectG;
39 private import gobject.Value;
40 public  import gtkc.giotypes;
41 
42 
43 /** */
44 public struct DBusUtilities
45 {
46 
47 	/**
48 	 * Escape @string so it can appear in a D-Bus address as the value
49 	 * part of a key-value pair.
50 	 *
51 	 * For instance, if @string is `/run/bus-for-:0`,
52 	 * this function would return `/run/bus-for-%3A0`,
53 	 * which could be used in a D-Bus address like
54 	 * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`.
55 	 *
56 	 * Params:
57 	 *     str = an unescaped string to be included in a D-Bus address
58 	 *         as the value in a key-value pair
59 	 *
60 	 * Returns: a copy of @string with all
61 	 *     non-optionally-escaped bytes escaped
62 	 *
63 	 * Since: 2.36
64 	 */
65 	public static string addressEscapeValue(string str)
66 	{
67 		auto retStr = g_dbus_address_escape_value(Str.toStringz(str));
68 
69 		scope(exit) Str.freeString(retStr);
70 		return Str.toString(retStr);
71 	}
72 
73 	/**
74 	 * Synchronously looks up the D-Bus address for the well-known message
75 	 * bus instance specified by @bus_type. This may involve using various
76 	 * platform specific mechanisms.
77 	 *
78 	 * The returned address will be in the
79 	 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
80 	 *
81 	 * Params:
82 	 *     busType = a #GBusType
83 	 *     cancellable = a #GCancellable or %NULL
84 	 *
85 	 * Returns: a valid D-Bus address string for @bus_type or %NULL if
86 	 *     @error is set
87 	 *
88 	 * Since: 2.26
89 	 *
90 	 * Throws: GException on failure.
91 	 */
92 	public static string addressGetForBusSync(GBusType busType, Cancellable cancellable)
93 	{
94 		GError* err = null;
95 
96 		auto retStr = g_dbus_address_get_for_bus_sync(busType, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
97 
98 		if (err !is null)
99 		{
100 			throw new GException( new ErrorG(err) );
101 		}
102 
103 		scope(exit) Str.freeString(retStr);
104 		return Str.toString(retStr);
105 	}
106 
107 	/**
108 	 * Asynchronously connects to an endpoint specified by @address and
109 	 * sets up the connection so it is in a state to run the client-side
110 	 * of the D-Bus authentication conversation. @address must be in the
111 	 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
112 	 *
113 	 * When the operation is finished, @callback will be invoked. You can
114 	 * then call g_dbus_address_get_stream_finish() to get the result of
115 	 * the operation.
116 	 *
117 	 * This is an asynchronous failable function. See
118 	 * g_dbus_address_get_stream_sync() for the synchronous version.
119 	 *
120 	 * Params:
121 	 *     address = A valid D-Bus address.
122 	 *     cancellable = A #GCancellable or %NULL.
123 	 *     callback = A #GAsyncReadyCallback to call when the request is satisfied.
124 	 *     userData = Data to pass to @callback.
125 	 *
126 	 * Since: 2.26
127 	 */
128 	public static void addressGetStream(string address, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
129 	{
130 		g_dbus_address_get_stream(Str.toStringz(address), (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
131 	}
132 
133 	/**
134 	 * Finishes an operation started with g_dbus_address_get_stream().
135 	 *
136 	 * Params:
137 	 *     res = A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
138 	 *     outGuid = %NULL or return location to store the GUID extracted from @address, if any.
139 	 *
140 	 * Returns: A #GIOStream or %NULL if @error is set.
141 	 *
142 	 * Since: 2.26
143 	 *
144 	 * Throws: GException on failure.
145 	 */
146 	public static IOStream addressGetStreamFinish(AsyncResultIF res, out string outGuid)
147 	{
148 		char* outoutGuid = null;
149 		GError* err = null;
150 
151 		auto p = g_dbus_address_get_stream_finish((res is null) ? null : res.getAsyncResultStruct(), &outoutGuid, &err);
152 
153 		if (err !is null)
154 		{
155 			throw new GException( new ErrorG(err) );
156 		}
157 
158 		outGuid = Str.toString(outoutGuid);
159 
160 		if(p is null)
161 		{
162 			return null;
163 		}
164 
165 		return ObjectG.getDObject!(IOStream)(cast(GIOStream*) p, true);
166 	}
167 
168 	/**
169 	 * Synchronously connects to an endpoint specified by @address and
170 	 * sets up the connection so it is in a state to run the client-side
171 	 * of the D-Bus authentication conversation. @address must be in the
172 	 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
173 	 *
174 	 * This is a synchronous failable function. See
175 	 * g_dbus_address_get_stream() for the asynchronous version.
176 	 *
177 	 * Params:
178 	 *     address = A valid D-Bus address.
179 	 *     outGuid = %NULL or return location to store the GUID extracted from @address, if any.
180 	 *     cancellable = A #GCancellable or %NULL.
181 	 *
182 	 * Returns: A #GIOStream or %NULL if @error is set.
183 	 *
184 	 * Since: 2.26
185 	 *
186 	 * Throws: GException on failure.
187 	 */
188 	public static IOStream addressGetStreamSync(string address, out string outGuid, Cancellable cancellable)
189 	{
190 		char* outoutGuid = null;
191 		GError* err = null;
192 
193 		auto p = g_dbus_address_get_stream_sync(Str.toStringz(address), &outoutGuid, (cancellable is null) ? null : cancellable.getCancellableStruct(), &err);
194 
195 		if (err !is null)
196 		{
197 			throw new GException( new ErrorG(err) );
198 		}
199 
200 		outGuid = Str.toString(outoutGuid);
201 
202 		if(p is null)
203 		{
204 			return null;
205 		}
206 
207 		return ObjectG.getDObject!(IOStream)(cast(GIOStream*) p, true);
208 	}
209 
210 	/**
211 	 * Generate a D-Bus GUID that can be used with
212 	 * e.g. g_dbus_connection_new().
213 	 *
214 	 * See the D-Bus specification regarding what strings are valid D-Bus
215 	 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
216 	 *
217 	 * Returns: A valid D-Bus GUID. Free with g_free().
218 	 *
219 	 * Since: 2.26
220 	 */
221 	public static string generateGuid()
222 	{
223 		auto retStr = g_dbus_generate_guid();
224 
225 		scope(exit) Str.freeString(retStr);
226 		return Str.toString(retStr);
227 	}
228 
229 	/**
230 	 * Converts a #GValue to a #GVariant of the type indicated by the @type
231 	 * parameter.
232 	 *
233 	 * The conversion is using the following rules:
234 	 *
235 	 * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay'
236 	 * - #G_TYPE_STRV: 'as', 'ao' or 'aay'
237 	 * - #G_TYPE_BOOLEAN: 'b'
238 	 * - #G_TYPE_UCHAR: 'y'
239 	 * - #G_TYPE_INT: 'i', 'n'
240 	 * - #G_TYPE_UINT: 'u', 'q'
241 	 * - #G_TYPE_INT64 'x'
242 	 * - #G_TYPE_UINT64: 't'
243 	 * - #G_TYPE_DOUBLE: 'd'
244 	 * - #G_TYPE_VARIANT: Any #GVariantType
245 	 *
246 	 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
247 	 * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
248 	 * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
249 	 * in the table above.
250 	 *
251 	 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
252 	 * %NULL, the empty #GVariant instance (never %NULL) for @type is
253 	 * returned (e.g. 0 for scalar types, the empty string for string types,
254 	 * '/' for object path types, the empty array for any array type and so on).
255 	 *
256 	 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
257 	 * #GVariant to a #GValue.
258 	 *
259 	 * Params:
260 	 *     gvalue = A #GValue to convert to a #GVariant
261 	 *     type = A #GVariantType
262 	 *
263 	 * Returns: A #GVariant (never floating) of #GVariantType @type holding
264 	 *     the data from @gvalue or %NULL in case of failure. Free with
265 	 *     g_variant_unref().
266 	 *
267 	 * Since: 2.30
268 	 */
269 	public static Variant gvalueToGvariant(Value gvalue, VariantType type)
270 	{
271 		auto p = g_dbus_gvalue_to_gvariant((gvalue is null) ? null : gvalue.getValueStruct(), (type is null) ? null : type.getVariantTypeStruct());
272 
273 		if(p is null)
274 		{
275 			return null;
276 		}
277 
278 		return new Variant(cast(GVariant*) p, true);
279 	}
280 
281 	/**
282 	 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
283 	 *
284 	 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
285 	 * used - this function is essentially its reverse form. So, a #GVariant
286 	 * containing any basic or string array type will be converted to a #GValue
287 	 * containing a basic value or string array. Any other #GVariant (handle,
288 	 * variant, tuple, dict entry) will be converted to a #GValue containing that
289 	 * #GVariant.
290 	 *
291 	 * The conversion never fails - a valid #GValue is always returned in
292 	 * @out_gvalue.
293 	 *
294 	 * Params:
295 	 *     value = A #GVariant.
296 	 *     outGvalue = Return location pointing to a zero-filled (uninitialized) #GValue.
297 	 *
298 	 * Since: 2.30
299 	 */
300 	public static void gvariantToGvalue(Variant value, out Value outGvalue)
301 	{
302 		GValue* outoutGvalue = sliceNew!GValue();
303 
304 		g_dbus_gvariant_to_gvalue((value is null) ? null : value.getVariantStruct(), outoutGvalue);
305 
306 		outGvalue = ObjectG.getDObject!(Value)(outoutGvalue, true);
307 	}
308 
309 	/**
310 	 * Checks if @string is a
311 	 * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
312 	 *
313 	 * This doesn't check if @string is actually supported by #GDBusServer
314 	 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
315 	 * checks.
316 	 *
317 	 * Params:
318 	 *     str = A string.
319 	 *
320 	 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
321 	 *
322 	 * Since: 2.26
323 	 */
324 	public static bool isAddress(string str)
325 	{
326 		return g_dbus_is_address(Str.toStringz(str)) != 0;
327 	}
328 
329 	/**
330 	 * Checks if @string is a D-Bus GUID.
331 	 *
332 	 * See the D-Bus specification regarding what strings are valid D-Bus
333 	 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
334 	 *
335 	 * Params:
336 	 *     str = The string to check.
337 	 *
338 	 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
339 	 *
340 	 * Since: 2.26
341 	 */
342 	public static bool isGuid(string str)
343 	{
344 		return g_dbus_is_guid(Str.toStringz(str)) != 0;
345 	}
346 
347 	/**
348 	 * Checks if @string is a valid D-Bus interface name.
349 	 *
350 	 * Params:
351 	 *     str = The string to check.
352 	 *
353 	 * Returns: %TRUE if valid, %FALSE otherwise.
354 	 *
355 	 * Since: 2.26
356 	 */
357 	public static bool isInterfaceName(string str)
358 	{
359 		return g_dbus_is_interface_name(Str.toStringz(str)) != 0;
360 	}
361 
362 	/**
363 	 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
364 	 *
365 	 * Params:
366 	 *     str = The string to check.
367 	 *
368 	 * Returns: %TRUE if valid, %FALSE otherwise.
369 	 *
370 	 * Since: 2.26
371 	 */
372 	public static bool isMemberName(string str)
373 	{
374 		return g_dbus_is_member_name(Str.toStringz(str)) != 0;
375 	}
376 
377 	/**
378 	 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
379 	 *
380 	 * Params:
381 	 *     str = The string to check.
382 	 *
383 	 * Returns: %TRUE if valid, %FALSE otherwise.
384 	 *
385 	 * Since: 2.26
386 	 */
387 	public static bool isName(string str)
388 	{
389 		return g_dbus_is_name(Str.toStringz(str)) != 0;
390 	}
391 
392 	/**
393 	 * Like g_dbus_is_address() but also checks if the library supports the
394 	 * transports in @string and that key/value pairs for each transport
395 	 * are valid. See the specification of the
396 	 * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
397 	 *
398 	 * Params:
399 	 *     str = A string.
400 	 *
401 	 * Returns: %TRUE if @string is a valid D-Bus address that is
402 	 *     supported by this library, %FALSE if @error is set.
403 	 *
404 	 * Since: 2.26
405 	 *
406 	 * Throws: GException on failure.
407 	 */
408 	public static bool isSupportedAddress(string str)
409 	{
410 		GError* err = null;
411 
412 		auto p = g_dbus_is_supported_address(Str.toStringz(str), &err) != 0;
413 
414 		if (err !is null)
415 		{
416 			throw new GException( new ErrorG(err) );
417 		}
418 
419 		return p;
420 	}
421 
422 	/**
423 	 * Checks if @string is a valid D-Bus unique bus name.
424 	 *
425 	 * Params:
426 	 *     str = The string to check.
427 	 *
428 	 * Returns: %TRUE if valid, %FALSE otherwise.
429 	 *
430 	 * Since: 2.26
431 	 */
432 	public static bool isUniqueName(string str)
433 	{
434 		return g_dbus_is_unique_name(Str.toStringz(str)) != 0;
435 	}
436 }