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.DBusError;
26 
27 private import gio.c.functions;
28 public  import gio.c.types;
29 private import glib.ErrorG;
30 private import glib.Str;
31 public  import gtkc.giotypes;
32 
33 
34 /** */
35 public struct DBusError
36 {
37 
38 	/**
39 	 * Creates a D-Bus error name to use for @error. If @error matches
40 	 * a registered error (cf. g_dbus_error_register_error()), the corresponding
41 	 * D-Bus error name will be returned.
42 	 *
43 	 * Otherwise the a name of the form
44 	 * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
45 	 * will be used. This allows other GDBus applications to map the error
46 	 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
47 	 *
48 	 * This function is typically only used in object mappings to put a
49 	 * #GError on the wire. Regular applications should not use it.
50 	 *
51 	 * Params:
52 	 *     error = A #GError.
53 	 *
54 	 * Returns: A D-Bus error name (never %NULL). Free with g_free().
55 	 *
56 	 * Since: 2.26
57 	 */
58 	public static string encodeGerror(ErrorG error)
59 	{
60 		auto retStr = g_dbus_error_encode_gerror((error is null) ? null : error.getErrorGStruct());
61 
62 		scope(exit) Str.freeString(retStr);
63 		return Str.toString(retStr);
64 	}
65 
66 	/**
67 	 * Gets the D-Bus error name used for @error, if any.
68 	 *
69 	 * This function is guaranteed to return a D-Bus error name for all
70 	 * #GErrors returned from functions handling remote method calls
71 	 * (e.g. g_dbus_connection_call_finish()) unless
72 	 * g_dbus_error_strip_remote_error() has been used on @error.
73 	 *
74 	 * Params:
75 	 *     error = a #GError
76 	 *
77 	 * Returns: an allocated string or %NULL if the D-Bus error name
78 	 *     could not be found. Free with g_free().
79 	 *
80 	 * Since: 2.26
81 	 */
82 	public static string getRemoteError(ErrorG error)
83 	{
84 		auto retStr = g_dbus_error_get_remote_error((error is null) ? null : error.getErrorGStruct());
85 
86 		scope(exit) Str.freeString(retStr);
87 		return Str.toString(retStr);
88 	}
89 
90 	/**
91 	 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
92 	 * use g_dbus_error_get_remote_error() to get the name of the error.
93 	 *
94 	 * Params:
95 	 *     error = A #GError.
96 	 *
97 	 * Returns: %TRUE if @error represents an error from a remote peer,
98 	 *     %FALSE otherwise.
99 	 *
100 	 * Since: 2.26
101 	 */
102 	public static bool isRemoteError(ErrorG error)
103 	{
104 		return g_dbus_error_is_remote_error((error is null) ? null : error.getErrorGStruct()) != 0;
105 	}
106 
107 	/**
108 	 * Creates a #GError based on the contents of @dbus_error_name and
109 	 * @dbus_error_message.
110 	 *
111 	 * Errors registered with g_dbus_error_register_error() will be looked
112 	 * up using @dbus_error_name and if a match is found, the error domain
113 	 * and code is used. Applications can use g_dbus_error_get_remote_error()
114 	 * to recover @dbus_error_name.
115 	 *
116 	 * If a match against a registered error is not found and the D-Bus
117 	 * error name is in a form as returned by g_dbus_error_encode_gerror()
118 	 * the error domain and code encoded in the name is used to
119 	 * create the #GError. Also, @dbus_error_name is added to the error message
120 	 * such that it can be recovered with g_dbus_error_get_remote_error().
121 	 *
122 	 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
123 	 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
124 	 * added to the error message such that it can be recovered with
125 	 * g_dbus_error_get_remote_error().
126 	 *
127 	 * In all three cases, @dbus_error_name can always be recovered from the
128 	 * returned #GError using the g_dbus_error_get_remote_error() function
129 	 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
130 	 *
131 	 * This function is typically only used in object mappings to prepare
132 	 * #GError instances for applications. Regular applications should not use
133 	 * it.
134 	 *
135 	 * Params:
136 	 *     dbusErrorName = D-Bus error name.
137 	 *     dbusErrorMessage = D-Bus error message.
138 	 *
139 	 * Returns: An allocated #GError. Free with g_error_free().
140 	 *
141 	 * Since: 2.26
142 	 */
143 	public static ErrorG newForDbusError(string dbusErrorName, string dbusErrorMessage)
144 	{
145 		auto p = g_dbus_error_new_for_dbus_error(Str.toStringz(dbusErrorName), Str.toStringz(dbusErrorMessage));
146 
147 		if(p is null)
148 		{
149 			return null;
150 		}
151 
152 		return new ErrorG(cast(GError*) p, true);
153 	}
154 
155 	/** */
156 	public static GQuark quark()
157 	{
158 		return g_dbus_error_quark();
159 	}
160 
161 	/**
162 	 * Creates an association to map between @dbus_error_name and
163 	 * #GErrors specified by @error_domain and @error_code.
164 	 *
165 	 * This is typically done in the routine that returns the #GQuark for
166 	 * an error domain.
167 	 *
168 	 * Params:
169 	 *     errorDomain = A #GQuark for a error domain.
170 	 *     errorCode = An error code.
171 	 *     dbusErrorName = A D-Bus error name.
172 	 *
173 	 * Returns: %TRUE if the association was created, %FALSE if it already
174 	 *     exists.
175 	 *
176 	 * Since: 2.26
177 	 */
178 	public static bool registerError(GQuark errorDomain, int errorCode, string dbusErrorName)
179 	{
180 		return g_dbus_error_register_error(errorDomain, errorCode, Str.toStringz(dbusErrorName)) != 0;
181 	}
182 
183 	/**
184 	 * Helper function for associating a #GError error domain with D-Bus error names.
185 	 *
186 	 * Params:
187 	 *     errorDomainQuarkName = The error domain name.
188 	 *     quarkVolatile = A pointer where to store the #GQuark.
189 	 *     entries = A pointer to @num_entries #GDBusErrorEntry struct items.
190 	 *
191 	 * Since: 2.26
192 	 */
193 	public static void registerErrorDomain(string errorDomainQuarkName, size_t* quarkVolatile, GDBusErrorEntry[] entries)
194 	{
195 		g_dbus_error_register_error_domain(Str.toStringz(errorDomainQuarkName), quarkVolatile, entries.ptr, cast(uint)entries.length);
196 	}
197 
198 	/**
199 	 * Looks for extra information in the error message used to recover
200 	 * the D-Bus error name and strips it if found. If stripped, the
201 	 * message field in @error will correspond exactly to what was
202 	 * received on the wire.
203 	 *
204 	 * This is typically used when presenting errors to the end user.
205 	 *
206 	 * Params:
207 	 *     error = A #GError.
208 	 *
209 	 * Returns: %TRUE if information was stripped, %FALSE otherwise.
210 	 *
211 	 * Since: 2.26
212 	 */
213 	public static bool stripRemoteError(ErrorG error)
214 	{
215 		return g_dbus_error_strip_remote_error((error is null) ? null : error.getErrorGStruct()) != 0;
216 	}
217 
218 	/**
219 	 * Destroys an association previously set up with g_dbus_error_register_error().
220 	 *
221 	 * Params:
222 	 *     errorDomain = A #GQuark for a error domain.
223 	 *     errorCode = An error code.
224 	 *     dbusErrorName = A D-Bus error name.
225 	 *
226 	 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
227 	 *
228 	 * Since: 2.26
229 	 */
230 	public static bool unregisterError(GQuark errorDomain, int errorCode, string dbusErrorName)
231 	{
232 		return g_dbus_error_unregister_error(errorDomain, errorCode, Str.toStringz(dbusErrorName)) != 0;
233 	}
234 }