TpDBusTubeChannel: telepathy-glib API Reference Manual

## TpDBusTubeChannel TpDBusTubeChannel — proxy object for D-Bus tube channels |

## Functions

GHashTable * | tp_dbus_tube_channel_get_parameters ()
GVariant * | tp_dbus_tube_channel_dup_parameters_vardict ()
const gchar * | tp_dbus_tube_channel_get_service_name ()
void | tp_dbus_tube_channel_offer_async ()
GDBusConnection * | tp_dbus_tube_channel_offer_finish ()
void | tp_dbus_tube_channel_accept_async ()
GDBusConnection * | tp_dbus_tube_channel_accept_finish ()

## Properties

GHashTable_gchararray+GValue_* | parameters | Read
GVariant * | parameters-vardict | Read
gchar * | service-name | Read

## Types and Values

struct | TpDBusTubeChannel
struct | TpDBusTubeChannelClass
#define | TP_DBUS_TUBE_CHANNEL_FEATURE_CORE

## Object Hierarchy

        GObject
        ╰── TpProxy
            ╰── TpChannel
                ╰── TpDBusTubeChannel

## Implemented Interfaces

TpDBusTubeChannel implements TpChannelIface.

## Includes

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

## Description

TpDBusTubeChannel provides API for working with D-Bus tube channels, which allow applications to open D-Bus connections to a contact or chat room.

To create a new outgoing D-Bus tube channel, do something like:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    GHashTable *request_properties = tp_asv_new (
        TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_DBUS_TUBE,
        TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_CONTACT,
        TP_PROP_CHANNEL_TARGET_ID, G_TYPE_STRING, tp_contact_get_identifier (contact),
        TP_PROP_CHANNEL_TYPE_DBUS_TUBE_SERVICE_NAME, G_TYPE_STRING, "com.example.walrus",
        NULL);
    TpAccountChannelRequest *req = tp_account_channel_request_new (account,
        request_properties, TP_USER_ACTION_TIME_NOT_USER_ACTION);
    tp_account_channel_request_create_and_handle_channel_async (req, NULL, callback, NULL);

    // ...

    static void
    callback (
        GObject *source,
        GAsyncResult *result,
        gpointer user_data)
    {
      TpAccountChannelRequest *req = TP_ACCOUNT_CHANNEL_REQUEST (source);
      TpChannel *channel;
      GError *error = NULL;

      channel = tp_account_channel_request_create_and_handle_channel_finish (req, result, &error);
      tp_dbus_tube_channel_offer_async (TP_DBUS_TUBE_CHANNEL (channel), NULL, offer_callback, NULL);
    }

You can find a fuller example in the examples/client/dbus-tubes directory.

## Functions

### tp_dbus_tube_channel_get_parameters ()

    GHashTable *
    tp_dbus_tube_channel_get_parameters (TpDBusTubeChannel *self);

Return the “parameters” property

[skip]

#### Parameters

self | a TpDBusTubeChannel |

#### Returns

the value of “parameters”.

[transfer none][element-type utf8 GObject.Value]

Since: 0.18.0

### tp_dbus_tube_channel_dup_parameters_vardict ()

    GVariant *
    tp_dbus_tube_channel_dup_parameters_vardict
                                   (TpDBusTubeChannel *self);

Return the parameters of the dbus-tube channel in a variant of type `G_VARIANT_TYPE_VARDICT` whose keys are strings representing parameter names and values are variants representing corresponding parameter values set by the offerer when offering this channel.

The GVariant returned is `NULL` if this is an outgoing tube that has not yet been offered or the parameters property has not been set.

Use `g_variant_lookup()`, `g_variant_lookup_value()`, or `tp_vardict_get_uint32()` and similar functions for convenient access to the values.

#### Parameters

self | a TpDBusTubeChannel |

#### Returns

a new reference to a GVariant.

[transfer full]

Since: 0.19.10

### tp_dbus_tube_channel_get_service_name ()

    const gchar *
    tp_dbus_tube_channel_get_service_name (TpDBusTubeChannel *self);

