Class DBusTubeChannel

Whenever the source_property is changed the target_property is updated using the same value. For instance:

  g_object_bind_property (action, "active", widget, "sensitive", 0);

Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance.

If flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: if target_property on target changes then the source_property on source will be updated as well.

The binding will automatically be removed when either the source or the target instances are finalized. To remove the binding without affecting the source and the target you can just call g_object_unref() on the returned #GBinding instance.

Removing the binding by calling g_object_unref() on it must only be done if the binding, source and target are only used from a single thread and it is clear that both source and target outlive the binding. Especially it is not safe to rely on this if the binding, source or target can be finalized from different threads. Keep another reference to the binding and use g_binding_unbind() instead to be on the safe side.

A #GObject can have multiple bindings.

This function is the language bindings friendly version of g_object_bind_property_full(), using #GClosures instead of function pointers.

The returned hash table should not be altered, and is not necessarily valid after the main loop is next re-entered. Copy it with g_boxed_copy() (its type is %TP_HASH_TYPE_QUALIFIED_PROPERTY_VALUE_MAP) if a copy that remains valid must be kept.

If the #TpChannel:channel-properties property was not set during construction (e.g. by calling tp_channel_new_from_properties()), a reasonable but possibly incomplete version will be made up from the values of individual properties; reading this property repeatedly may yield progressively more complete values until the %TP_CHANNEL_FEATURE_CORE feature is prepared.

When the channel has been closed, callback will be called. You can then call tp_channel_close_finish() to get the result of the operation.

When the channel has been destroyed or closed, callback will be called. You can then call tp_channel_destroy_finish() to get the result of the operation.

If the #TpChannel:channel-properties property was not set during construction (e.g. by calling tp_channel_new_from_properties()), a reasonable but possibly incomplete version will be made up from the values of individual properties; reading this property repeatedly may yield progressively more complete values until the %TP_CHANNEL_FEATURE_CORE feature is prepared.

This function should be used only by #TpChannel subclasses, otherwise it is recommended to use individual property getters instead.

This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

This is the same as the #TpChannelIface:channel-type property; it isn't guaranteed to be non-%NULL until the %TP_CHANNEL_FEATURE_CORE feature has been prepared.

This is the same as the #TpChannelIface:channel-type property, except that it is a GQuark rather than a string. It isn't guaranteed to be nonzero until the %TP_CHANNEL_FEATURE_CORE property is ready.

This is the same as the #TpChannelIface:handle property. It isn't guaranteed to have its final value until the %TP_CHANNEL_FEATURE_CORE feature is ready.

If handle_type is not %NULL, the type of handle is written into it. This will be %TP_UNKNOWN_HANDLE_TYPE if the handle has not yet been discovered, or %TP_HANDLE_TYPE_NONE if there is no handle with which this channel will always communicate. This is the same as the #TpChannelIface:handle-type property.

This is the same as the #TpChannel:identifier property, and isn't guaranteed to be set until the %TP_CHANNEL_FEATURE_CORE property is ready.

Changed in 0.11.4: as with #TpChannel:identifier, this could previously either be %NULL or the empty string if there was no suitable value. It is now non-%NULL in all cases.

The value can be:

• an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60)
• a #GValue initialized with the expected type of the property
• a #GValue initialized with a type to which the expected type of the property can be transformed

In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset().

Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.

If self is a group but %TP_CHANNEL_FEATURE_CONTACTS has not been prepared, the result may either be a set of local-pending members, or %NULL.

If self is not a group, return %NULL.

If self is a group but %TP_CHANNEL_FEATURE_CONTACTS has not been prepared, the result may either be a set of members, or %NULL.

If self is not a group, return %NULL.

If self is a group but %TP_CHANNEL_FEATURE_CONTACTS has not been prepared, the result may either be a set of remote-pending members, or %NULL.

If self is not a group, return %NULL.

