Gio.DBusConnection.signal_subscribe

### Method

# Gio DBusConnectionsignal_subscribe

since: 2.26

#### Declaration [src]

    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
    )

#### Description [src]

Subscribes to signals on `connection` and invokes `callback` whenever the signal is received. Note that `callback` will be invoked in the thread-default main context (see `g_main_context_push_thread_default()`) 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.

Available since: 2.26

#### Parameters

`sender`

  Type: `const gchar*`

  Sender name to match on (unique or well-known name) or `NULL` to listen from all senders.

  The argument can be `NULL`.
  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

`interface_name`

  Type: `const gchar*`

  D-Bus interface name to match on or `NULL` to match on all interfaces.

  The argument can be `NULL`.
  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

`member`

  Type: `const gchar*`

  D-Bus signal name to match on or `NULL` to match on all signals.

  The argument can be `NULL`.
  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

`object_path`

  Type: `const gchar*`

  Object path to match on or `NULL` to match on all object paths.

  The argument can be `NULL`.
  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

`arg0`

  Type: `const gchar*`

  Contents of first string argument to match on or `NULL` to match on all kinds of arguments.

  The argument can be `NULL`.
  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

`flags`

  Type: `GDBusSignalFlags`

  `GDBusSignalFlags` describing how arg0 is used in subscribing to the signal.

`callback`

  Type: `GDBusSignalCallback`

  Callback to invoke when there is a signal matching the requested data.

`user_data`

  Type: `gpointer`

  User data to pass to `callback`.

  The argument can be `NULL`.
  The data is owned by the caller of the method.

`user_data_free_func`

  Type: `GDestroyNotify`

  Function to free `user_data` with when subscription is removed or `NULL`.

  The argument can be `NULL`.

#### Return value

Type: `guint`

A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().