Return the “service-name” property

#### Parameters

self | a TpDBusTubeChannel |

#### Returns

the value of “service-name”.

[transfer none]

Since: 0.18.0

### tp_dbus_tube_channel_offer_async ()

    void
    tp_dbus_tube_channel_offer_async (TpDBusTubeChannel *self,
                                      GHashTable *params,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Offer an outgoing D-Bus tube. When the tube has been offered and accepted `callback` will be called. You can then call `tp_dbus_tube_channel_offer_finish()` to get the GDBusConnection that will be used to communicate through the tube.

#### Parameters

self | an outgoing TpDBusTubeChannel |
params | parameters of the tube, or `NULL`. | [allow-none][transfer none]
callback | a callback to call when the tube has been offered |
user_data | data to pass to `callback` |

Since: 0.18.0

### tp_dbus_tube_channel_offer_finish ()

    GDBusConnection *
    tp_dbus_tube_channel_offer_finish (TpDBusTubeChannel *self,
                                       GAsyncResult *result,
                                       GError **error);

Finishes offering an outgoing D-Bus tube. The returned GDBusConnection is ready to be used to exchange data through the tube.

#### Parameters

self | a TpDBusTubeChannel |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

a reference on a GDBusConnection if the tube has been successfully offered and opened; `NULL` otherwise.

[transfer full]

Since: 0.18.0

### tp_dbus_tube_channel_accept_async ()

    void
    tp_dbus_tube_channel_accept_async (TpDBusTubeChannel *self,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Accept an incoming D-Bus tube. When the tube has been accepted `callback` will be called. You can then call `tp_dbus_tube_channel_accept_finish()` to get the GDBusConnection that will be used to communicate through the tube.

#### Parameters

self | an incoming TpDBusTubeChannel |
callback | a callback to call when the tube has been offered |
user_data | data to pass to `callback` |

Since: 0.18.0

### tp_dbus_tube_channel_accept_finish ()

    GDBusConnection *
    tp_dbus_tube_channel_accept_finish (TpDBusTubeChannel *self,
                                        GAsyncResult *result,
                                        GError **error);

Finishes to accept an incoming D-Bus tube. The returned GDBusConnection is ready to be used to exchange data through the tube.

#### Parameters

self | a TpDBusTubeChannel |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

a reference on a GDBusConnection if the tube has been successfully accepted and opened; `NULL` otherwise.

[transfer full]

Since: 0.18.0

## Types and Values

### struct TpDBusTubeChannel

    struct TpDBusTubeChannel;

Data structure representing a TpDBusTubeChannel.

Since: 0.18.0

### struct TpDBusTubeChannelClass

    struct TpDBusTubeChannelClass {
    };

The class of a TpDBusTubeChannel.

Since: 0.18.0

### TP_DBUS_TUBE_CHANNEL_FEATURE_CORE

    #define             TP_DBUS_TUBE_CHANNEL_FEATURE_CORE

Expands to a call to a function that returns a quark representing the core feature of a TpDBusTubeChannel.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since: 0.18.0

## Property Details

### The `“parameters”` property

      “parameters”               GHashTable_gchararray+GValue_*

A string to GValue GHashTable representing the parameters of the tube.

Will be `NULL` for outgoing tubes until the tube has been offered.

In high-level language bindings, use `tp_dbus_tube_channel_dup_parameters_vardict()` to get the same information in a more convenient format.

Owner: TpDBusTubeChannel

Flags: Read

Since: 0.18.0

### The `“parameters-vardict”` property

      “parameters-vardict”       GVariant *

A `G_VARIANT_TYPE_VARDICT` representing the parameters of the tube.

Will be `NULL` for outgoing tubes until the tube has been offered.

Owner: TpDBusTubeChannel

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

Since: 0.19.10

### The `“service-name”` property

      “service-name”             gchar *

A string representing the service name that will be used over the tube.

Owner: TpDBusTubeChannel

Flags: Read

Default value: NULL

Since: 0.18.0