DBusMessageFilterFunction


Description:

[ Version ( since = "2.26" ) ]
public delegate DBusMessage? DBusMessageFilterFunction (DBusConnection connection, owned DBusMessage message, bool incoming)

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.


Namespace: GLib
Package: gio-2.0