1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright (C) 2009 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 *
20 * Author: Alexander Larsson <alexl@redhat.com>
21 */
22
23 #include "config.h"
24 #include "ginitable.h"
25 #include "glibintl.h"
26
27
28 /**
29 * GInitable:
30 *
31 * `GInitable` is implemented by objects that can fail during
32 * initialization. If an object implements this interface then
33 * it must be initialized as the first thing after construction,
34 * either via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async]
35 * (the latter is only available if it also implements [iface@Gio.AsyncInitable]).
36 *
37 * If the object is not initialized, or initialization returns with an
38 * error, then all operations on the object except `g_object_ref()` and
39 * `g_object_unref()` are considered to be invalid, and have undefined
40 * behaviour. They will often fail with [func@GLib.critical] or
41 * [func@GLib.warning], but this must not be relied on.
42 *
43 * Users of objects implementing this are not intended to use
44 * the interface method directly, instead it will be used automatically
45 * in various ways. For C applications you generally just call
46 * [func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper.
47 * This will call [method@Gio.Initable.init] under the cover, returning `NULL`
48 * and setting a `GError` on failure (at which point the instance is
49 * unreferenced).
50 *
51 * For bindings in languages where the native constructor supports
52 * exceptions the binding could check for objects implementing `GInitable`
53 * during normal construction and automatically initialize them, throwing
54 * an exception on failure.
55 *
56 * Since: 2.22
57 */
58
59 typedef GInitableIface GInitableInterface;
60 G_DEFINE_INTERFACE (GInitable, g_initable, G_TYPE_OBJECT)
61
62 static void
63 g_initable_default_init (GInitableInterface *iface)
64 {
65 }
66
67 /**
68 * g_initable_init:
69 * @initable: a #GInitable.
70 * @cancellable: optional #GCancellable object, %NULL to ignore.
71 * @error: a #GError location to store the error occurring, or %NULL to
72 * ignore.
73 *
74 * Initializes the object implementing the interface.
75 *
76 * This method is intended for language bindings. If writing in C,
77 * g_initable_new() should typically be used instead.
78 *
79 * The object must be initialized before any real use after initial
80 * construction, either with this function or g_async_initable_init_async().
81 *
82 * Implementations may also support cancellation. If @cancellable is not %NULL,
83 * then initialization can be cancelled by triggering the cancellable object
84 * from another thread. If the operation was cancelled, the error
85 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
86 * the object doesn't support cancellable initialization the error
87 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
88 *
89 * If the object is not initialized, or initialization returns with an
90 * error, then all operations on the object except g_object_ref() and
91 * g_object_unref() are considered to be invalid, and have undefined
92 * behaviour. See the [introduction][ginitable] for more details.
93 *
94 * Callers should not assume that a class which implements #GInitable can be
95 * initialized multiple times, unless the class explicitly documents itself as
96 * supporting this. Generally, a class’ implementation of init() can assume
97 * (and assert) that it will only be called once. Previously, this documentation
98 * recommended all #GInitable implementations should be idempotent; that
99 * recommendation was relaxed in GLib 2.54.
100 *
101 * If a class explicitly supports being initialized multiple times, it is
102 * recommended that the method is idempotent: multiple calls with the same
103 * arguments should return the same results. Only the first call initializes
104 * the object; further calls return the result of the first call.
105 *
106 * One reason why a class might need to support idempotent initialization is if
107 * it is designed to be used via the singleton pattern, with a
108 * #GObjectClass.constructor that sometimes returns an existing instance.
109 * In this pattern, a caller would expect to be able to call g_initable_init()
110 * on the result of g_object_new(), regardless of whether it is in fact a new
111 * instance.
112 *
113 * Returns: %TRUE if successful. If an error has occurred, this function will
114 * return %FALSE and set @error appropriately if present.
115 *
116 * Since: 2.22
117 */
118 gboolean
119 g_initable_init (GInitable *initable,
120 GCancellable *cancellable,
121 GError **error)
122 {
123 GInitableIface *iface;
124
125 g_return_val_if_fail (G_IS_INITABLE (initable), FALSE);
126
127 iface = G_INITABLE_GET_IFACE (initable);
128
129 return (* iface->init) (initable, cancellable, error);
130 }
131
132 /**
133 * g_initable_new:
134 * @object_type: a #GType supporting #GInitable.
135 * @cancellable: optional #GCancellable object, %NULL to ignore.
136 * @error: a #GError location to store the error occurring, or %NULL to
137 * ignore.
138 * @first_property_name: (nullable): the name of the first property, or %NULL if no
139 * properties
140 * @...: the value if the first property, followed by and other property
141 * value pairs, and ended by %NULL.
142 *
143 * Helper function for constructing #GInitable object. This is
144 * similar to g_object_new() but also initializes the object
145 * and returns %NULL, setting an error on failure.
146 *
147 * Returns: (type GObject.Object) (transfer full): a newly allocated
148 * #GObject, or %NULL on error
149 *
150 * Since: 2.22
151 */
152 gpointer
153 g_initable_new (GType object_type,
154 GCancellable *cancellable,
155 GError **error,
156 const gchar *first_property_name,
157 ...)
158 {
159 GObject *object;
160 va_list var_args;
161
162 va_start (var_args, first_property_name);
163 object = g_initable_new_valist (object_type,
164 first_property_name, var_args,
165 cancellable, error);
166 va_end (var_args);
167
168 return object;
169 }
170
171 /**
172 * g_initable_newv:
173 * @object_type: a #GType supporting #GInitable.
174 * @n_parameters: the number of parameters in @parameters
175 * @parameters: (array length=n_parameters): the parameters to use to construct the object
176 * @cancellable: optional #GCancellable object, %NULL to ignore.
177 * @error: a #GError location to store the error occurring, or %NULL to
178 * ignore.
179 *
180 * Helper function for constructing #GInitable object. This is
181 * similar to g_object_newv() but also initializes the object
182 * and returns %NULL, setting an error on failure.
183 *
184 * Returns: (type GObject.Object) (transfer full): a newly allocated
185 * #GObject, or %NULL on error
186 *
187 * Since: 2.22
188 * Deprecated: 2.54: Use g_object_new_with_properties() and
189 * g_initable_init() instead. See #GParameter for more information.
190 */
191 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
192 gpointer
193 g_initable_newv (GType object_type,
194 guint n_parameters,
195 GParameter *parameters,
196 GCancellable *cancellable,
197 GError **error)
198 {
199 GObject *obj;
200
201 g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);
202
203 obj = g_object_newv (object_type, n_parameters, parameters);
204
205 if (!g_initable_init (G_INITABLE (obj), cancellable, error))
206 {
207 g_object_unref (obj);
208 return NULL;
209 }
210
211 return (gpointer)obj;
212 }
213 G_GNUC_END_IGNORE_DEPRECATIONS
214
215 /**
216 * g_initable_new_valist:
217 * @object_type: a #GType supporting #GInitable.
218 * @first_property_name: the name of the first property, followed by
219 * the value, and other property value pairs, and ended by %NULL.
220 * @var_args: The var args list generated from @first_property_name.
221 * @cancellable: optional #GCancellable object, %NULL to ignore.
222 * @error: a #GError location to store the error occurring, or %NULL to
223 * ignore.
224 *
225 * Helper function for constructing #GInitable object. This is
226 * similar to g_object_new_valist() but also initializes the object
227 * and returns %NULL, setting an error on failure.
228 *
229 * Returns: (type GObject.Object) (transfer full): a newly allocated
230 * #GObject, or %NULL on error
231 *
232 * Since: 2.22
233 */
234 GObject*
235 g_initable_new_valist (GType object_type,
236 const gchar *first_property_name,
237 va_list var_args,
238 GCancellable *cancellable,
239 GError **error)
240 {
241 GObject *obj;
242
243 g_return_val_if_fail (G_TYPE_IS_INITABLE (object_type), NULL);
244
245 obj = g_object_new_valist (object_type,
246 first_property_name,
247 var_args);
248
249 if (!g_initable_init (G_INITABLE (obj), cancellable, error))
250 {
251 g_object_unref (obj);
252 return NULL;
253 }
254
255 return obj;
256 }