glibmm: Gio::Initable Class Reference

# Gio::Initable Class Reference

Failable object initialization interface. More...

`#include <giomm/initable.h>`

Inheritance diagram for Gio::Initable:
[legend]

List of all members.

## Public Member Functions

virtual | ~Initable ()
GInitable* | gobj ()
| Provides access to the underlying C GObject.
const GInitable* | gobj () const
| Provides access to the underlying C GObject.

## Static Public Member Functions

static void | add_interface (GType gtype_implementer)

## Protected Member Functions

void | init (const Glib::RefPtr< Cancellable >& cancellable)
| Initializes the object implementing the interface.
virtual bool | init_vfunc (const Glib::RefPtr< Cancellable >& cancellable, GError** error)

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gio::Initable > | wrap (GInitable* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Failable object initialization interface.

Initable is implemented by objects that can fail during initialization. If an object implements this interface the init() function must be called as the first thing after construction. If 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.

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.

Since glibmm 2.24:

## Constructor & Destructor Documentation

virtual Gio::Initable::~Initable | ( |  | ) | `[virtual]`

## Member Function Documentation

static void Gio::Initable::add_interface | ( | GType | gtype_implementer | ) | `[static]`

const GInitable* Gio::Initable::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::Interface.

Reimplemented in Gio::Socket.

GInitable* Gio::Initable::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Glib::Interface.

Reimplemented in Gio::Socket.

void Gio::Initable::init | ( | const Glib::RefPtr< Cancellable >& | cancellable | ) | `[protected]`

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 `0`, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IO_ERROR_CANCELLED will be returned. If cancellable is not `0` and the object doesn't support cancellable initialization the error 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 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.

Since glibmm 2.22:

Parameters:

  | cancellable | Optional Cancellable object, `0` to ignore.

Returns:
  `true` if successful. If an error has occurred, this function will return `false` and set error appropriately if present.

virtual bool Gio::Initable::init_vfunc | ( | const Glib::RefPtr< Cancellable >& | cancellable,
|  | GError ** | error |
| ) |  |  | `[protected, virtual]`

## Friends And Related Function Documentation

Glib::RefPtr< Gio::Initable > wrap | ( | GInitable * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.