|
|
|
GIO Reference Manual | |
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Prerequisites | Known Derived Interfaces | Known Implementations | ||||
#include <gio/gio.h>
GInitable;
struct GInitableIface;
gboolean g_initable_init (GInitable *initable,
GCancellable *cancellable,
GError **error);
gpointer g_initable_new (GType object_type,
GCancellable *cancellable,
GError **error,
const gchar *first_property_name,
...);
GObject * g_initable_new_valist (GType object_type,
const gchar *first_property_name,
va_list var_args,
GCancellable *cancellable,
GError **error);
gpointer g_initable_newv (GType object_type,
guint n_parameters,
GParameter *parameters,
GCancellable *cancellable,
GError **error);
GInitable is implemented by GCharsetConverter, GDBusConnection, GDBusObjectManagerClient, GDBusProxy, GDBusServer and GSocket.
GInitable is implemented by objects that can fail during
initialization. If an object implements this interface then
it must be initialized as the first thing after construction,
either via g_initable_init() or g_async_initable_init_async()
(the latter is only available if it also implements GAsyncInitable).
If the object is not initialized, or initialization returns with an
error, then all operations on the object except g_object_ref() and
g_object_unref() are considered to be invalid, and have undefined
behaviour. They will often fail with g_critical() or g_warning(), but
this must not be relied on.
Users of objects implementing this are not intended to use
the interface method directly, instead it will be used automatically
in various ways. For C applications you generally just call
g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
This will call g_initable_init() under the cover, returning NULL and
setting a GError on failure (at which point the instance is
unreferenced).
For bindings in languages where the native constructor supports
exceptions the binding could check for objects implemention GInitable
during normal construction and automatically initialize them, throwing
an exception on failure.
struct GInitableIface {
GTypeInterface g_iface;
/* Virtual Table */
gboolean (* init) (GInitable *initable,
GCancellable *cancellable,
GError **error);
};
Provides an interface for initializing object such that initialization may fail.
GTypeInterface |
The parent interface. |
| Initializes the object. |
Since 2.22
gboolean g_initable_init (GInitable *initable,GCancellable *cancellable,GError **error);
Initializes the object implementing the interface.
The object must be initialized before any real use after initial
construction, either with this function or g_async_initable_init_async().
Implementations may also support cancellation. If cancellable is not NULL,
then initialization can be cancelled by triggering the cancellable object
from another thread. If the operation was cancelled, the error
G_IO_ERROR_CANCELLED will be returned. If cancellable is not NULL and
the object doesn't support cancellable initialization the error
G_IO_ERROR_NOT_SUPPORTED will be returned.
If the object is not initialized, or initialization returns with an
error, then all operations on the object except g_object_ref() and
g_object_unref() are considered to be invalid, and have undefined
behaviour. See the ??? section introduction
for more details.
Implementations of this method must be idempotent, i.e. multiple calls to this function with the same argument should return the same results. Only the first call initializes the object, further calls return the result of the first call. This is so that it's safe to implement the singleton pattern in the GObject constructor function.
|
a GInitable. |
|
optional GCancellable object, NULL to ignore. |
|
a GError location to store the error occurring, or NULL to
ignore. |
Returns : |
TRUE if successful. If an error has occurred, this function will
return FALSE and set error appropriately if present. |
Since 2.22
gpointer g_initable_new (GType object_type,GCancellable *cancellable,GError **error,const gchar *first_property_name,...);
Helper function for constructing GInitable object. This is
similar to g_object_new() but also initializes the object
and returns NULL, setting an error on failure.
|
a GType supporting GInitable. |
|
optional GCancellable object, NULL to ignore. |
|
a GError location to store the error occurring, or NULL to
ignore. |
|
the name of the first property, or NULL if no
properties. [allow-none]
|
|
the value if the first property, followed by and other property
value pairs, and ended by NULL. |
Returns : |
a newly allocated GObject, or NULL on error. [transfer full]
|
Since 2.22
GObject * g_initable_new_valist (GType object_type,const gchar *first_property_name,va_list var_args,GCancellable *cancellable,GError **error);
Helper function for constructing GInitable object. This is
similar to g_object_new_valist() but also initializes the object
and returns NULL, setting an error on failure.
|
a GType supporting GInitable. |
|
the name of the first property, followed by
the value, and other property value pairs, and ended by NULL. |
|
The var args list generated from first_property_name. |
|
optional GCancellable object, NULL to ignore. |
|
a GError location to store the error occurring, or NULL to
ignore. |
Returns : |
a newly allocated GObject, or NULL on error. [transfer full]
|
Since 2.22
gpointer g_initable_newv (GType object_type,guint n_parameters,GParameter *parameters,GCancellable *cancellable,GError **error);
Helper function for constructing GInitable object. This is
similar to g_object_newv() but also initializes the object
and returns NULL, setting an error on failure.
|
a GType supporting GInitable. |
|
the number of parameters in parameters
|
|
the parameters to use to construct the object. [array length=n_parameters] |
|
optional GCancellable object, NULL to ignore. |
|
a GError location to store the error occurring, or NULL to
ignore. |
Returns : |
a newly allocated GObject, or NULL on error. [transfer full]
|
Since 2.22