Function

GioDBusMessageFilterFunction

Declaration

GDBusMessage*
(* GDBusMessageFilterFunction) (
  GDBusConnection* connection,
  GDBusMessage* message,
  gboolean incoming,
  gpointer user_data
)

Description

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:

static GDBusMessage *
passive_filter (GDBusConnection *connection
                GDBusMessage    *message,
                gboolean         incoming,
                gpointer         user_data)
{
  // inspect @message
  return message;
}

Filter functions that wants to drop a message can simply return NULL:

static GDBusMessage *
drop_filter (GDBusConnection *connection
             GDBusMessage    *message,
             gboolean         incoming,
             gpointer         user_data)
{
  if (should_drop_message)
    {
      g_object_unref (message);
      message = NULL;
    }
  return message;
}

Finally, a filter function may modify a message by copying it:

static GDBusMessage *
modifying_filter (GDBusConnection *connection
                  GDBusMessage    *message,
                  gboolean         incoming,
                  gpointer         user_data)
{
  GDBusMessage *copy;
  GError *error;

  error = NULL;
  copy = g_dbus_message_copy (message, &error);
  // handle @error being set
  g_object_unref (message);

  // modify @copy

  return copy;
}

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.

Available since:

2.26

Parameters

`connection`	`GDBusConnection`
	A `GDBusConnection`.
	The data is owned by the caller of the function.
`message`	`GDBusMessage`
	A locked `GDBusMessage` that the filter function takes ownership of.
	The called function takes ownership of the data, and is responsible for freeing it.
`incoming`	`gboolean`
	`TRUE` if it is a message received from the other peer, `FALSE` if it is a message to be sent to the other peer.
`user_data`	`gpointer`
	User data passed when adding the filter.
	The argument can be `NULL`.
	The data is owned by the caller of the function.

Return value

Returns:	`GDBusMessage`
	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.
	The caller of the function takes ownership of the data, and is responsible for freeing it.
	The return value can be `NULL`.