TpChannelFilter

TpChannelFilter — a filter matching certain channels

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── TpChannelFilter

Includes

#include <telepathy-glib/telepathy-glib.h>

Description

Telepathy clients are notified about "interesting" TpChannels by the Channel Dispatcher. To do this efficiently, the clients have lists of "channel filters", describing the channels that each client considers to be "interesting".

In telepathy-glib, these lists take the form of lists of TpChannelFilter objects. Each TpChannelFilter matches certain properties of the channel, and the channel dispatcher dispatches a channel to a client if that channel matches any of the filters in the client's list:

1
2
3
4
5
6
7
channel is interesting to this client = (
    ((channel matches property A from filter 1) &&
     (channel matches property B from filter 1) && ...)
     ||
    ((channel matches property P from filter 2) &&
     (channel matches property Q from filter 2) && ...)
     || ...)

An empty list of filters does not match any channels, but a list containing an empty filter matches every channel.

To construct a filter, either create an empty filter with tp_channel_filter_new(), or create a pre-populated filter with certain properties using one of the convenience constructors like tp_channel_filter_new_for_text_chats().

After creating a filter, you can make it more specific by using methods like tp_channel_filter_require_locally_requested(), if required.

Finally, add it to a TpBaseClient using tp_base_client_add_observer_filter(), tp_base_client_add_approver_filter() and/or tp_base_client_add_handler_filter() (depending on the type of client required), and release the filter object with g_object_unref().

If you would like the TpBaseClient to act on particular channels in more than one role - for instance, an Approver for Text channels which is also a Handler for Text channels - you can add the same TpChannelFilter object via more than one method.

Once you have added a filter object to a TpBaseClient, you may not modify it further.

Functions

tp_channel_filter_new_for_all_types ()

TpChannelFilter *
tp_channel_filter_new_for_all_types (void);

Return a channel filter that matches every channel.

You can make the filter more restrictive by setting properties.


tp_channel_filter_new_for_calls ()

TpChannelFilter *
tp_channel_filter_new_for_calls (TpEntityType entity_type);

Return a channel filter that matches audio and video calls, including VoIP and telephony.

entity_type is passed to tp_channel_filter_require_target_type(). Use TP_ENTITY_TYPE_CONTACT for ordinary 1-1 calls.

Parameters

entity_type

the desired entity type

 

tp_channel_filter_new_for_dbus_tubes ()

TpChannelFilter *
tp_channel_filter_new_for_dbus_tubes (const gchar *service);

Return a channel filter that matches D-Bus tube channels, as used by TpDBusTubeChannel, and optionally also match a particular service. This filter can be narrowed further via other methods.

For instance, to match a "com.example.Chess" tube being offered by the local user to a peer:

1
2
3
filter = tp_channel_filter_new_for_dbus_tube ("com.example.Chess");
tp_channel_filter_require_target_is_contact (filter);
tp_channel_filter_require_locally_requested (filter, TRUE);

Parameters

service

the desired value of “service-name”, or NULL to match any service.

[allow-none]

tp_channel_filter_new_for_file_transfers ()

TpChannelFilter *
tp_channel_filter_new_for_file_transfers
                               (const gchar *service);

Return a channel filter that matches file transfer channels with a TpContact, as used by TpFileTransferChannel.

At the time of writing, file transfers with other types of target (like chatrooms) have not been implemented. If they are, they will use a different filter.

Using this method will match both incoming and outgoing file transfers. If you only want to match one direction, use tp_channel_filter_require_locally_requested() to select it.

For instance, to match outgoing file transfers (sending a file to a contact), you can use:

1
2
filter = tp_channel_filter_new_for_file_transfer (NULL);
tp_channel_filter_require_locally_requested (filter, TRUE);

service can be used by collaborative applications to match a particular “service-name”. For instance, if an application wants to be the handler for incoming file transfers that are marked as belonging to that application, it could use a filter like this:

1
2
3
filter = tp_channel_filter_new_for_file_transfer ("com.example.MyApp");
tp_channel_filter_require_locally_requested (filter, FALSE);
tp_base_client_take_handler_filter (client, filter);

Parameters

service

a service name, or NULL.

[allow-none]

tp_channel_filter_new_for_stream_tubes ()

TpChannelFilter *
tp_channel_filter_new_for_stream_tubes
                               (const gchar *service);

Return a channel filter that matches stream tube channels, as used by TpStreamTubeChannel, and optionally also match a particular service. This filter can be narrowed further via other methods.

For instance, to match RFB display-sharing being offered by another participant in a chatroom:

Parameters

service

the desired value of “service”, or NULL to match any service.

[allow-none]

tp_channel_filter_new_for_text_chatrooms ()

TpChannelFilter *
tp_channel_filter_new_for_text_chatrooms
                               (void);

