DBusMessageFilterFunction

Signature for function used in add_filter.

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

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 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 to_blob passing a DBusCapabilityFlags value obtained from connection.

Parameters:

connection	A DBusConnection.
message	A locked 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.
user_data	User data passed when adding the filter.

Returns:

A DBusMessage that will be freed with unref or null to drop the message. Passive filter functions can simply return the passed message object.