GInitable

## GInitable GInitable — Failable object initialization interface |

## Synopsis

    #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);

## Object Hierarchy

      GInterface
       +----GInitable

## Prerequisites

GInitable requires GObject.

## Known Implementations

GInitable is implemented by GCharsetConverter, GDBusConnection, GDBusObjectManagerClient, GDBusProxy, GDBusServer and GSocket.

## Description

GInitable is implemented by objects that can fail during initialization. If an object implements this interface the `g_initable_init()` function must be called as the first thing after construction. If `g_initable_init()` is not called, or if it returns an error, all further operations on the object should fail, generally with a `G_IO_ERROR_NOT_INITIALIZED` error.

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.

## Details

### GInitable

    typedef struct _GInitable GInitable;

Interface for initializable objects.

Since 2.22

### struct GInitableIface

    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 `g_iface`; | The parent interface.
`init` () | Initializes the object.

Since 2.22

### g_initable_init ()

    gboolean            g_initable_init                     (GInitable *initable,
                                                             GCancellable *cancellable,
                                                             GError **error);

Initializes the object implementing the interface. This must be done before any real use of the object after initial construction.

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 this function is not called, or returns with an error then all operations on the object should fail, generally returning the error `G_IO_ERROR_NOT_INITIALIZED`.

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 its safe to implement the singleton pattern in the GObject constructor function.

`initable` : | a GInitable.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`error` : | 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

### g_initable_new ()

    gpointer            g_initable_new                      (GType object_type,
                                                             GCancellable *cancellable,
                                                             GError **error,
                                                             const gchar *first_property_name,
                                                             ...);

Helper function for constructing GInitiable object. This is similar to `g_object_new()` but also initializes the object and returns `NULL`, setting an error on failure.

`object_type` : | a GType supporting GInitable.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`error` : | a GError location to store the error occurring, or `NULL` to ignore.
`first_property_name` : | the name of the first property, or `NULL` if no properties
`...` : | 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

### g_initable_new_valist ()

    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 GInitiable object. This is similar to `g_object_new_valist()` but also initializes the object and returns `NULL`, setting an error on failure.

`object_type` : | a GType supporting GInitable.
`first_property_name` : | the name of the first property, followed by the value, and other property value pairs, and ended by `NULL`.
`var_args` : | The var args list generated from `first_property_name`.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`error` : | 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

### g_initable_newv ()

    gpointer            g_initable_newv                     (GType object_type,
                                                             guint n_parameters,
                                                             GParameter *parameters,
                                                             GCancellable *cancellable,
                                                             GError **error);

Helper function for constructing GInitiable object. This is similar to `g_object_newv()` but also initializes the object and returns `NULL`, setting an error on failure.

`object_type` : | a GType supporting GInitable.
`n_parameters` : | the number of parameters in `parameters`
`parameters` : | the parameters to use to construct the object
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`error` : | 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

## See Also

GAsyncInitable