TpCapabilities: telepathy-glib API Reference Manual

## TpCapabilities TpCapabilities — object representing capabilities |

## Functions

GPtrArray * | tp_capabilities_get_channel_classes ()
GVariant * | tp_capabilities_dup_channel_classes_variant ()
gboolean | tp_capabilities_is_specific_to_contact ()
gboolean | tp_capabilities_supports_text_chatrooms ()
gboolean | tp_capabilities_supports_text_chats ()
gboolean | tp_capabilities_supports_sms ()
gboolean | tp_capabilities_supports_audio_call ()
gboolean | tp_capabilities_supports_audio_video_call ()
gboolean | tp_capabilities_supports_file_transfer ()
gboolean | tp_capabilities_supports_file_transfer_description ()
gboolean | tp_capabilities_supports_file_transfer_initial_offset ()
gboolean | tp_capabilities_supports_file_transfer_timestamp ()
gboolean | tp_capabilities_supports_file_transfer_uri ()
gboolean | tp_capabilities_supports_stream_tubes ()
gboolean | tp_capabilities_supports_dbus_tubes ()
gboolean | tp_capabilities_supports_contact_search ()
gboolean | tp_capabilities_supports_room_list ()

## Properties

GPtrArray_GValueArray_GHashTable_gchararray+GValue_+GStrv__* | channel-classes | Read / Write / Construct Only
GVariant * | channel-classes-variant | Read
gboolean | contact-specific | Read / Write / Construct Only

## Types and Values

| TpCapabilities

## Object Hierarchy

        GObject
        ╰── TpCapabilities

## Includes

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

## Description

TpCapabilities objects represent the capabilities a TpConnection or a TpContact supports.

## Functions

### tp_capabilities_get_channel_classes ()

    GPtrArray *
    tp_capabilities_get_channel_classes (TpCapabilities *self);

#### Parameters

self | a TpCapabilities object |

#### Returns

the same GPtrArray as the “channel-classes” property.

[transfer none][element-type GHashTable]

Since: 0.11.3

### tp_capabilities_dup_channel_classes_variant ()

    GVariant *
    tp_capabilities_dup_channel_classes_variant
                                   (TpCapabilities *self);

Return the “channel-classes-variant” property

#### Parameters

self | a TpCapabilities |

#### Returns

the value of the “channel-classes-variant” property.

[transfer full]

Since: 0.19.0

### tp_capabilities_is_specific_to_contact ()

    gboolean
    tp_capabilities_is_specific_to_contact
                                   (TpCapabilities *self);

#### Parameters

self | a TpCapabilities object |

#### Returns

the same gboolean as the “contact-specific” property

Since: 0.11.3

### tp_capabilities_supports_text_chatrooms ()

    gboolean
    tp_capabilities_supports_text_chatrooms
                                   (TpCapabilities *self);

If the “contact-specific” property is `FALSE`, this function checks if named text chatrooms can be joined by providing a chatroom identifier, for instance by calling `tp_account_channel_request_new_text()` followed by `tp_account_channel_request_set_target_id()` with `TP_HANDLE_TYPE_ROOM`.

If the “contact-specific” property is `TRUE`, this function checks if the contact associated with this TpCapabilities can be invited to named text chatrooms.

If the protocol is such that chatrooms can be joined or contacts can be invited, but only via a more elaborate D-Bus API than normal (because more information is needed), then this method will return `FALSE`.

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if a channel request containing Text as ChannelType, HandleTypeRoom as TargetHandleType and a channel identifier can be expected to work, `FALSE` otherwise.

Since: 0.11.3

### tp_capabilities_supports_text_chats ()

    gboolean
    tp_capabilities_supports_text_chats (TpCapabilities *self);

Return whether private text channels can be established by providing a contact identifier, for instance by calling `tp_account_channel_request_new_text()` followed by `tp_account_channel_request_set_target_contact()`.

If the protocol is such that text chats can be established, but only via a more elaborate D-Bus API than normal (because more information is needed), then this method will return `FALSE`.

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if a channel request containing Text as ChannelType, HandleTypeContact as TargetHandleType and a contact identifier can be expected to work, `FALSE` otherwise.

Since: 0.11.3

### tp_capabilities_supports_sms ()

    gboolean
    tp_capabilities_supports_sms (TpCapabilities *self);

If the “contact-specific” property is `FALSE`, this function checks if SMS text channels can be requested with the connection associated with this TpCapabilities.

If the “contact-specific” property is `TRUE`, this function checks if the contact associated with this TpCapabilities supports SMS text channels.

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if a channel request containing Text as ChannelType, HandleTypeContact as TargetHandleType, a channel identifier and TP_PROP_CHANNEL_INTERFACE_SMS_SMS_CHANNEL set to `TRUE` can be expected to work, `FALSE` otherwise.

Since: 0.19.0

### tp_capabilities_supports_audio_call ()

    gboolean
    tp_capabilities_supports_audio_call (TpCapabilities *self,
                                         TpHandleType handle_type);

