Method

GioDBusConnectionadd_filter

since: 2.26

Declaration [src] 

guint
g_dbus_connection_add_filter (
  GDBusConnection* connection,
  GDBusMessageFilterFunction filter_function,
  gpointer user_data,
  GDestroyNotify user_data_free_func
)

Description [src]

Adds a message filter. Filters are handlers that are run on all incoming and outgoing messages, prior to standard dispatch. Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won’t be run on the message being processed. Filter functions are allowed to modify and even drop messages.

Note that filters are run in a dedicated message handling thread so they can’t block and, generally, can’t do anything but signal a worker thread. Also note that filters are rarely needed - use API such as g_dbus_connection_send_message_with_reply(), g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.

If a filter consumes an incoming message the message is not dispatched anywhere else - not even the standard dispatch machinery (that API such as g_dbus_connection_signal_subscribe() and g_dbus_connection_send_message_with_reply() relies on) will see the message. Similarly, if a filter consumes an outgoing message, the message will not be sent to the other peer.

If user_data_free_func is non-NULL, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after user_data is no longer needed. (It is not guaranteed to be called synchronously when the filter is removed, and may be called after connection has been destroyed.).

Available since: 2.26

Parameters

filter_function

Type: GDBusMessageFilterFunction

A filter function.

user_data

Type: gpointer

User data to pass to filter_function.

The argument can be NULL.
The data is owned by the caller of the method.
user_data_free_func

Type: GDestroyNotify

Function to free user_data with when filter is removed or NULL.

Return value

Type: guint

A filter identifier that can be used with g_dbus_connection_remove_filter().