• if self is not a group or contact is not a member of this channel, result is undefined;
• if %TP_CHANNEL_FEATURE_CONTACTS has not yet been prepared, result is undefined;
• if self does not have flags that include %TP_CHANNEL_GROUP_FLAG_PROPERTIES, result is undefined;
• if contact is channel-specific and its globally valid "owner" is known, return that owner;
• if contact is channel-specific and its globally valid "owner" is unknown, return %NULL;
• if contact is globally valid, return contact itself

Some channels (those with flags that include %TP_CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES) have a concept of "channel-specific contacts". These are contacts that only have meaning within the context of the channel - for instance, in XMPP Multi-User Chat, participants in a chatroom are identified by an in-room JID consisting of the JID of the chatroom plus a local nickname.

Depending on the protocol and configuration, it might be possible to find out what globally valid contact (i.e. a contact that you could add to your contact list) "owns" a channel-specific contact. For instance, in most XMPP MUC chatrooms, normal users cannot see what global JID corresponds to an in-room JID, but moderators can.

This is further complicated by the fact that channels with channel-specific contacts can sometimes have members with globally valid contacts (for instance, if you invite someone to an XMPP MUC using their globally valid JID, you would expect to see the contact representing that JID in the Group's remote-pending set).

• if self is not a group or handle is not a member of this channel, result is undefined;
• if %TP_CHANNEL_FEATURE_GROUP has not yet been prepared, result is undefined;
• if self does not have flags that include %TP_CHANNEL_GROUP_FLAG_PROPERTIES, result is undefined;
• if handle is channel-specific and its globally valid "owner" is known, return that owner;
• if handle is channel-specific and its globally valid "owner" is unknown, return zero;
• if handle is globally valid, return handle itself

Some channels (those with flags that include %TP_CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES) have a concept of "channel-specific handles". These are handles that only have meaning within the context of the channel - for instance, in XMPP Multi-User Chat, participants in a chatroom are identified by an in-room JID consisting of the JID of the chatroom plus a local nickname.

Depending on the protocol and configuration, it might be possible to find out what globally valid handle (i.e. an identifier that you could add to your contact list) "owns" a channel-specific handle. For instance, in most XMPP MUC chatrooms, normal users cannot see what global JID corresponds to an in-room JID, but moderators can.

This is further complicated by the fact that channels with channel-specific handles can sometimes have members with globally valid handles (for instance, if you invite someone to an XMPP MUC using their globally valid JID, you would expect to see the handle representing that JID in the Group's remote-pending set).

This function's result is undefined unless the channel is ready and its flags include %TP_CHANNEL_GROUP_FLAG_PROPERTIES (an implementation without extra D-Bus round trips is not possible using the older API).

If self is a group but %TP_CHANNEL_FEATURE_GROUP has not been prepared, the result may either be a set of local-pending members, or %NULL.

If self is not a group, return %NULL.

If local_pending is not the handle of a local-pending contact, write %NULL into actor, %TP_CHANNEL_GROUP_CHANGE_REASON_NONE into reason and "" into message, and return %FALSE.

If local_pending is not the handle of a local-pending contact, write 0 into actor, %TP_CHANNEL_GROUP_CHANGE_REASON_NONE into reason and "" into message, and return %FALSE.

If self is a group but %TP_CHANNEL_FEATURE_GROUP has not been prepared, the result may either be a set of members, or %NULL.

If self is not a group, return %NULL.

If self is a group but %TP_CHANNEL_FEATURE_GROUP has not been prepared, the result may either be a set of remote-pending members, or %NULL.

If self is not a group, return %NULL.

For objects that discover their interfaces at runtime, this method will indicate that interfaces are missing until they are known to be present. In subclasses that define features for use with tp_proxy_prepare_async(), successfully preparing the "core" feature for that subclass (such as %TP_CHANNEL_FEATURE_CORE or %TP_CONNECTION_FEATURE_CORE) implies that the interfaces are known.

(For instance, if feature is %TP_CHANNEL_FEATURE_CHAT_STATES and self is a #TpChannel in a protocol that doesn't actually implement chat states, or is not a #TpChannel at all, then this method will return %FALSE.)

To prepare features, call tp_proxy_prepare_async().

When we joined the channel, callback will be called. You can then call tp_channel_join_finish() to get the result of the operation.

Note that unlike tp_channel_leave_async(), %TP_CHANNEL_FEATURE_GROUP feature must be prepared before calling this function.

When we left the channel, callback will be called. You can then call tp_channel_leave_finish() to get the result of the operation.

Note that unlike tp_channel_join_async(), %TP_CHANNEL_FEATURE_GROUP feature does not have to be prepared and will be prepared for you. But this is a deprecated behaviour.

When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.

This function omits the property name lookup, hence it is faster than g_object_notify().

One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with g_object_class_install_property() inside a static array, e.g.:

  enum
  {
    PROP_0,
    PROP_FOO,
    PROP_LAST
  };

  static GParamSpec *properties[PROP_LAST];

  static void
  my_object_class_init (MyObjectClass *klass)
  {
    properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
                                             0, 100,
                                             50,
                                             G_PARAM_READWRITE);
    g_object_class_install_property (gobject_class,
                                     PROP_FOO,
                                     properties[PROP_FOO]);
  }

and then notify a change on the "foo" property with:

  g_object_notify_by_pspec (self, properties[PROP_FOO]);

Proxy instances start with no features prepared. When features are requested via tp_proxy_prepare_async(), the proxy starts to do the necessary setup to use those features.

tp_proxy_prepare_async() always waits for core functionality of the proxy's class to be prepared, even if it is not specifically requested: for instance, because %TP_CHANNEL_FEATURE_CORE is core functionality of a #TpChannel,

|[ TpChannel *channel = ...;

tp_proxy_prepare_async (channel, NULL, callback, user_data);

is equivalent to

|[
TpChannel *channel = ...;
GQuark features[] = { TP_CHANNEL_FEATURE_CORE, 0 };

tp_proxy_prepare_async (channel, features, callback, user_data);

If a feature represents core functionality (like %TP_CHANNEL_FEATURE_CORE), failure to prepare it will result in tp_proxy_prepare_async() finishing unsuccessfully: if failure to prepare the feature indicates that the proxy is no longer useful, it will also emit #TpProxy::invalidated.

If a feature represents non-essential functionality (like %TP_CHANNEL_FEATURE_CHAT_STATES), or is not supported by the object at all, then failure to prepare it is not fatal: tp_proxy_prepare_async() will complete successfully, but tp_proxy_is_prepared() will still return %FALSE for the feature, and accessor methods for the feature will typically return a dummy value.

Some #TpProxy subclasses automatically start to prepare their core features when instantiated, and features will sometimes become prepared as a side-effect of other actions, but to ensure that a feature is present you must generally call tp_proxy_prepare_async() and wait for the result.

Once the password has been provided, callback will be called. You can then call tp_channel_provide_password_finish() to get the result of the operation.

Since GLib 2.56, if GLIB_VERSION_MAX_ALLOWED is 2.56 or greater, the type of object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit.

In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one.

Since GLib 2.56, the type of object will be propagated to the return type under the same conditions as for g_object_ref().

This function should only be called from object system implementations.

If the object already had an association with that name, the old association will be destroyed.

Internally, the key is converted to a #GQuark using g_quark_from_string(). This means a copy of key is kept permanently (even after object has been finalized) — so it is recommended to only use a small, bounded set of values for key in your program, to avoid the #GQuark storage growing unbounded.

void
object_add_to_user_list (GObject     *object,
                         const gchar *new_string)
{
  // the quark, naming the object data
  GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
  // retrieve the old string list
  GList *list = g_object_steal_qdata (object, quark_string_list);

  // prepend new string
  list = g_list_prepend (list, g_strdup (new_string));
  // this changed 'list', so we need to set it again
  g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
}
static void
free_string_list (gpointer data)
{
  GList *node, *list = data;

  for (node = list; node; node = node->next)
    g_free (node->data);
  g_list_free (list);
}

Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata() would have left the destroy function set, and thus the partial string list would have been freed upon g_object_set_qdata_full().

Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued.

It is an error to call this function when the freeze count is zero.

If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this.

When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called.