## TpBaseChannel

TpBaseChannel — base class for TpExportableChannel implementations

## Synopsis

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

                        TpBaseChannel;
                        TpBaseChannelClass;
    void                (*TpBaseChannelFillPropertiesFunc)  (TpBaseChannel *chan,
                                                             GHashTable *properties);
    void                (*TpBaseChannelCloseFunc)           (TpBaseChannel *chan);
    gchar *             (*TpBaseChannelGetPathFunc)         (TpBaseChannel *chan);
    void                tp_base_channel_register            (TpBaseChannel *chan);
    void                tp_base_channel_close               (TpBaseChannel *chan);
    void                tp_base_channel_destroyed           (TpBaseChannel *chan);
    void                tp_base_channel_reopened            (TpBaseChannel *chan,
                                                             TpHandle initiator);
    const gchar *       tp_base_channel_get_object_path     (TpBaseChannel *chan);
    TpBaseConnection *  tp_base_channel_get_connection      (TpBaseChannel *chan);
    TpHandle            tp_base_channel_get_target_handle   (TpBaseChannel *chan);
    TpHandle            tp_base_channel_get_initiator       (TpBaseChannel *chan);
    gboolean            tp_base_channel_is_requested        (TpBaseChannel *chan);
    gboolean            tp_base_channel_is_registered       (TpBaseChannel *chan);
    gboolean            tp_base_channel_is_destroyed        (TpBaseChannel *chan);

## Object Hierarchy

      GObject
       +----TpBaseChannel

## Implemented Interfaces

TpBaseChannel implements TpSvcDBusProperties, TpSvcChannel, TpChannelIface and TpExportableChannel.

## Properties

      "connection"               TpBaseConnection*     : Read / Write / Construct Only
      "initiator-handle"         guint                 : Read / Write / Construct Only
      "initiator-id"             gchar*                : Read
      "interfaces"               GStrv*                : Read
      "requested"                gboolean              : Read / Write / Construct Only
      "target-id"                gchar*                : Read

## Description

This base class makes it easier to write TpExportableChannel implementations by implementing some of its properties, and defining other relevant properties.

Subclasses should fill in TpBaseChannelClass.channel_type, TpBaseChannelClass.target_handle_type and TpBaseChannelClass.interfaces, and implement the TpBaseChannelClass.close virtual function.

If the channel type and/or interfaces being implemented define immutable D-Bus properties besides those on the Channel interface, the subclass should implement the TpBaseChannelClass.fill_immutable_properties virtual function.

If the "object-path" property is not set at construct time, the TpBaseChannelClass.get_object_path_suffix virtual function will be called to determine the channel's path, whose default implementation simply generates a unique path based on the object's address in memory.

## Details

### TpBaseChannel

    typedef struct _TpBaseChannel TpBaseChannel;

A base class for channel implementations

Since 0.11.14

### TpBaseChannelClass

    typedef struct {
      TpDBusPropertiesMixinClass dbus_props_class;

      const gchar *channel_type;
      TpHandleType target_handle_type;
      const gchar **interfaces;

      TpBaseChannelCloseFunc close;
      TpBaseChannelFillPropertiesFunc fill_immutable_properties;
      TpBaseChannelGetPathFunc get_object_path_suffix;
    } TpBaseChannelClass;

The class structure for TpBaseChannel

TpDBusPropertiesMixinClass `dbus_props_class`; | The class structure for the DBus properties mixin
const gchar *`channel_type`; | The type of channel that instances of this class represent (e.g. TP_IFACE_CHANNEL_TYPE_TEXT)
TpHandleType `target_handle_type`; | The type of handle that is the target of channels of this type
const gchar **`interfaces`; | Extra interfaces provided by this channel (this SHOULD NOT include the channel type and interface itself)
TpBaseChannelCloseFunc `close`; | A virtual function called to close the channel, which will be called by `tp_base_channel_close()` and by the implementation of the Closed D-Bus method.
TpBaseChannelFillPropertiesFunc `fill_immutable_properties`; | A virtual function called to add custom properties to the DBus properties hash. Implementations must chain up to the parent class implementation and call `tp_dbus_properties_mixin_fill_properties_hash()` on the supplied hash table

TpBaseChannelGetPathFunc `get_object_path_suffix`;

Returns a string that will be appended to the Connection objects's object path to get the Channel's object path. This function will only be called as a fallback if the "object-path" property is not set. The default implementation simply generates a unique path based on the object's address in memory. The returned string will be freed automatically.

Since 0.11.14

