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.

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;
  // ...
}

Since 0.11.14

TpBaseChannelGetPathFunc ()

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

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

Since 0.11.14

TpBaseChannelGetInterfacesFunc ()

GPtrArray *
(*TpBaseChannelGetInterfacesFunc) (TpBaseChannel *chan);

Signature of an implementation of TpBaseChannelClass.get_interfaces virtual function.

Implementation must first chainup on parent class implementation and then add extra interfaces into the GPtrArray.

1
2
3
4
5
6
7
8
9
10
11

static GPtrArray *
my_channel_get_interfaces (TpBaseChannel *self)
{
  GPtrArray *interfaces;

  interfaces = TP_BASE_CHANNEL_CLASS (my_channel_parent_class)->get_interfaces (self);

  g_ptr_array_add (interfaces, TP_IFACE_BADGERS);

  return interfaces;
}

Since 0.17.5

TpBaseChannelFunc ()

void
(*TpBaseChannelFunc) (TpBaseChannel *channel,
                      gpointer user_data);

A callback for functions which act on base channels.

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.

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.

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.

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.

Calling this method is the same as calling tp_base_channel_reopened_with_requested() with a requested value of FALSE.

Since 0.11.14

tp_base_channel_disappear ()

void
tp_base_channel_disappear (TpBaseChannel *chan);

Called by subclasses to indicate that this channel is closing and should be unregistered from the bus, but the actual object shouldn't be destroyed. The "Closed" signal will be emitted, the “channel-destroyed” property will not be set, and the channel will be unregistered from the bus.

Since 0.19.7

tp_base_channel_reopened_with_requested ()

void
tp_base_channel_reopened_with_requested
                               (TpBaseChannel *chan,
                                gboolean requested,
                                TpHandle initiator);

Called by subclasses to indicate that this channel was closed but was re-opened, either due to pending messages or from having disappeared (with tp_base_channel_disappear()). 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 requested .

Since 0.19.7

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.

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.

Since 0.11.14

tp_base_channel_get_self_handle ()

TpHandle
tp_base_channel_get_self_handle (TpBaseChannel *chan);

If chan has a TpGroupMixin, returns the value of group's self handle. Otherwise return the value of “self-handle”.

Since 0.17.5

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_entity_type is TP_ENTITY_TYPE_NONE for this class, and non-zero otherwise. This is a shortcut for retrieving the “handle” property.

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.

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.

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.

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

Since 0.11.14

tp_base_channel_is_respawning ()

gboolean
tp_base_channel_is_respawning (TpBaseChannel *chan);

Returns TRUE if the channel has been reopened, either by a subclass calling tp_base_channel_reopened() or tp_base_channel_reopened_with_requested(). This is useful for "closed" handlers to distinguish between channels really closing and channels that have been reopened due to pending messages.

Since 0.19.7

struct TpBaseChannel

struct TpBaseChannel;

A base class for channel implementations

Since 0.11.14

struct TpBaseChannelClass

struct TpBaseChannelClass {
  const gchar *channel_type;
  TpEntityType target_entity_type;

  TpBaseChannelCloseFunc close;
  TpBaseChannelFillPropertiesFunc fill_immutable_properties;
  TpBaseChannelGetPathFunc get_object_path_suffix;
  TpBaseChannelGetInterfacesFunc get_interfaces;
};

The class structure for TpBaseChannel

Since 0.11.14

The “channel-destroyed” property

  “channel-destroyed”        gboolean

If true, the closed signal on the Channel interface indicates that the channel can go away.

If false, the closed signal indicates to the channel manager that the channel should appear to go away and be re-created, by emitting Closed followed by NewChannel. (This is to support the "respawning" of Text channels which are closed with unacknowledged messages.)

Flags: Read

Default value: FALSE

The “channel-properties” property

  “channel-properties”       GVariant *

The D-Bus properties to be announced in the NewChannels signal and in the Channels property, as a map from interface.name.propertyname to variant.

A channel's immutable properties are constant for its lifetime on the bus, so this property should only change when the closed signal is emitted (so that respawned channels can reappear on the bus with different properties). All of the D-Bus properties mentioned here should be exposed through the D-Bus properties interface; additional (possibly mutable) properties not included here may also be exposed via the D-Bus properties interface.

If the channel implementation uses

this property can implemented using tp_dbus_properties_mixin_make_properties_hash() as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

case PROP_CHANNEL_PROPERTIES:
  {
    GHashTable *hash = tp_dbus_properties_mixin_make_properties_hash (object,
        // The spec says these properties MUST be included:
        TP_IFACE_CHANNEL, "TargetHandle",
        TP_IFACE_CHANNEL, "TargetEntityType",
        TP_IFACE_CHANNEL, "ChannelType",
        TP_IFACE_CHANNEL, "TargetID",
        TP_IFACE_CHANNEL, "Requested",
        TP_IFACE_CHANNEL, "InitiatorHandle",
        TP_IFACE_CHANNEL, "InitiatorID",
        TP_IFACE_CHANNEL, "Interfaces",
        // Perhaps your channel has some other immutable properties:
        TP_IFACE_CHANNEL_INTERFACE_MESSAGES, "SupportedContentTypes",
        // etc.
        NULL));

    g_value_set_variant (value, tp_asv_to_vardict (hash));
    g_hash_table_unref (hash);
  }
  break;

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

The “channel-type” property

  “channel-type”             gchar *

The D-Bus interface representing the type of this channel. Read-only except during construction.

In connection manager implementations, attempts to set this property during construction will usually be ignored or treated as an error.

Flags: Read / Write / Construct Only

Default value: NULL

The “connection” property

  “connection”               TpBaseConnection *

Connection object that owns this channel.

Flags: Read / Write / Construct Only

The “entity-type” property

  “entity-type”              guint

The TpEntityType of this channel's associated handle, or TP_ENTITY_TYPE_NONE (which is numerically 0) if no handle.

In connection manager implementations, attempts to set this during construction might be ignored.

Flags: Read / Write / Construct Only

Default value: 4294967295

The “handle” property

  “handle”                   guint

This channel's associated handle, or 0 if no handle or unknown. Read-only except during construction.

In connection manager implementations, attempts to set this during construction might be ignored, depending on the channel type.

Flags: Read / Write / Construct Only

Default value: 0

The “initiator-handle” property

  “initiator-handle”         guint

The contact who initiated the channel.

Flags: Read / Write / Construct Only

Default value: 0

The “initiator-id” property

  “initiator-id”             gchar *

The string obtained by inspecting the initiator-handle.

Flags: Read

Default value: NULL

The “interfaces” property

  “interfaces”               GStrv

Additional Channel.Interface.* interfaces.

Flags: Read

The “object-path” property

  “object-path”              gchar *

The D-Bus object path used for this object on the bus. Read-only except during construction.

Flags: Read / Write / Construct Only

Default value: NULL

The “requested” property

  “requested”                gboolean

True if this channel was requested by the local user.

Flags: Read / Write / Construct Only

Default value: FALSE

The “target-id” property

  “target-id”                gchar *

The string obtained by inspecting the target handle.

Flags: Read

Default value: NULL