## TpDBusTubeChannel

TpDBusTubeChannel — proxy object for D-Bus tube channels

## Synopsis

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

    struct              TpDBusTubeChannel;
    struct              TpDBusTubeChannelClass;
    #define             TP_DBUS_TUBE_CHANNEL_FEATURE_CORE
    GHashTable *        tp_dbus_tube_channel_get_parameters (TpDBusTubeChannel *self);
    GVariant *          tp_dbus_tube_channel_dup_parameters_vardict
                                                            (TpDBusTubeChannel *self);
    const gchar *       tp_dbus_tube_channel_get_service_name
                                                            (TpDBusTubeChannel *self);
    void                tp_dbus_tube_channel_offer_async    (TpDBusTubeChannel *self,
                                                             GHashTable *params,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDBusConnection *   tp_dbus_tube_channel_offer_finish   (TpDBusTubeChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_dbus_tube_channel_accept_async   (TpDBusTubeChannel *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDBusConnection *   tp_dbus_tube_channel_accept_finish  (TpDBusTubeChannel *self,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpChannel
                   +----TpDBusTubeChannel

## Implemented Interfaces

TpDBusTubeChannel implements TpChannelIface.

## Properties

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

## 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.

## Details

### 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

### tp_dbus_tube_channel_get_parameters ()

    GHashTable *        tp_dbus_tube_channel_get_parameters (TpDBusTubeChannel *self);

Return the "parameters" property

`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.

`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

`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.

`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.

`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.

`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.

`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

## Property Details

### The `"parameters"` property

      "parameters"               GHashTable_gchararray+GValue_*  : Read

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.

Since 0.18.0

### The `"parameters-vardict"` property

      "parameters-vardict"       GVariant*             : Read

A `G_VARIANT_TYPE_VARDICT` representing the parameters of the tube.

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

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.10

### The `"service-name"` property

      "service-name"             gchar*                : Read

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

Default value: NULL

Since 0.18.0