Return whether audio calls can be established, for instance by calling `tp_account_channel_request_new_audio_call()`, followed by `tp_account_channel_request_set_target_id()` with `handle_type` .

To check whether requests using `tp_account_channel_request_set_target_contact()` would work, set `handle_type` to `TP_HANDLE_TYPE_CONTACT`.

#### Parameters

self | a TpCapabilities object |
handle_type | the handle type of the call; TP_HANDLE_TYPE_CONTACT for private, TP_HANDLE_TYPE_ROOM or TP_HANDLE_TYPE_NONE for conference (depending on the protocol) |

#### Returns

`TRUE` if a channel request containing Call as ChannelType, `handle_type` as TargetHandleType, a True value for InitialAudio and an identifier of the appropriate type can be expected to work, `FALSE` otherwise.

Since: 0.17.6

### tp_capabilities_supports_audio_video_call ()

    gboolean
    tp_capabilities_supports_audio_video_call
                                   (TpCapabilities *self,
                                    TpHandleType handle_type);

Return whether audio/video calls can be established, for instance by calling `tp_account_channel_request_new_audio_video_call()`, followed by `tp_account_channel_request_set_target_id()` with `handle_type` .

To check whether requests using `tp_account_channel_request_set_target_contact()` would work, set `handle_type` to `TP_HANDLE_TYPE_CONTACT`.

#### Parameters

self | a TpCapabilities object |
handle_type | the handle type of the call; TP_HANDLE_TYPE_CONTACT for private, TP_HANDLE_TYPE_ROOM or TP_HANDLE_TYPE_NONE for conference (depending on the protocol) |

#### Returns

`TRUE` if a channel request containing Call as ChannelType, `handle_type` as TargetHandleType, a True value for InitialAudio/InitialVideo and an identifier of the appropriate type can be expected to work, `FALSE` otherwise.

Since: 0.17.6

### tp_capabilities_supports_file_transfer ()

    gboolean
    tp_capabilities_supports_file_transfer
                                   (TpCapabilities *self);

Return whether private file transfer can be established by providing a contact identifier.

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if a channel request containing FileTransfer as ChannelType, HandleTypeContact as TargetHandleType and a contact identifier can be expected to work, `FALSE` otherwise.

Since: 0.17.6

### tp_capabilities_supports_file_transfer_description ()

    gboolean
    tp_capabilities_supports_file_transfer_description
                                   (TpCapabilities *self);

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if requests as described for `tp_capabilities_supports_file_transfer()` can also specify the outgoing file's description

Since: 0.19.0

### tp_capabilities_supports_file_transfer_initial_offset ()

    gboolean
    tp_capabilities_supports_file_transfer_initial_offset
                                   (TpCapabilities *self);

Return whether an initial offset other than 0 can be specified on outgoing file transfers. This can be used to resume partial transfers, by omitting the part that has already been sent.

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if requests as described for `tp_capabilities_supports_file_transfer()` can also specify an initial offset greater than 0

Since: 0.19.0

### tp_capabilities_supports_file_transfer_timestamp ()

    gboolean
    tp_capabilities_supports_file_transfer_timestamp
                                   (TpCapabilities *self);

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if requests as described for `tp_capabilities_supports_file_transfer()` can also specify the outgoing file's timestamp

Since: 0.19.0

### tp_capabilities_supports_file_transfer_uri ()

    gboolean
    tp_capabilities_supports_file_transfer_uri
                                   (TpCapabilities *self);

#### Parameters

self | a TpCapabilities object |

#### Returns

`TRUE` if requests as described for `tp_capabilities_supports_file_transfer()` can also specify the outgoing file's URI

Since: 0.19.0

### tp_capabilities_supports_stream_tubes ()

    gboolean
    tp_capabilities_supports_stream_tubes (TpCapabilities *self,
                                           TpHandleType handle_type,
                                           const gchar *service);

If the “contact-specific” property is `TRUE`, this function checks if the contact associated with this TpCapabilities supports stream tubes with `handle_type` as TargetHandleType. If `service` is not `NULL`, it also checks if it supports stream tubes with `service` as TP_PROP_CHANNEL_TYPE_STREAM_TUBE_SERVICE.

If the “contact-specific” property is `FALSE`, this function checks if the connection supports requesting stream tube channels with `handle_type` as ChannelType. The `service` argument is unused in this case.

#### Parameters

self | a TpCapabilities object |
handle_type | the handle type of the tube (either TP_HANDLE_TYPE_CONTACT or TP_HANDLE_TYPE_ROOM) |
service | the service of the tube, or `NULL` |

#### Returns

`TRUE` if the contact or connection supports this type of stream tubes.

Since: 0.13.0

### tp_capabilities_supports_dbus_tubes ()

    gboolean
    tp_capabilities_supports_dbus_tubes (TpCapabilities *self,
                                         TpHandleType handle_type,
                                         const gchar *service_name);