Return a channel filter that matches participation in named text chatrooms, such as TpTextChannels communicating with an XMPP Multi-User Chat room or an IRC channel.

It is not necessary to call tp_channel_filter_require_target_is_room() on the returned filter.


tp_channel_filter_new_for_text_chats ()

TpChannelFilter *
tp_channel_filter_new_for_text_chats (void);

Return a channel filter that matches 1-1 text chats, such as TpTextChannels carrying private messages or SMSs.

It is not necessary to call tp_channel_filter_require_target_is_contact() on the returned filter.


tp_channel_filter_require_locally_requested ()

void
tp_channel_filter_require_locally_requested
                               (TpChannelFilter *self,
                                gboolean requested);

Narrow self to require that the channel was requested by the local user, or to require that the channel was not requested by the local user, depending on the value of requested .

For instance, to match an outgoing (locally-requested) 1-1 call:

1
2
filter = tp_channel_filter_new_for_calls (TP_ENTITY_TYPE_CONTACT);
tp_channel_filter_require_locally_requested (filter, TRUE);

or to match an incoming (not locally-requested) file transfer:

1
2
filter = tp_channel_filter_new_for_file_transfer ();
tp_channel_filter_require_locally_requested (filter, FALSE);

It is an error to call this method if the channel filter has already been passed to a TpBaseClient.

Parameters

self

a channel filter

 

requested

the desired value for tp_channel_get_requested()

 

tp_channel_filter_require_no_target ()

void
tp_channel_filter_require_no_target (TpChannelFilter *self);

Narrow self to require that the channel communicates with an ad-hoc, unnamed group of contacts.

For instance, among other things, this filter would match TpCallChannels for conference calls in cellular telephony.

This is equivalent to tp_channel_filter_require_target_type() with argument TP_ENTITY_TYPE_NONE.

It is an error to call this method if the channel filter has already been passed to a TpBaseClient.

Parameters

self

a channel filter

 

tp_channel_filter_require_target_is_contact ()

void
tp_channel_filter_require_target_is_contact
                               (TpChannelFilter *self);

Narrow self to require that the channel communicates with a single TpContact.

For instance, the filter would match TpTextChannels carrying private messages or SMSs, TpCallChannels for ordinary 1-1 audio and/or video calls, TpFileTransferChannels for file transfers to or from a contact, and so on.

It would not match channels communicating with a chatroom, ad-hoc chatrooms with no name, or conference-calls (in protocols that can tell the difference between a conference call and an ordinary 1-1 call).

It is an error to call this method if the channel filter has already been passed to a TpBaseClient.

Parameters

self

a channel filter

 

tp_channel_filter_require_target_is_room ()

void
tp_channel_filter_require_target_is_room
                               (TpChannelFilter *self);

Narrow self to require that the channel communicates with a named chatroom.

For instance, this filter would match TpTextChannels communicating with an XMPP Multi-User Chat room or an IRC channel. It would also match TpDBusTubeChannels or TpStreamTubeChannels that communicate through a chatroom, and multi-user audio and/or video calls that use a named, chatroom-like object on the server.

It is an error to call this method if the channel filter has already been passed to a TpBaseClient.

Parameters

self

a channel filter

 

tp_channel_filter_require_target_type ()

void
tp_channel_filter_require_target_type (TpChannelFilter *self,
                                       TpEntityType entity_type);

Narrow self to require a particular target entity type.

For instance, setting entity_type to TP_ENTITY_TYPE_CONTACT is equivalent to tp_channel_filter_require_target_is_contact().

It is an error to call this method if the channel filter has already been passed to a TpBaseClient.

Parameters

self

a channel filter

 

entity_type

the desired value for “entity-type”

 

tp_channel_filter_require_property ()

void
tp_channel_filter_require_property (TpChannelFilter *self,
                                    const gchar *name,
                                    GVariant *value);

Narrow self to require that the immutable channel property name has the given value.

If value is a floating reference, this method will take ownership of it.

value must not contain any GVariant extensions not supported by dbus-glib, such as G_VARIANT_TYPE_UNIT or G_VARIANT_TYPE_HANDLE.

For instance, tp_channel_filter_require_target_is_contact() is equivalent to:

1
2
3
tp_channel_filter_require_property (filter,
    TP_PROP_CHANNEL_TARGET_ENTITY_TYPE,
    g_variant_new_uint32 (TP_ENTITY_TYPE_CONTACT));

It is an error to call this method if the channel filter has already been passed to a TpBaseClient.

Parameters

self

a channel filter

 

name

a fully-qualified D-Bus property name (in the format "interface.name.propertyname") as described by the Telepathy D-Bus API Specification

 

value

the value required for name

 

Types and Values

TpChannelFilter

typedef struct _TpChannelFilter TpChannelFilter;

A filter matching certain channels.

See Also

TpBaseClient, TpSimpleApprover, TpSimpleHandler, TpSimpleObserver