GDBusMessageFilterFunction

Signature for function used in g_dbus_connection_add_filter().

A filter function is passed a gio.DBusMessage and expected to return a gio.DBusMessage 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;
}

inally, 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 [gio.DBusMessage.DBusMessage|gio.DBusMessage] 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
[GDBusCapabilityFlag|GDBusCapabilityFlags] value obtained from `connection`.

Params:
    connection = A [gio.DBusConnection.DBusConnection|gio.DBusConnection]
    message = A locked [gio.DBusMessage.DBusMessage|gio.DBusMessage] that the filter function takes ownership of.
    incoming = `TRUE` if it is a message received from the other peer, `FALSE` if it is
        a message to be sent to the other peer.
    userData = User data passed when adding the filter.

Returns: A [gio.DBusMessage.DBusMessage|gio.DBusMessage] that will be freed with
    `g_object_unref()` or `NULL` to drop the message. Passive filter
    functions can simply return the passed `message` object.

Since: 2.26