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