### TpBaseChannelFillPropertiesFunc ()

    void                (*TpBaseChannelFillPropertiesFunc)  (TpBaseChannel *chan,
                                                             GHashTable *properties);

Signature of an implementation of the TpBaseChannelClass.fill_immutable_properties virtual function. A typical implementation, for a channel implementing TpSvcChannelTypeContactSearch, would be:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16

    static void
    my_search_channel_fill_properties (
        TpBaseChannel *chan,
        GHashTable *properties)
    {
      TpBaseChannelClass *klass = TP_BASE_CHANNEL_CLASS (my_search_channel_parent_class);

      klass->fill_immutable_properties (chan, properties);

      tp_dbus_properties_mixin_fill_properties_hash (
          G_OBJECT (chan), properties,
          TP_IFACE_CHANNEL_TYPE_CONTACT_SEARCH, "Limit",
          TP_IFACE_CHANNEL_TYPE_CONTACT_SEARCH, "AvailableSearchKeys",
          TP_IFACE_CHANNEL_TYPE_CONTACT_SEARCH, "Server",
          NULL);
    }

Note that the SearchState property is not added to `properties`, since only immutable properties (whose value cannot change over the lifetime of `chan`) should be included.

`chan` : | a channel
`properties` : | a dictionary of `chan`'s immutable properties, which the implementation may add to using `tp_dbus_properties_mixin_fill_properties_hash()`

Since 0.11.14

### TpBaseChannelCloseFunc ()

    void                (*TpBaseChannelCloseFunc)           (TpBaseChannel *chan);

Signature of an implementation of the TpBaseChannelClass.close virtual function. Implementations should eventually call either `tp_base_channel_destroyed()` if the channel is really closed as a result, or `tp_base_channel_reopened()` if the channel will be re-spawned (for instance, due to unacknowledged messages on a text channel), but need not do so before returning. Note that channels that support re-spawning must also implement TpSvcChannelInterfaceDestroyable.

Implementations may assume that `tp_base_channel_is_destroyed()` is FALSE for `chan` when called. Note that if this function is implemented asynchronously, it may be called more than once. A subclass which needs to perform some asynchronous clean-up in order to close might implement this function as follows:

    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
    26
    27
    28

    static void
    my_channel_close (TpBaseChannel *chan)
    {
      MyChannel *self = MY_CHANNEL (chan);

      if (self->priv->closing)
        return;

      self->priv->closing = TRUE;

      // some hypothetical channel-specific clean-up function:
      clean_up (self, cleaned_up_cb);
    }

    static void
    cleaned_up_cb (MyChannel *self)
    {
      // all done, we can finish closing now
      tp_base_channel_destroyed (TP_BASE_CHANNEL (self));
    }
    static void
    my_channel_class_init (MyChannelClass *klass)
    {
      TpBaseChannelClass *base_channel_class = TP_BASE_CHANNEL_CLASS (klass);

      klass->close = my_channel_close;
      // ...
    }

If a subclass does not need to do anything to clean itself up, it may implement TpBaseChannelClass.close using `tp_base_channel_destroyed()` directly:

    1
    2
    3
    4
    5
    6
    7
    8

    static void
    my_channel_class_init (MyChannelClass *klass)
    {
      TpBaseChannelClass *base_channel_class = TP_BASE_CHANNEL_CLASS (klass);

      klass->close = tp_base_channel_destroyed;
      // ...
    }

`chan` : | a channel

Since 0.11.14

### TpBaseChannelGetPathFunc ()

    gchar *             (*TpBaseChannelGetPathFunc)         (TpBaseChannel *chan);

Signature of an implementation of the TpBaseChannelClass.get_object_path_suffix virtual function.

`chan` : | a channel
Returns : | a string that will be appended to the Connection objects's object path to get the Channel's object path. [transfer full]

Since 0.11.14

### tp_base_channel_register ()

    void                tp_base_channel_register            (TpBaseChannel *chan);

Make the channel appear on the bus. "object-path" must have been set to a valid path, which must not already be in use as another object's path.

`chan` : | a channel

Since 0.11.14

### tp_base_channel_close ()

    void                tp_base_channel_close               (TpBaseChannel *chan);

Asks `chan` to close, just as if the Close D-Bus method had been called. If "channel-destroyed" is TRUE, this is a no-op.

Note that, depending on the subclass's implementation of TpBaseChannelClass.close and internal behaviour, this may or may not be a suitable method to use during connection teardown. For instance, if the channel may respawn when Close is called, an equivalent of the Destroy D-Bus method would be more appropriate during teardown, since the intention is to forcibly terminate all channels.

