### Function

# Gio DBusMessageFilterFunction

since: 2.26

#### 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`

  Type: `GDBusConnection`

  A `GDBusConnection`.

  The data is owned by the caller of the function.

`message`

  Type: `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`

  Type: `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`

  Type: `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

Type: `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`.