Functions
g_bus_get ()
void
g_bus_get (GBusType bus_type,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously connects to the message bus specified by bus_type
.
When the operation is finished, callback
will be invoked. You can
then call g_bus_get_finish() to get the result of the operation.
This is an asynchronous failable function. See g_bus_get_sync() for
the synchronous version.
Since: 2.26
g_dbus_connection_new ()
void
g_dbus_connection_new (GIOStream *stream,
const gchar *guid,
GDBusConnectionFlags flags,
GDBusAuthObserver *observer,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
with the end represented by stream
.
If stream
is a GSocketConnection, then the corresponding GSocket
will be put into non-blocking mode.
The D-Bus connection will interact with stream
from a worker thread.
As a result, the caller should not interact with stream
after this
method has been called, except by calling g_object_unref() on it.
If observer
is not NULL it may be used to control the
authentication process.
When the operation is finished, callback
will be invoked. You can
then call g_dbus_connection_new_finish() to get the result of the
operation.
This is an asynchronous failable constructor. See
g_dbus_connection_new_sync() for the synchronous
version.
Since: 2.26
g_dbus_connection_new_sync ()
GDBusConnection *
g_dbus_connection_new_sync (GIOStream *stream,
const gchar *guid,
GDBusConnectionFlags flags,
GDBusAuthObserver *observer,
GCancellable *cancellable,
GError **error);
Synchronously sets up a D-Bus connection for exchanging D-Bus messages
with the end represented by stream
.
If stream
is a GSocketConnection, then the corresponding GSocket
will be put into non-blocking mode.
The D-Bus connection will interact with stream
from a worker thread.
As a result, the caller should not interact with stream
after this
method has been called, except by calling g_object_unref() on it.
If observer
is not NULL it may be used to control the
authentication process.
This is a synchronous failable constructor. See
g_dbus_connection_new() for the asynchronous version.
Returns
a GDBusConnection or NULL if error
is set. Free with g_object_unref().
Since: 2.26
g_dbus_connection_start_message_processing ()
void
g_dbus_connection_start_message_processing
(GDBusConnection *connection);
If connection
was created with
G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
starts processing messages. Does nothing on if connection
wasn't
created with this flag or if the method has already been called.
Since: 2.26
g_dbus_connection_close ()
void
g_dbus_connection_close (GDBusConnection *connection,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Closes connection
. Note that this never causes the process to
exit (this might only happen if the other end of a shared message
bus connection disconnects, see “exit-on-close”).
Once the connection is closed, operations such as sending a message
will return with the error G_IO_ERROR_CLOSED. Closing a connection
will not automatically flush the connection so queued messages may
be lost. Use g_dbus_connection_flush() if you need such guarantees.
If connection
is already closed, this method fails with
G_IO_ERROR_CLOSED.
When connection
has been closed, the “closed”
signal is emitted in the
thread-default main context
of the thread that connection
was constructed in.
This is an asynchronous method. When the operation is finished,
callback
will be invoked in the
thread-default main context
of the thread you are calling this method from. You can
then call g_dbus_connection_close_finish() to get the result of the
operation. See g_dbus_connection_close_sync() for the synchronous
version.
Since: 2.26
g_dbus_connection_close_sync ()
gboolean
g_dbus_connection_close_sync (GDBusConnection *connection,
GCancellable *cancellable,
GError **error);
Synchronously closes connection
. The calling thread is blocked
until this is done. See g_dbus_connection_close() for the
asynchronous version of this method and more details about what it
does.
Returns
TRUE if the operation succeeded, FALSE if error
is set
Since: 2.26
g_dbus_connection_is_closed ()
gboolean
g_dbus_connection_is_closed (GDBusConnection *connection);
Gets whether connection
is closed.
Returns
TRUE if the connection is closed, FALSE otherwise
Since: 2.26
g_dbus_connection_flush ()
void
g_dbus_connection_flush (GDBusConnection *connection,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously flushes connection
, that is, writes all queued
outgoing message to the transport and then flushes the transport
(using g_output_stream_flush_async()). This is useful in programs
that wants to emit a D-Bus signal and then exit immediately. Without
flushing the connection, there is no guaranteed that the message has
been sent to the networking buffers in the OS kernel.
This is an asynchronous method. When the operation is finished,
callback
will be invoked in the
thread-default main context
of the thread you are calling this method from. You can
then call g_dbus_connection_flush_finish() to get the result of the
operation. See g_dbus_connection_flush_sync() for the synchronous
version.
Since: 2.26
g_dbus_connection_flush_sync ()
gboolean
g_dbus_connection_flush_sync (GDBusConnection *connection,
GCancellable *cancellable,
GError **error);
Synchronously flushes connection
. The calling thread is blocked
until this is done. See g_dbus_connection_flush() for the
asynchronous version of this method and more details about what it
does.
Returns
TRUE if the operation succeeded, FALSE if error
is set
Since: 2.26
g_dbus_connection_get_exit_on_close ()
gboolean
g_dbus_connection_get_exit_on_close (GDBusConnection *connection);
Gets whether the process is terminated when connection
is
closed by the remote peer. See
“exit-on-close” for more details.
Returns
whether the process is terminated when connection
is
closed by the remote peer
Since: 2.26
g_dbus_connection_set_exit_on_close ()
void
g_dbus_connection_set_exit_on_close (GDBusConnection *connection,
gboolean exit_on_close);
Sets whether the process should be terminated when connection
is
closed by the remote peer. See “exit-on-close” for
more details.
Note that this function should be used with care. Most modern UNIX
desktops tie the notion of a user session with the session bus, and expect
all of a user's applications to quit when their bus connection goes away.
If you are setting exit_on_close
to FALSE for the shared session
bus connection, you should make sure that your application exits
when the user session ends.
Since: 2.26
g_dbus_connection_get_stream ()
GIOStream *
g_dbus_connection_get_stream (GDBusConnection *connection);
Gets the underlying stream used for IO.
While the GDBusConnection is active, it will interact with this
stream from a worker thread, so it is not safe to interact with
the stream directly.
Returns
the stream used for IO.
[transfer none]
Since: 2.26
g_dbus_connection_get_guid ()
const gchar *
g_dbus_connection_get_guid (GDBusConnection *connection);
The GUID of the peer performing the role of server when
authenticating. See “guid” for more details.
Returns
The GUID. Do not free this string, it is owned by
connection
.
Since: 2.26
g_dbus_connection_get_unique_name ()
const gchar *
g_dbus_connection_get_unique_name (GDBusConnection *connection);
Gets the unique name of connection
as assigned by the message
bus. This can also be used to figure out if connection
is a
message bus connection.
Returns
the unique name or NULL if connection
is not a message
bus connection. Do not free this string, it is owned by
connection
.
[nullable]
Since: 2.26
g_dbus_connection_get_peer_credentials ()
GCredentials *
g_dbus_connection_get_peer_credentials
(GDBusConnection *connection);
Gets the credentials of the authenticated peer. This will always
return NULL unless connection
acted as a server
(e.g. G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
when set up and the client passed credentials as part of the
authentication process.
In a message bus setup, the message bus is always the server and
each application is a client. So this method will always return
NULL for message bus clients.
Returns
a GCredentials or NULL if not
available. Do not free this object, it is owned by connection
.
[transfer none][nullable]
Since: 2.26
g_dbus_connection_call ()
void
g_dbus_connection_call (GDBusConnection *connection,
const gchar *bus_name,
const gchar *object_path,
const gchar *interface_name,
const gchar *method_name,
GVariant *parameters,
const GVariantType *reply_type,
GDBusCallFlags flags,
gint timeout_msec,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously invokes the method_name
method on the
interface_name
D-Bus interface on the remote object at
object_path
owned by bus_name
.
If connection
is closed then the operation will fail with
G_IO_ERROR_CLOSED. If cancellable
is canceled, the operation will
fail with G_IO_ERROR_CANCELLED. If parameters
contains a value
not compatible with the D-Bus protocol, the operation fails with
G_IO_ERROR_INVALID_ARGUMENT.
If reply_type
is non-NULL then the reply will be checked for having this type and an
error will be raised if it does not match. Said another way, if you give a reply_type
then any non-NULL return value will be of this type. Unless it’s
G_VARIANT_TYPE_UNIT, the reply_type
will be a tuple containing one or more
values.
If the parameters
GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.:
This is an asynchronous method. When the operation is finished,
callback
will be invoked in the
thread-default main context
of the thread you are calling this method from. You can then call
g_dbus_connection_call_finish() to get the result of the operation.
See g_dbus_connection_call_sync() for the synchronous version of this
function.
If callback
is NULL then the D-Bus method call message will be sent with
the G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
Since: 2.26
g_dbus_connection_call_finish ()
GVariant *
g_dbus_connection_call_finish (GDBusConnection *connection,
GAsyncResult *res,
GError **error);
Finishes an operation started with g_dbus_connection_call().
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.26
g_dbus_connection_call_sync ()
GVariant *
g_dbus_connection_call_sync (GDBusConnection *connection,
const gchar *bus_name,
const gchar *object_path,
const gchar *interface_name,
const gchar *method_name,
GVariant *parameters,
const GVariantType *reply_type,
GDBusCallFlags flags,
gint timeout_msec,
GCancellable *cancellable,
GError **error);
Synchronously invokes the method_name
method on the
interface_name
D-Bus interface on the remote object at
object_path
owned by bus_name
.
If connection
is closed then the operation will fail with
G_IO_ERROR_CLOSED. If cancellable
is canceled, the
operation will fail with G_IO_ERROR_CANCELLED. If parameters
contains a value not compatible with the D-Bus protocol, the operation
fails with G_IO_ERROR_INVALID_ARGUMENT.
If reply_type
is non-NULL then the reply will be checked for having
this type and an error will be raised if it does not match. Said
another way, if you give a reply_type
then any non-NULL return
value will be of this type.
If the parameters
GVariant is floating, it is consumed.
This allows convenient 'inline' use of g_variant_new(), e.g.:
The calling thread is blocked until a reply is received. See
g_dbus_connection_call() for the asynchronous version of
this method.
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.26
g_dbus_connection_call_with_unix_fd_list ()
void
g_dbus_connection_call_with_unix_fd_list
(GDBusConnection *connection,
const gchar *bus_name,
const gchar *object_path,
const gchar *interface_name,
const gchar *method_name,
GVariant *parameters,
const GVariantType *reply_type,
GDBusCallFlags flags,
gint timeout_msec,
GUnixFDList *fd_list,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Like g_dbus_connection_call() but also takes a GUnixFDList object.
This method is only available on UNIX.
Since: 2.30
g_dbus_connection_call_with_unix_fd_list_sync ()
GVariant *
g_dbus_connection_call_with_unix_fd_list_sync
(GDBusConnection *connection,
const gchar *bus_name,
const gchar *object_path,
const gchar *interface_name,
const gchar *method_name,
GVariant *parameters,
const GVariantType *reply_type,
GDBusCallFlags flags,
gint timeout_msec,
GUnixFDList *fd_list,
GUnixFDList **out_fd_list,
GCancellable *cancellable,
GError **error);
Like g_dbus_connection_call_sync() but also takes and returns GUnixFDList objects.
This method is only available on UNIX.
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.30
g_dbus_connection_emit_signal ()
gboolean
g_dbus_connection_emit_signal (GDBusConnection *connection,
const gchar *destination_bus_name,
const gchar *object_path,
const gchar *interface_name,
const gchar *signal_name,
GVariant *parameters,
GError **error);
Emits a signal.
If the parameters GVariant is floating, it is consumed.
This can only fail if parameters
is not compatible with the D-Bus protocol
(G_IO_ERROR_INVALID_ARGUMENT), or if connection
has been closed
(G_IO_ERROR_CLOSED).
Returns
TRUE unless error
is set
Since: 2.26
GDBusSignalCallback ()
void
(*GDBusSignalCallback) (GDBusConnection *connection,
const gchar *sender_name,
const gchar *object_path,
const gchar *interface_name,
const gchar *signal_name,
GVariant *parameters,
gpointer user_data);
Signature for callback function used in g_dbus_connection_signal_subscribe().
Since: 2.26
g_dbus_connection_signal_subscribe ()
guint
g_dbus_connection_signal_subscribe (GDBusConnection *connection,
const gchar *sender,
const gchar *interface_name,
const gchar *member,
const gchar *object_path,
const gchar *arg0,
GDBusSignalFlags flags,
GDBusSignalCallback callback,
gpointer user_data,
GDestroyNotify user_data_free_func);
Subscribes to signals on connection
and invokes callback
with a whenever
the signal is received. Note that callback
will be invoked in the
thread-default main context
of the thread you are calling this method from.
If connection
is not a message bus connection, sender
must be
NULL.
If sender
is a well-known name note that callback
is invoked with
the unique name for the owner of sender
, not the well-known name
as one would expect. This is because the message bus rewrites the
name. As such, to avoid certain race conditions, users should be
tracking the name owner of the well-known name and use that when
processing the received signal.
If one of G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or
G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, arg0
is
interpreted as part of a namespace or path. The first argument
of a signal is matched against that part as specified by D-Bus.
If user_data_free_func
is non-NULL, it will be called (in the
thread-default main context of the thread you are calling this
method from) at some point after user_data
is no longer
needed. (It is not guaranteed to be called synchronously when the
signal is unsubscribed from, and may be called after connection
has been destroyed.)
As callback
is potentially invoked in a different thread from where it’s
emitted, it’s possible for this to happen after
g_dbus_connection_signal_unsubscribe() has been called in another thread.
Due to this, user_data
should have a strong reference which is freed with
user_data_free_func
, rather than pointing to data whose lifecycle is tied
to the signal subscription. For example, if a GObject is used to store the
subscription ID from g_dbus_connection_signal_subscribe(), a strong reference
to that GObject must be passed to user_data
, and g_object_unref() passed to
user_data_free_func
. You are responsible for breaking the resulting
reference count cycle by explicitly unsubscribing from the signal when
dropping the last external reference to the GObject. Alternatively, a weak
reference may be used.
It is guaranteed that if you unsubscribe from a signal using
g_dbus_connection_signal_unsubscribe() from the same thread which made the
corresponding g_dbus_connection_signal_subscribe() call, callback
will not
be invoked after g_dbus_connection_signal_unsubscribe() returns.
The returned subscription identifier is an opaque value which is guaranteed
to never be zero.
This function can never fail.
Since: 2.26
g_dbus_connection_signal_unsubscribe ()
void
g_dbus_connection_signal_unsubscribe (GDBusConnection *connection,
guint subscription_id);
Unsubscribes from signals.
Note that there may still be D-Bus traffic to process (relating to this
signal subscription) in the current thread-default GMainContext after this
function has returned. You should continue to iterate the GMainContext
until the GDestroyNotify function passed to
g_dbus_connection_signal_subscribe() is called, in order to avoid memory
leaks through callbacks queued on the GMainContext after it’s stopped being
iterated.
Since: 2.26
g_dbus_connection_send_message ()
gboolean
g_dbus_connection_send_message (GDBusConnection *connection,
GDBusMessage *message,
GDBusSendMessageFlags flags,
volatile guint32 *out_serial,
GError **error);
Asynchronously sends message
to the peer represented by connection
.
Unless flags
contain the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
will be assigned by connection
and set on message
via
g_dbus_message_set_serial(). If out_serial
is not NULL, then the
serial number used will be written to this location prior to
submitting the message to the underlying transport.
If connection
is closed then the operation will fail with
G_IO_ERROR_CLOSED. If message
is not well-formed,
the operation fails with G_IO_ERROR_INVALID_ARGUMENT.
See this server and client
for an example of how to use this low-level API to send and receive
UNIX file descriptors.
Note that message
must be unlocked, unless flags
contain the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
Returns
TRUE if the message was well-formed and queued for
transmission, FALSE if error
is set
Since: 2.26
g_dbus_connection_send_message_with_reply ()
void
g_dbus_connection_send_message_with_reply
(GDBusConnection *connection,
GDBusMessage *message,
GDBusSendMessageFlags flags,
gint timeout_msec,
volatile guint32 *out_serial,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously sends message
to the peer represented by connection
.
Unless flags
contain the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
will be assigned by connection
and set on message
via
g_dbus_message_set_serial(). If out_serial
is not NULL, then the
serial number used will be written to this location prior to
submitting the message to the underlying transport.
If connection
is closed then the operation will fail with
G_IO_ERROR_CLOSED. If cancellable
is canceled, the operation will
fail with G_IO_ERROR_CANCELLED. If message
is not well-formed,
the operation fails with G_IO_ERROR_INVALID_ARGUMENT.
This is an asynchronous method. When the operation is finished, callback
will be invoked in the
thread-default main context
of the thread you are calling this method from. You can then call
g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
Note that message
must be unlocked, unless flags
contain the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
See this server and client
for an example of how to use this low-level API to send and receive
UNIX file descriptors.
Since: 2.26
g_dbus_connection_send_message_with_reply_sync ()
GDBusMessage *
g_dbus_connection_send_message_with_reply_sync
(GDBusConnection *connection,
GDBusMessage *message,
GDBusSendMessageFlags flags,
gint timeout_msec,
volatile guint32 *out_serial,
GCancellable *cancellable,
GError **error);
Synchronously sends message
to the peer represented by connection
and blocks the calling thread until a reply is received or the
timeout is reached. See g_dbus_connection_send_message_with_reply()
for the asynchronous version of this method.
Unless flags
contain the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
will be assigned by connection
and set on message
via
g_dbus_message_set_serial(). If out_serial
is not NULL, then the
serial number used will be written to this location prior to
submitting the message to the underlying transport.
If connection
is closed then the operation will fail with
G_IO_ERROR_CLOSED. If cancellable
is canceled, the operation will
fail with G_IO_ERROR_CANCELLED. If message
is not well-formed,
the operation fails with G_IO_ERROR_INVALID_ARGUMENT.
Note that error
is only set if a local in-process error
occurred. That is to say that the returned GDBusMessage object may
be of type G_DBUS_MESSAGE_TYPE_ERROR. Use
g_dbus_message_to_gerror() to transcode this to a GError.
See this server and client
for an example of how to use this low-level API to send and receive
UNIX file descriptors.
Note that message
must be unlocked, unless flags
contain the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
Returns
a locked GDBusMessage that is the reply
to message
or NULL if error
is set.
[transfer full]
Since: 2.26
GDBusMessageFilterFunction ()
GDBusMessage *
(*GDBusMessageFilterFunction) (GDBusConnection *connection,
GDBusMessage *message,
gboolean incoming,
gpointer user_data);
Signature for function used in g_dbus_connection_add_filter().
A filter function is passed a GDBusMessage and expected to return
a GDBusMessage too. Passive filter functions that don't modify the
message can simply return the message
object:
Filter functions that wants to drop a message can simply return NULL:
Finally, a filter function may modify a message by copying it:
If the returned GDBusMessage is different from message
and cannot
be sent on connection
(it could use features, such as file
descriptors, not compatible with connection
), then a warning is
logged to standard error. Applications can
check this ahead of time using g_dbus_message_to_blob() passing a
GDBusCapabilityFlags value obtained from connection
.
Returns
A GDBusMessage that will be freed with
g_object_unref() or NULL to drop the message. Passive filter
functions can simply return the passed message
object.
[transfer full][nullable]
Since: 2.26
g_dbus_connection_add_filter ()
guint
g_dbus_connection_add_filter (GDBusConnection *connection,
GDBusMessageFilterFunction filter_function,
gpointer user_data,
GDestroyNotify user_data_free_func);
Adds a message filter. Filters are handlers that are run on all
incoming and outgoing messages, prior to standard dispatch. Filters
are run in the order that they were added. The same handler can be
added as a filter more than once, in which case it will be run more
than once. Filters added during a filter callback won't be run on
the message being processed. Filter functions are allowed to modify
and even drop messages.
Note that filters are run in a dedicated message handling thread so
they can't block and, generally, can't do anything but signal a
worker thread. Also note that filters are rarely needed - use API
such as g_dbus_connection_send_message_with_reply(),
g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
If a filter consumes an incoming message the message is not
dispatched anywhere else - not even the standard dispatch machinery
(that API such as g_dbus_connection_signal_subscribe() and
g_dbus_connection_send_message_with_reply() relies on) will see the
message. Similarly, if a filter consumes an outgoing message, the
message will not be sent to the other peer.
If user_data_free_func
is non-NULL, it will be called (in the
thread-default main context of the thread you are calling this
method from) at some point after user_data
is no longer
needed. (It is not guaranteed to be called synchronously when the
filter is removed, and may be called after connection
has been
destroyed.)
Since: 2.26
g_dbus_connection_remove_filter ()
void
g_dbus_connection_remove_filter (GDBusConnection *connection,
guint filter_id);
Removes a filter.
Note that since filters run in a different thread, there is a race
condition where it is possible that the filter will be running even
after calling g_dbus_connection_remove_filter(), so you cannot just
free data that the filter might be using. Instead, you should pass
a GDestroyNotify to g_dbus_connection_add_filter(), which will be
called when it is guaranteed that the data is no longer needed.
Since: 2.26
GDBusInterfaceMethodCallFunc ()
void
(*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
const gchar *interface_name,
const gchar *method_name,
GVariant *parameters,
GDBusMethodInvocation *invocation,
gpointer user_data);
The type of the method_call
function in GDBusInterfaceVTable.
Since: 2.26
GDBusInterfaceGetPropertyFunc ()
GVariant *
(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
const gchar *interface_name,
const gchar *property_name,
GError **error,
gpointer user_data);
The type of the get_property
function in GDBusInterfaceVTable.
Returns
A GVariant with the value for property_name
or NULL if
error
is set. If the returned GVariant is floating, it is
consumed - otherwise its reference count is decreased by one.
Since: 2.26
GDBusInterfaceSetPropertyFunc ()
gboolean
(*GDBusInterfaceSetPropertyFunc) (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
const gchar *interface_name,
const gchar *property_name,
GVariant *value,
GError **error,
gpointer user_data);
The type of the set_property
function in GDBusInterfaceVTable.
Returns
TRUE if the property was set to value
, FALSE if error
is set.
Since: 2.26
g_dbus_connection_register_object ()
guint
g_dbus_connection_register_object (GDBusConnection *connection,
const gchar *object_path,
GDBusInterfaceInfo *interface_info,
const GDBusInterfaceVTable *vtable,
gpointer user_data,
GDestroyNotify user_data_free_func,
GError **error);
Registers callbacks for exported objects at object_path
with the
D-Bus interface that is described in interface_info
.
Calls to functions in vtable
(and user_data_free_func
) will happen
in the
thread-default main context
of the thread you are calling this method from.
Note that all GVariant values passed to functions in vtable
will match
the signature given in interface_info
- if a remote caller passes
incorrect values, the org.freedesktop.DBus.Error.InvalidArgs
is returned to the remote caller.
Additionally, if the remote caller attempts to invoke methods or
access properties not mentioned in interface_info
the
org.freedesktop.DBus.Error.UnknownMethod resp.
org.freedesktop.DBus.Error.InvalidArgs errors
are returned to the caller.
It is considered a programming error if the
GDBusInterfaceGetPropertyFunc function in vtable
returns a
GVariant of incorrect type.
If an existing callback is already registered at object_path
and
interface_name
, then error
is set to G_IO_ERROR_EXISTS.
GDBus automatically implements the standard D-Bus interfaces
org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
and org.freedesktop.Peer, so you don't have to implement those for the
objects you export. You can implement org.freedesktop.DBus.Properties
yourself, e.g. to handle getting and setting of properties asynchronously.
Note that the reference count on interface_info
will be
incremented by 1 (unless allocated statically, e.g. if the
reference count is -1, see g_dbus_interface_info_ref()) for as long
as the object is exported. Also note that vtable
will be copied.
See this server for an example of how to use this method.
Since: 2.26
g_dbus_connection_unregister_object ()
gboolean
g_dbus_connection_unregister_object (GDBusConnection *connection,
guint registration_id);
Unregisters an object.
Returns
TRUE if the object was unregistered, FALSE otherwise
Since: 2.26
g_dbus_connection_register_object_with_closures ()
guint
g_dbus_connection_register_object_with_closures
(GDBusConnection *connection,
const gchar *object_path,
GDBusInterfaceInfo *interface_info,
GClosure *method_call_closure,
GClosure *get_property_closure,
GClosure *set_property_closure,
GError **error);
Version of g_dbus_connection_register_object() using closures instead of a
GDBusInterfaceVTable for easier binding in other languages.
[rename-to g_dbus_connection_register_object]
Since: 2.46
GDBusSubtreeEnumerateFunc ()
gchar **
(*GDBusSubtreeEnumerateFunc) (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
gpointer user_data);
The type of the enumerate
function in GDBusSubtreeVTable.
This function is called when generating introspection data and also
when preparing to dispatch incoming messages in the event that the
G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
specified (ie: to verify that the object path is valid).
Hierarchies are not supported; the items that you return should not
contain the '/' character.
The return value will be freed with g_strfreev().
Returns
A newly allocated array of strings for node names that are children of object_path
.
Since: 2.26
GDBusSubtreeIntrospectFunc ()
GDBusInterfaceInfo **
(*GDBusSubtreeIntrospectFunc) (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
const gchar *node,
gpointer user_data);
The type of the introspect
function in GDBusSubtreeVTable.
Subtrees are flat. node
, if non-NULL, is always exactly one
segment of the object path (ie: it never contains a slash).
This function should return NULL to indicate that there is no object
at this node.
If this function returns non-NULL, the return value is expected to
be a NULL-terminated array of pointers to GDBusInterfaceInfo
structures describing the interfaces implemented by node
. This
array will have g_dbus_interface_info_unref() called on each item
before being freed with g_free().
The difference between returning NULL and an array containing zero
items is that the standard DBus interfaces will returned to the
remote introspector in the empty array case, but not in the NULL
case.
Since: 2.26
GDBusSubtreeDispatchFunc ()
const GDBusInterfaceVTable *
(*GDBusSubtreeDispatchFunc) (GDBusConnection *connection,
const gchar *sender,
const gchar *object_path,
const gchar *interface_name,
const gchar *node,
gpointer *out_user_data,
gpointer user_data);
The type of the dispatch
function in GDBusSubtreeVTable.
Subtrees are flat. node
, if non-NULL, is always exactly one
segment of the object path (ie: it never contains a slash).
Since: 2.26
g_dbus_connection_register_subtree ()
guint
g_dbus_connection_register_subtree (GDBusConnection *connection,
const gchar *object_path,
const GDBusSubtreeVTable *vtable,
GDBusSubtreeFlags flags,
gpointer user_data,
GDestroyNotify user_data_free_func,
GError **error);
Registers a whole subtree of dynamic objects.
The enumerate
and introspection
functions in vtable
are used to
convey, to remote callers, what nodes exist in the subtree rooted
by object_path
.
When handling remote calls into any node in the subtree, first the
enumerate
function is used to check if the node exists. If the node exists
or the G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
the introspection
function is used to check if the node supports the
requested method. If so, the dispatch
function is used to determine
where to dispatch the call. The collected GDBusInterfaceVTable and
gpointer will be used to call into the interface vtable for processing
the request.
All calls into user-provided code will be invoked in the
thread-default main context
of the thread you are calling this method from.
If an existing subtree is already registered at object_path
or
then error
is set to G_IO_ERROR_EXISTS.
Note that it is valid to register regular objects (using
g_dbus_connection_register_object()) in a subtree registered with
g_dbus_connection_register_subtree() - if so, the subtree handler
is tried as the last resort. One way to think about a subtree
handler is to consider it a fallback handler for object paths not
registered via g_dbus_connection_register_object() or other bindings.
Note that vtable
will be copied so you cannot change it after
registration.
See this server for an example of how to use
this method.
Since: 2.26
g_dbus_connection_unregister_subtree ()
gboolean
g_dbus_connection_unregister_subtree (GDBusConnection *connection,
guint registration_id);
Unregisters a subtree.
Returns
TRUE if the subtree was unregistered, FALSE otherwise
Since: 2.26