`chan` : | a channel

Since 0.11.14

### tp_base_channel_destroyed ()

    void                tp_base_channel_destroyed           (TpBaseChannel *chan);

Called by subclasses to indicate that this channel was destroyed and can be removed from the bus. The "Closed" signal will be emitted and the "channel-destroyed" property will be set.

`chan` : | a channel

Since 0.11.14

### tp_base_channel_reopened ()

    void                tp_base_channel_reopened            (TpBaseChannel *chan,
                                                             TpHandle initiator);

Called by subclasses to indicate that this channel was closed but was re-opened due to pending messages. The "Closed" signal will be emitted, but the "channel-destroyed" property will not be set. The channel's "initiator-handle" property will be set to `initiator`, and the "requested" property will be set to FALSE.

`chan` : | a channel
`initiator` : | the handle of the contact that re-opened the channel

Since 0.11.14

### tp_base_channel_get_object_path ()

    const gchar *       tp_base_channel_get_object_path     (TpBaseChannel *chan);

Returns `chan`'s object path, as a shortcut for retrieving the "object-path" property.

`chan` : | a channel
Returns : | `chan`'s object path. [transfer none]

Since 0.11.14

### tp_base_channel_get_connection ()

    TpBaseConnection *  tp_base_channel_get_connection      (TpBaseChannel *chan);

Returns the connection to which `chan` is attached, as a shortcut for retrieving the "connection" property.

`chan` : | a channel
Returns : | the connection to which `chan` is attached. [transfer none]

Since 0.11.14

### tp_base_channel_get_target_handle ()

    TpHandle            tp_base_channel_get_target_handle   (TpBaseChannel *chan);

Returns the target handle of `chan` (without a reference), which will be 0 if TpBaseChannelClass.target_handle_type is TP_HANDLE_TYPE_NONE for this class, and non-zero otherwise. This is a shortcut for retrieving the "handle" property. The reference count of the handle is not increased; you should use `tp_handle_ref()` if you want to keep a hold of it.

`chan` : | a channel
Returns : | the target handle of `chan`

Since 0.11.14

### tp_base_channel_get_initiator ()

    TpHandle            tp_base_channel_get_initiator       (TpBaseChannel *chan);

Returns the initiator handle of `chan`, as a shortcut for retrieving the "initiator-handle" property. The reference count of the handle is not increased; you should use `tp_handle_ref()` if you want to keep a hold of it.

`chan` : | a channel
Returns : | the initiator handle of `chan`

Since 0.11.14

### tp_base_channel_is_requested ()

    gboolean            tp_base_channel_is_requested        (TpBaseChannel *chan);

Returns whether or not `chan` was requested, as a shortcut for retrieving the "requested" property.

`chan` : | a channel
Returns : | whether or not `chan` was requested.

Since 0.11.14

### tp_base_channel_is_registered ()

    gboolean            tp_base_channel_is_registered       (TpBaseChannel *chan);

Returns whether or not `chan` is visible on the bus; that is, whether `tp_base_channel_register()` has been called and `tp_base_channel_destroyed()` has not been called.

`chan` : | a channel
Returns : | TRUE if `chan` is visible on the bus

Since 0.11.14

### tp_base_channel_is_destroyed ()

    gboolean            tp_base_channel_is_destroyed        (TpBaseChannel *chan);

Returns the value of the "channel-destroyed" property, which is TRUE if `tp_base_channel_destroyed()` has been called (and thus the channel has been removed from the bus).

`chan` : | a channel
Returns : | TRUE if `tp_base_channel_destroyed()` has been called.

Since 0.11.14

## Property Details

### The `"connection"` property

      "connection"               TpBaseConnection*     : Read / Write / Construct Only

Connection object that owns this channel.

### The `"initiator-handle"` property

      "initiator-handle"         guint                 : Read / Write / Construct Only

The contact who initiated the channel.

Default value: 0

### The `"initiator-id"` property

      "initiator-id"             gchar*                : Read

The string obtained by inspecting the initiator-handle.

Default value: NULL

### The `"interfaces"` property

      "interfaces"               GStrv*                : Read

Additional Channel.Interface.* interfaces.

### The `"requested"` property

      "requested"                gboolean              : Read / Write / Construct Only

True if this channel was requested by the local user.

Default value: FALSE

### The `"target-id"` property

      "target-id"                gchar*                : Read

The string obtained by inspecting the target handle.

Default value: NULL

## See Also

TpSvcChannel