If the “contact-specific” property is `TRUE`, this function checks if the contact associated with this TpCapabilities supports D-Bus tubes with `handle_type` as TargetHandleType. If `service_name` is not `NULL`, it also checks if it supports stream tubes with `service` as TP_PROP_CHANNEL_TYPE_DBUS_TUBE_SERVICE_NAME.

If the “contact-specific” property is `FALSE`, this function checks if the connection supports requesting D-Bus tube channels with `handle_type` as ChannelType. The `service_name` argument is unused in this case.

#### Parameters

self | a TpCapabilities object |
handle_type | the handle type of the tube (either TP_HANDLE_TYPE_CONTACT or TP_HANDLE_TYPE_ROOM) |
service_name | the service name of the tube, or `NULL` |

#### Returns

`TRUE` if the contact or connection supports this type of D-Bus tubes.

Since: 0.13.0

### tp_capabilities_supports_contact_search ()

    gboolean
    tp_capabilities_supports_contact_search
                                   (TpCapabilities *self,
                                    gboolean *with_limit,
                                    gboolean *with_server);

Return whether this protocol or connection can perform contact searches. Optionally, also return whether a limited number of results can be specified, and whether alternative servers can be searched.

#### Parameters

self | a TpCapabilities object |
with_limit | if not `NULL`, used to return `TRUE` if the limit parameter to `tp_contact_search_new_async()` and `tp_contact_search_reset_async()` can be nonzero. | [out]
with_server | if not `NULL`, used to return `TRUE` if the server parameter to `tp_contact_search_new_async()` and `tp_contact_search_reset_async()` can be non-`NULL`. | [out]

#### Returns

`TRUE` if TpContactSearch can be used.

Since: 0.13.11

### tp_capabilities_supports_room_list ()

    gboolean
    tp_capabilities_supports_room_list (TpCapabilities *self,
                                        gboolean *with_server);

Discovers whether this protocol or connection supports listing rooms. Specifically, if this function returns `TRUE`, a room list channel can be requested as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    GHashTable *request;
    TpAccountChannelRequest *req;

    request = tp_asv_new (
        TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING,
          TP_IFACE_CHANNEL_TYPE_ROOM_LIST,
        TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_NONE,
        NULL);

    req = tp_account_channel_request_new (account, request,
       TP_USER_ACTION_TIME_CURRENT_TIME);

    tp_account_channel_request_create_and_handle_channel_async (req, NULL,
        create_channel_cb, NULL);

    g_object_unref (req);
    g_hash_table_unref (request);

If `with_server` is set to `TRUE`, a list of rooms on a particular server can be requested as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    /\* Same code as above but with request defined using: *\/
    request = tp_asv_new (
        TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING,
          TP_IFACE_CHANNEL_TYPE_ROOM_LIST,
        TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_NONE,
        TP_PROP_CHANNEL_TYPE_ROOM_LIST_SERVER, G_TYPE_STRING,
          "characters.shakespeare.lit",
        NULL);

#### Parameters

self | a TpCapabilities object |
with_server | if not `NULL`, used to return `TRUE` if the TP_PROP_CHANNEL_TYPE_ROOM_LIST_SERVER property can be defined when requesting a RoomList channel. | [out]

#### Returns

`TRUE` if a channel request containing RoomList as ChannelType, HandleTypeNone as TargetHandleType can be expected to work, `FALSE` otherwise.

Since: 0.13.14

## Types and Values

### TpCapabilities

    typedef struct _TpCapabilities TpCapabilities;

An object representing capabilities a TpConnection or TpContact supports.

Since: 0.11.3

## Property Details

### The `“channel-classes”` property

      “channel-classes”          GPtrArray_GValueArray_GHashTable_gchararray+GValue_+GStrv__*

The underlying data structure used by Telepathy to represent the requests that can succeed.

This can be used by advanced clients to determine whether an unusually complex request would succeed. See the Telepathy D-Bus API Specification for details of how to interpret the returned GPtrArray of TP_STRUCT_TYPE_REQUESTABLE_CHANNEL_CLASS.

The higher-level methods like `tp_capabilities_supports_text_chats()` are likely to be more useful to the majority of clients.

Owner: TpCapabilities

Flags: Read / Write / Construct Only

### The `“channel-classes-variant”` property

      “channel-classes-variant”  GVariant *

The underlying data structure used by Telepathy to represent the requests that can succeed.

This can be used by advanced clients to determine whether an unusually complex request would succeed. See the Telepathy D-Bus API Specification for details of how to interpret the returned GVariant of type a(a{sv}as).

The higher-level methods like `tp_capabilities_supports_text_chats()` are likely to be more useful to the majority of clients.

Owner: TpCapabilities

Flags: Read

Allowed values: GVariant<a(a{sv}as)>

Default value: NULL

Since: 0.19.0

### The `“contact-specific”` property

      “contact-specific”         gboolean

Whether this object accurately describes the capabilities of a particular contact, or if it's only a guess based on the capabilities of the underlying connection.

Owner: TpCapabilities

Flags: Read / Write / Construct Only

Default value: FALSE