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.AsyncInitableIF;
26 
27 private import gio.AsyncResultIF;
28 private import gio.Cancellable;
29 private import glib.ErrorG;
30 private import glib.GException;
31 private import glib.Str;
32 private import gobject.ObjectG;
33 private import gtkc.gio;
34 public  import gtkc.giotypes;
35 
36 
37 /**
38  * This is the asynchronous version of #GInitable; it behaves the same
39  * in all ways except that initialization is asynchronous. For more details
40  * see the descriptions on #GInitable.
41  * 
42  * A class may implement both the #GInitable and #GAsyncInitable interfaces.
43  * 
44  * Users of objects implementing this are not intended to use the interface
45  * method directly; instead it will be used automatically in various ways.
46  * For C applications you generally just call g_async_initable_new_async()
47  * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
48  * g_async_initable_init_async() under the cover, calling back with %NULL and
49  * a set %GError on failure.
50  * 
51  * A typical implementation might look something like this:
52  * 
53  * |[<!-- language="C" -->
54  * enum {
55  * NOT_INITIALIZED,
56  * INITIALIZING,
57  * INITIALIZED
58  * };
59  * 
60  * static void
61  * _foo_ready_cb (Foo *self)
62  * {
63  * GList *l;
64  * 
65  * self->priv->state = INITIALIZED;
66  * 
67  * for (l = self->priv->init_results; l != NULL; l = l->next)
68  * {
69  * GTask *task = l->data;
70  * 
71  * if (self->priv->success)
72  * g_task_return_boolean (task, TRUE);
73  * else
74  * g_task_return_new_error (task, ...);
75  * g_object_unref (task);
76  * }
77  * 
78  * g_list_free (self->priv->init_results);
79  * self->priv->init_results = NULL;
80  * }
81  * 
82  * static void
83  * foo_init_async (GAsyncInitable       *initable,
84  * int                   io_priority,
85  * GCancellable         *cancellable,
86  * GAsyncReadyCallback   callback,
87  * gpointer              user_data)
88  * {
89  * Foo *self = FOO (initable);
90  * GTask *task;
91  * 
92  * task = g_task_new (initable, cancellable, callback, user_data);
93  * 
94  * switch (self->priv->state)
95  * {
96  * case NOT_INITIALIZED:
97  * _foo_get_ready (self);
98  * self->priv->init_results = g_list_append (self->priv->init_results,
99  * task);
100  * self->priv->state = INITIALIZING;
101  * break;
102  * case INITIALIZING:
103  * self->priv->init_results = g_list_append (self->priv->init_results,
104  * task);
105  * break;
106  * case INITIALIZED:
107  * if (!self->priv->success)
108  * g_task_return_new_error (task, ...);
109  * else
110  * g_task_return_boolean (task, TRUE);
111  * g_object_unref (task);
112  * break;
113  * }
114  * }
115  * 
116  * static gboolean
117  * foo_init_finish (GAsyncInitable       *initable,
118  * GAsyncResult         *result,
119  * GError              **error)
120  * {
121  * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);
122  * 
123  * return g_task_propagate_boolean (G_TASK (result), error);
124  * }
125  * 
126  * static void
127  * foo_async_initable_iface_init (gpointer g_iface,
128  * gpointer data)
129  * {
130  * GAsyncInitableIface *iface = g_iface;
131  * 
132  * iface->init_async = foo_init_async;
133  * iface->init_finish = foo_init_finish;
134  * }
135  * ]|
136  *
137  * Since: 2.22
138  */
139 public interface AsyncInitableIF{
140 	/** Get the main Gtk struct */
141 	public GAsyncInitable* getAsyncInitableStruct(bool transferOwnership = false);
142 
143 	/** the main Gtk struct as a void* */
144 	protected void* getStruct();
145 
146 
147 	/**
148 	 * Helper function for constructing #GAsyncInitable object. This is
149 	 * similar to g_object_new_valist() but also initializes the object
150 	 * asynchronously.
151 	 *
152 	 * When the initialization is finished, @callback will be called. You can
153 	 * then call g_async_initable_new_finish() to get the new object and check
154 	 * for any errors.
155 	 *
156 	 * Params:
157 	 *     objectType = a #GType supporting #GAsyncInitable.
158 	 *     firstPropertyName = the name of the first property, followed by
159 	 *         the value, and other property value pairs, and ended by %NULL.
160 	 *     varArgs = The var args list generated from @first_property_name.
161 	 *     ioPriority = the [I/O priority][io-priority] of the operation
162 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
163 	 *     callback = a #GAsyncReadyCallback to call when the initialization is
164 	 *         finished
165 	 *     userData = the data to pass to callback function
166 	 *
167 	 * Since: 2.22
168 	 */
169 	public static void newValistAsync(GType objectType, string firstPropertyName, void* varArgs, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
170 
171 	/**
172 	 * Helper function for constructing #GAsyncInitable object. This is
173 	 * similar to g_object_newv() but also initializes the object asynchronously.
174 	 *
175 	 * When the initialization is finished, @callback will be called. You can
176 	 * then call g_async_initable_new_finish() to get the new object and check
177 	 * for any errors.
178 	 *
179 	 * Params:
180 	 *     objectType = a #GType supporting #GAsyncInitable.
181 	 *     nParameters = the number of parameters in @parameters
182 	 *     parameters = the parameters to use to construct the object
183 	 *     ioPriority = the [I/O priority][io-priority] of the operation
184 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
185 	 *     callback = a #GAsyncReadyCallback to call when the initialization is
186 	 *         finished
187 	 *     userData = the data to pass to callback function
188 	 *
189 	 * Since: 2.22
190 	 */
191 	public static void newvAsync(GType objectType, uint nParameters, GParameter* parameters, int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
192 
193 	/**
194 	 * Starts asynchronous initialization of the object implementing the
195 	 * interface. This must be done before any real use of the object after
196 	 * initial construction. If the object also implements #GInitable you can
197 	 * optionally call g_initable_init() instead.
198 	 *
199 	 * When the initialization is finished, @callback will be called. You can
200 	 * then call g_async_initable_init_finish() to get the result of the
201 	 * initialization.
202 	 *
203 	 * Implementations may also support cancellation. If @cancellable is not
204 	 * %NULL, then initialization can be cancelled by triggering the cancellable
205 	 * object from another thread. If the operation was cancelled, the error
206 	 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
207 	 * the object doesn't support cancellable initialization, the error
208 	 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
209 	 *
210 	 * As with #GInitable, if the object is not initialized, or initialization
211 	 * returns with an error, then all operations on the object except
212 	 * g_object_ref() and g_object_unref() are considered to be invalid, and
213 	 * have undefined behaviour. They will often fail with g_critical() or
214 	 * g_warning(), but this must not be relied on.
215 	 *
216 	 * Implementations of this method must be idempotent: i.e. multiple calls
217 	 * to this function with the same argument should return the same results.
218 	 * Only the first call initializes the object; further calls return the result
219 	 * of the first call. This is so that it's safe to implement the singleton
220 	 * pattern in the GObject constructor function.
221 	 *
222 	 * For classes that also support the #GInitable interface, the default
223 	 * implementation of this method will run the g_initable_init() function
224 	 * in a thread, so if you want to support asynchronous initialization via
225 	 * threads, just implement the #GAsyncInitable interface without overriding
226 	 * any interface methods.
227 	 *
228 	 * Params:
229 	 *     ioPriority = the [I/O priority][io-priority] of the operation
230 	 *     cancellable = optional #GCancellable object, %NULL to ignore.
231 	 *     callback = a #GAsyncReadyCallback to call when the request is satisfied
232 	 *     userData = the data to pass to callback function
233 	 *
234 	 * Since: 2.22
235 	 */
236 	public void initAsync(int ioPriority, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
237 
238 	/**
239 	 * Finishes asynchronous initialization and returns the result.
240 	 * See g_async_initable_init_async().
241 	 *
242 	 * Params:
243 	 *     res = a #GAsyncResult.
244 	 *
245 	 * Returns: %TRUE if successful. If an error has occurred, this function
246 	 *     will return %FALSE and set @error appropriately if present.
247 	 *
248 	 * Since: 2.22
249 	 *
250 	 * Throws: GException on failure.
251 	 */
252 	public bool initFinish(AsyncResultIF res);
253 
254 	/**
255 	 * Finishes the async construction for the various g_async_initable_new
256 	 * calls, returning the created object or %NULL on error.
257 	 *
258 	 * Params:
259 	 *     res = the #GAsyncResult from the callback
260 	 *
261 	 * Returns: a newly created #GObject,
262 	 *     or %NULL on error. Free with g_object_unref().
263 	 *
264 	 * Since: 2.22
265 	 *
266 	 * Throws: GException on failure.
267 	 */
268 	public ObjectG newFinish(AsyncResultIF res);
269 }