|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>GInitable: GIO Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GIO Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="failable_initialization.html" title="Failable Initialization">
|
|
Packit |
ae235b |
<link rel="prev" href="failable_initialization.html" title="Failable Initialization">
|
|
Packit |
ae235b |
<link rel="next" href="GAsyncInitable.html" title="GAsyncInitable">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Top |
|
|
Packit |
ae235b |
Description |
|
|
Packit |
ae235b |
Object Hierarchy |
|
|
Packit |
ae235b |
Prerequisites |
|
|
Packit |
ae235b |
Known Derived Interfaces |
|
|
Packit |
ae235b |
Known Implementations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GInitable
|
|
Packit |
ae235b |
GInitable — Failable object initialization interface
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Functions
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gboolean
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_init ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gpointer
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_new ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GObject *
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_new_valist ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gpointer
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_newv ()
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Types and Values
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GInitable
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct
|
|
Packit |
ae235b |
GInitableIface
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Object Hierarchy
|
|
Packit |
ae235b |
GInterface
|
|
Packit |
ae235b |
╰── GInitable
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Prerequisites
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GInitable requires
|
|
Packit |
ae235b |
GObject.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Known Derived Interfaces
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GInitable is required by
|
|
Packit |
ae235b |
GNetworkMonitor.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Known Implementations
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GInitable is implemented by
|
|
Packit |
ae235b |
GCharsetConverter, GDBusConnection, GDBusObjectManagerClient, GDBusProxy, GDBusServer, GInetAddressMask, GSocket and GSubprocess.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Includes
|
|
Packit |
ae235b |
#include <gio/gio.h>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Description
|
|
Packit |
ae235b |
GInitable is implemented by objects that can fail during
|
|
Packit |
ae235b |
initialization. If an object implements this interface then
|
|
Packit |
ae235b |
it must be initialized as the first thing after construction,
|
|
Packit |
ae235b |
either via g_initable_init() or g_async_initable_init_async()
|
|
Packit |
ae235b |
(the latter is only available if it also implements GAsyncInitable).
|
|
Packit |
ae235b |
If the object is not initialized, or initialization returns with an
|
|
Packit |
ae235b |
error, then all operations on the object except g_object_ref() and
|
|
Packit |
ae235b |
g_object_unref() are considered to be invalid, and have undefined
|
|
Packit |
ae235b |
behaviour. They will often fail with g_critical() or g_warning(), but
|
|
Packit |
ae235b |
this must not be relied on.
|
|
Packit |
ae235b |
Users of objects implementing this are not intended to use
|
|
Packit |
ae235b |
the interface method directly, instead it will be used automatically
|
|
Packit |
ae235b |
in various ways. For C applications you generally just call
|
|
Packit |
ae235b |
g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
|
|
Packit |
ae235b |
This will call g_initable_init() under the cover, returning NULL and
|
|
Packit |
ae235b |
setting a GError on failure (at which point the instance is
|
|
Packit |
ae235b |
unreferenced).
|
|
Packit |
ae235b |
For bindings in languages where the native constructor supports
|
|
Packit |
ae235b |
exceptions the binding could check for objects implemention GInitable
|
|
Packit |
ae235b |
during normal construction and automatically initialize them, throwing
|
|
Packit |
ae235b |
an exception on failure.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Functions
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_init ()
|
|
Packit |
ae235b |
gboolean
|
|
Packit |
ae235b |
g_initable_init (GInitable *initable,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
Initializes the object implementing the interface.
|
|
Packit |
ae235b |
This method is intended for language bindings. If writing in C,
|
|
Packit |
ae235b |
g_initable_new() should typically be used instead.
|
|
Packit |
ae235b |
The object must be initialized before any real use after initial
|
|
Packit |
ae235b |
construction, either with this function or g_async_initable_init_async().
|
|
Packit |
ae235b |
Implementations may also support cancellation. If cancellable
|
|
Packit |
ae235b |
is not NULL,
|
|
Packit |
ae235b |
then initialization can be cancelled by triggering the cancellable object
|
|
Packit |
ae235b |
from another thread. If the operation was cancelled, the error
|
|
Packit |
ae235b |
G_IO_ERROR_CANCELLED will be returned. If cancellable
|
|
Packit |
ae235b |
is not NULL and
|
|
Packit |
ae235b |
the object doesn't support cancellable initialization the error
|
|
Packit |
ae235b |
G_IO_ERROR_NOT_SUPPORTED will be returned.
|
|
Packit |
ae235b |
If the object is not initialized, or initialization returns with an
|
|
Packit |
ae235b |
error, then all operations on the object except g_object_ref() and
|
|
Packit |
ae235b |
g_object_unref() are considered to be invalid, and have undefined
|
|
Packit |
ae235b |
behaviour. See the introduction for more details.
|
|
Packit |
ae235b |
Callers should not assume that a class which implements GInitable can be
|
|
Packit |
ae235b |
initialized multiple times, unless the class explicitly documents itself as
|
|
Packit |
ae235b |
supporting this. Generally, a class’ implementation of init() can assume
|
|
Packit |
ae235b |
(and assert) that it will only be called once. Previously, this documentation
|
|
Packit |
ae235b |
recommended all GInitable implementations should be idempotent; that
|
|
Packit |
ae235b |
recommendation was relaxed in GLib 2.54.
|
|
Packit |
ae235b |
If a class explicitly supports being initialized multiple times, it is
|
|
Packit |
ae235b |
recommended that the method is idempotent: multiple calls with the same
|
|
Packit |
ae235b |
arguments should return the same results. Only the first call initializes
|
|
Packit |
ae235b |
the object; further calls return the result of the first call.
|
|
Packit |
ae235b |
One reason why a class might need to support idempotent initialization is if
|
|
Packit |
ae235b |
it is designed to be used via the singleton pattern, with a
|
|
Packit |
ae235b |
GObjectClass.constructor that sometimes returns an existing instance.
|
|
Packit |
ae235b |
In this pattern, a caller would expect to be able to call g_initable_init()
|
|
Packit |
ae235b |
on the result of g_object_new(), regardless of whether it is in fact a new
|
|
Packit |
ae235b |
instance.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
initable
|
|
Packit |
ae235b |
a GInitable.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
optional GCancellable object, NULL to ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
a GError location to store the error occurring, or NULL to
|
|
Packit |
ae235b |
ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
TRUE if successful. If an error has occurred, this function will
|
|
Packit |
ae235b |
return FALSE and set error
|
|
Packit |
ae235b |
appropriately if present.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.22
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_new ()
|
|
Packit |
ae235b |
gpointer
|
|
Packit |
ae235b |
g_initable_new (GType object_type,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error,
|
|
Packit |
ae235b |
const gchar *first_property_name,
|
|
Packit |
ae235b |
...);
|
|
Packit |
ae235b |
Helper function for constructing GInitable object. This is
|
|
Packit |
ae235b |
similar to g_object_new() but also initializes the object
|
|
Packit |
ae235b |
and returns NULL, setting an error on failure.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
object_type
|
|
Packit |
ae235b |
a GType supporting GInitable.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
optional GCancellable object, NULL to ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
a GError location to store the error occurring, or NULL to
|
|
Packit |
ae235b |
ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
first_property_name
|
|
Packit |
ae235b |
the name of the first property, or NULL if no
|
|
Packit |
ae235b |
properties.
|
|
Packit |
ae235b |
[nullable]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
...
|
|
Packit |
ae235b |
the value if the first property, followed by and other property
|
|
Packit |
ae235b |
value pairs, and ended by NULL.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
a newly allocated
|
|
Packit |
ae235b |
GObject, or NULL on error.
|
|
Packit |
ae235b |
[type GObject.Object][transfer full]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.22
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_new_valist ()
|
|
Packit |
ae235b |
GObject *
|
|
Packit |
ae235b |
g_initable_new_valist (GType object_type,
|
|
Packit |
ae235b |
const gchar *first_property_name,
|
|
Packit |
ae235b |
va_list var_args,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
Helper function for constructing GInitable object. This is
|
|
Packit |
ae235b |
similar to g_object_new_valist() but also initializes the object
|
|
Packit |
ae235b |
and returns NULL, setting an error on failure.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
object_type
|
|
Packit |
ae235b |
a GType supporting GInitable.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
first_property_name
|
|
Packit |
ae235b |
the name of the first property, followed by
|
|
Packit |
ae235b |
the value, and other property value pairs, and ended by NULL.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
var_args
|
|
Packit |
ae235b |
The var args list generated from first_property_name
|
|
Packit |
ae235b |
.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
optional GCancellable object, NULL to ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
a GError location to store the error occurring, or NULL to
|
|
Packit |
ae235b |
ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
a newly allocated
|
|
Packit |
ae235b |
GObject, or NULL on error.
|
|
Packit |
ae235b |
[type GObject.Object][transfer full]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.22
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_newv ()
|
|
Packit |
ae235b |
gpointer
|
|
Packit |
ae235b |
g_initable_newv (GType object_type,
|
|
Packit |
ae235b |
guint n_parameters,
|
|
Packit |
ae235b |
GParameter *parameters,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
g_initable_newv has been deprecated since version 2.54 and should not be used in newly-written code.
|
|
Packit |
ae235b |
Use g_object_new_with_properties() and
|
|
Packit |
ae235b |
g_initable_init() instead. See GParameter for more information.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Helper function for constructing GInitable object. This is
|
|
Packit |
ae235b |
similar to g_object_newv() but also initializes the object
|
|
Packit |
ae235b |
and returns NULL, setting an error on failure.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
object_type
|
|
Packit |
ae235b |
a GType supporting GInitable.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
n_parameters
|
|
Packit |
ae235b |
the number of parameters in parameters
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
parameters
|
|
Packit |
ae235b |
the parameters to use to construct the object.
|
|
Packit |
ae235b |
[array length=n_parameters]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
cancellable
|
|
Packit |
ae235b |
optional GCancellable object, NULL to ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
error
|
|
Packit |
ae235b |
a GError location to store the error occurring, or NULL to
|
|
Packit |
ae235b |
ignore.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Returns
|
|
Packit |
ae235b |
a newly allocated
|
|
Packit |
ae235b |
GObject, or NULL on error.
|
|
Packit |
ae235b |
[type GObject.Object][transfer full]
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.22
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Types and Values
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GInitable
|
|
Packit |
ae235b |
typedef struct _GInitable GInitable;
|
|
Packit |
ae235b |
Interface for initializable objects.
|
|
Packit |
ae235b |
Since: 2.22
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
struct GInitableIface
|
|
Packit |
ae235b |
struct GInitableIface {
|
|
Packit |
ae235b |
GTypeInterface g_iface;
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
/* Virtual Table */
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
gboolean (* init) (GInitable *initable,
|
|
Packit |
ae235b |
GCancellable *cancellable,
|
|
Packit |
ae235b |
GError **error);
|
|
Packit |
ae235b |
};
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Provides an interface for initializing object such that initialization
|
|
Packit |
ae235b |
may fail.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Members
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
init ()
|
|
Packit |
ae235b |
Initializes the object.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Since: 2.22
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
See Also
|
|
Packit |
ae235b |
GAsyncInitable
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|