TpGroupMixin

## TpGroupMixin TpGroupMixin — a mixin implementation of the groups interface |

## Synopsis

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

    #define             TP_HAS_GROUP_MIXIN                  (o)
    #define             TP_HAS_GROUP_MIXIN_CLASS            (cls)
    gboolean            (*TpGroupMixinAddMemberFunc)        (GObject *obj,
                                                             TpHandle handle,
                                                             const gchar *message,
                                                             GError **error);
    gboolean            (*TpGroupMixinRemMemberFunc)        (GObject *obj,
                                                             TpHandle handle,
                                                             const gchar *message,
                                                             GError **error);
    gboolean            (*TpGroupMixinRemMemberWithReasonFunc)
                                                            (GObject *obj,
                                                             TpHandle handle,
                                                             const gchar *message,
                                                             guint reason,
                                                             GError **error);
    struct              TpGroupMixin;
    struct              TpGroupMixinClass;
    void                tp_group_mixin_class_init           (GObjectClass *obj_cls,
                                                             glong offset,
                                                             TpGroupMixinAddMemberFunc add_func,
                                                             TpGroupMixinRemMemberFunc rem_func);
    void                tp_group_mixin_class_allow_self_removal
                                                            (GObjectClass *obj_cls);
    void                tp_group_mixin_class_set_remove_with_reason_func
                                                            (GObjectClass *cls,
                                                             TpGroupMixinRemMemberWithReasonFunc func);
    void                tp_group_mixin_init                 (GObject *obj,
                                                             glong offset,
                                                             TpHandleRepoIface *handle_repo,
                                                             TpHandle self_handle);
    void                tp_group_mixin_finalize             (GObject *obj);
    gboolean            tp_group_mixin_get_self_handle      (GObject *obj,
                                                             guint *ret,
                                                             GError **error);
    gboolean            tp_group_mixin_get_group_flags      (GObject *obj,
                                                             guint *ret,
                                                             GError **error);
    gboolean            tp_group_mixin_add_members          (GObject *obj,
                                                             const GArray *contacts,
                                                             const gchar *message,
                                                             GError **error);
    gboolean            tp_group_mixin_remove_members       (GObject *obj,
                                                             const GArray *contacts,
                                                             const gchar *message,
                                                             GError **error);
    gboolean            tp_group_mixin_remove_members_with_reason
                                                            (GObject *obj,
                                                             const GArray *contacts,
                                                             const gchar *message,
                                                             guint reason,
                                                             GError **error);
    gboolean            tp_group_mixin_get_members          (GObject *obj,
                                                             GArray **ret,
                                                             GError **error);
    gboolean            tp_group_mixin_get_local_pending_members
                                                            (GObject *obj,
                                                             GArray **ret,
                                                             GError **error);
    gboolean            tp_group_mixin_get_local_pending_members_with_info
                                                            (GObject *obj,
                                                             GPtrArray **ret,
                                                             GError **error);
    gboolean            tp_group_mixin_get_remote_pending_members
                                                            (GObject *obj,
                                                             GArray **ret,
                                                             GError **error);
    gboolean            tp_group_mixin_get_all_members      (GObject *obj,
                                                             GArray **members,
                                                             GArray **local_pending,
                                                             GArray **remote_pending,
                                                             GError **error);
    gboolean            tp_group_mixin_get_handle_owners    (GObject *obj,
                                                             const GArray *handles,
                                                             GArray **ret,
                                                             GError **error);
    void                tp_group_mixin_change_flags         (GObject *obj,
                                                             TpChannelGroupFlags add,
                                                             TpChannelGroupFlags del);
    gboolean            tp_group_mixin_change_members       (GObject *obj,
                                                             const gchar *message,
                                                             const TpIntset *add,
                                                             const TpIntset *del,
                                                             const TpIntset *add_local_pending,
                                                             const TpIntset *add_remote_pending,
                                                             TpHandle actor,
                                                             TpChannelGroupChangeReason reason);
    gboolean            tp_group_mixin_change_members_detailed
                                                            (GObject *obj,
                                                             const TpIntset *add,
                                                             const TpIntset *del,
                                                             const TpIntset *add_local_pending,
                                                             const TpIntset *add_remote_pending,
                                                             const GHashTable *details);
    void                tp_group_mixin_add_handle_owner     (GObject *obj,
                                                             TpHandle local_handle,
                                                             TpHandle owner_handle);
    void                tp_group_mixin_iface_init           (gpointer g_iface,
                                                             gpointer iface_data);
    void                tp_group_mixin_add_handle_owners    (GObject *obj,
                                                             GHashTable *local_to_owner_handle);
    void                tp_group_mixin_get_dbus_property    (GObject *object,
                                                             GQuark interface,
                                                             GQuark name,
                                                             GValue *value,
                                                             gpointer unused);
    void                tp_group_mixin_init_dbus_properties (GObjectClass *cls);
    void                tp_group_mixin_change_self_handle   (GObject *obj,
                                                             TpHandle new_self_handle);
    void                tp_external_group_mixin_iface_init  (gpointer g_iface,
                                                             gpointer iface_data);
    void                tp_external_group_mixin_init        (GObject *obj,
                                                             GObject *obj_with_mixin);
    void                tp_external_group_mixin_finalize    (GObject *obj);
    void                tp_external_group_mixin_init_dbus_properties
                                                            (GObjectClass *cls);
    void                tp_external_group_mixin_get_dbus_property
                                                            (GObject *object,
                                                             GQuark interface,
                                                             GQuark name,
                                                             GValue *value,
                                                             gpointer unused);

## Description

This mixin can be added to a channel GObject class to implement the groups interface in a general way.

To use the group mixin, include a TpGroupMixinClass somewhere in your class structure and a TpGroupMixin somewhere in your instance structure, and call `tp_group_mixin_class_init()` from your class_init function, `tp_group_mixin_init()` from your init function or constructor, and `tp_group_mixin_finalize()` from your dispose or finalize function.

To use the group mixin as the implementation of TpSvcChannelInterfaceGroup, call `G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_INTERFACE_GROUP, tp_group_mixin_iface_init)` in the fourth argument to `G_DEFINE_TYPE_WITH_CODE`.

Since 0.5.13 you can also implement the group interface by forwarding all group operations to the group mixin of an associated object (mainly useful for Tubes channels). To do this, call `tp_external_group_mixin_init()` in the constructor after the associated object has been set, `tp_external_group_mixin_finalize()` in the dispose or finalize function, and `G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CHANNEL_INTERFACE_GROUP, tp_external_group_mixin_iface_init)` in the fourth argument to `G_DEFINE_TYPE_WITH_CODE`.

Since 0.7.10 you can also implement the properties of Group channels, by calling `tp_group_mixin_init_dbus_properties()` or `tp_external_group_mixin_init_dbus_properties()` (as appropriate).

## Details

### TP_HAS_GROUP_MIXIN()

    #define TP_HAS_GROUP_MIXIN(o) (TP_GROUP_MIXIN_OFFSET (o) != 0)

`o` : | a GObject instance
Returns : | `TRUE` if `o` (or one of its parent classes) has the group mixin.

Since 0.13.9

### TP_HAS_GROUP_MIXIN_CLASS()

    #define TP_HAS_GROUP_MIXIN_CLASS(cls) (TP_GROUP_MIXIN_CLASS_OFFSET (cls) != 0)

`cls` : | a GObjectClass structure
Returns : | `TRUE` if `cls` (or one of its parent classes) has the group mixin.

Since 0.13.9

### TpGroupMixinAddMemberFunc ()

    gboolean            (*TpGroupMixinAddMemberFunc)        (GObject *obj,
                                                             TpHandle handle,
                                                             const gchar *message,
                                                             GError **error);

Signature of the callback used to add a member to the group. This should perform the necessary operations in the underlying IM protocol to cause the member to be added.

`obj` : | An object implementing the group interface with this mixin
`handle` : | The handle of the contact to be added
`message` : | A message to be sent if the protocol supports it
`error` : | Used to return a Telepathy D-Bus error if `FALSE` is returned
Returns : | `TRUE` on success, `FALSE` with `error` set on error

### TpGroupMixinRemMemberFunc ()

    gboolean            (*TpGroupMixinRemMemberFunc)        (GObject *obj,
                                                             TpHandle handle,
                                                             const gchar *message,
                                                             GError **error);

Signature of the callback used to remove a member from the group. This should perform the necessary operations in the underlying IM protocol to cause the member to be removed.

`obj` : | An object implementing the group interface with this mixin
`handle` : | The handle of the contact to be removed
`message` : | A message to be sent if the protocol supports it
`error` : | Used to return a Telepathy D-Bus error if `FALSE` is returned
Returns : | `TRUE` on success, `FALSE` with `error` set on error

### TpGroupMixinRemMemberWithReasonFunc ()

    gboolean            (*TpGroupMixinRemMemberWithReasonFunc)
                                                            (GObject *obj,
                                                             TpHandle handle,
                                                             const gchar *message,
                                                             guint reason,
                                                             GError **error);

Signature of the callback used to remove a member from the group. This should perform the necessary operations in the underlying IM protocol to cause the member to be removed.

Set this with `tp_group_mixin_class_set_remove_with_reason_func()`, .

`obj` : | An object implementing the group interface with this mixin
`handle` : | The handle of the contact to be removed
`message` : | A message to be sent if the protocol supports it
`reason` : | A TpChannelGroupChangeReason indicating the reason
`error` : | Used to return a Telepathy D-Bus error if `FALSE` is returned
Returns : | `TRUE` on success, `FALSE` with `error` set on error

### struct TpGroupMixin

    struct TpGroupMixin {
      TpHandleRepoIface *handle_repo;
      TpHandle self_handle;

      TpChannelGroupFlags group_flags;

      TpHandleSet *members;
      TpHandleSet *local_pending;
      TpHandleSet *remote_pending;

      TpGroupMixinPrivate *priv;
    };

Structure representing the group mixin as used in a particular class. To be placed in the implementation's instance structure.

All fields should be considered read-only.

TpHandleRepoIface *`handle_repo`; | The connection's contact handle repository
TpHandle `self_handle`; | The local user's handle within this group, or 0 if none. Set using `tp_group_mixin_init()` and `tp_group_mixin_change_self_handle()`.
TpChannelGroupFlags `group_flags`; | This group's flags. Set using `tp_group_mixin_change_flags()`; defaults to 0.
TpHandleSet *`members`; | The members of the group. Alter using `tp_group_mixin_change_members()`.
TpHandleSet *`local_pending`; | Members awaiting the local user's approval to join the group. Alter using `tp_group_mixin_change_members()`.
TpHandleSet *`remote_pending`; | Members awaiting remote (e.g. remote user or server) approval to join the group. Alter using `tp_group_mixin_change_members()`.
TpGroupMixinPrivate *`priv`; | Pointer to opaque private data

### struct TpGroupMixinClass

    struct TpGroupMixinClass {
      TpGroupMixinAddMemberFunc add_member;
      TpGroupMixinRemMemberFunc remove_member;
      TpGroupMixinClassPrivate *priv;
    };

Structure representing the group mixin as used in a particular class. To be placed in the implementation's class structure.

Initialize this with `tp_group_mixin_class_init()`.

All fields should be considered read-only.

TpGroupMixinAddMemberFunc `add_member`; | The add-member function that was passed to `tp_group_mixin_class_init()`
TpGroupMixinRemMemberFunc `remove_member`; | The remove-member function that was passed to `tp_group_mixin_class_init()`
TpGroupMixinClassPrivate *`priv`; | Pointer to opaque private data

### tp_group_mixin_class_init ()

    void                tp_group_mixin_class_init           (GObjectClass *obj_cls,
                                                             glong offset,
                                                             TpGroupMixinAddMemberFunc add_func,
                                                             TpGroupMixinRemMemberFunc rem_func);

Configure the mixin for use with the given class.

`obj_cls` : | The class of an object implementing the group interface using this mixin
`offset` : | The offset of the TpGroupMixinClass structure within the class structure
`add_func` : | A callback to be used to add contacts to this group
`rem_func` : | A callback to be used to remove contacts from this group. This must be `NULL` if you will subsequently call `tp_group_mixin_class_set_remove_with_reason_func()`.

### tp_group_mixin_class_allow_self_removal ()

    void                tp_group_mixin_class_allow_self_removal
                                                            (GObjectClass *obj_cls);

Configure the mixin to allow attempts to remove the SelfHandle from this Group, even if the group flags would otherwise disallow this. The channel's TpGroupMixinRemMemberFunc or TpGroupMixinRemMemberWithReasonFunc will be called as usual for such attempts, and may make them fail with `TP_ERROR_PERMISSION_DENIED` if required.

This function should be called from the GObject `class_init` callback, after calling `tp_group_mixin_class_init()`.

(Recent telepathy-spec changes make it valid to try to remove the self-handle at all times, regardless of group flags. However, if this was implemented automatically in TpGroupMixin, this would risk crashing connection manager implementations that assume that TpGroupMixin will enforce the group flags strictly. As a result, connection managers should call this function to indicate to the TpGroupMixin that it may call their removal callback with the self-handle regardless of flag settings.)

`obj_cls` : | The class of an object implementing the group interface using this mixin

Since 0.7.27

### tp_group_mixin_class_set_remove_with_reason_func ()

    void                tp_group_mixin_class_set_remove_with_reason_func
                                                            (GObjectClass *cls,
                                                             TpGroupMixinRemMemberWithReasonFunc func);

Set a callback to be used to implement `RemoveMembers()` and `RemoveMembersWithReason()`. If this function is called during class initialization, the given callback will be used instead of the remove callback passed to `tp_group_mixin_class_init()` (which must be `NULL` in this case).

`cls` : | The class of an object implementing the group interface using this mixin
`func` : | A callback to be used to remove contacts from this group with a specified reason.

Since 0.5.13

### tp_group_mixin_init ()

    void                tp_group_mixin_init                 (GObject *obj,
                                                             glong offset,
                                                             TpHandleRepoIface *handle_repo,
                                                             TpHandle self_handle);

Initialize the mixin.

`obj` : | An object implementing the group interface using this mixin
`offset` : | The offset of the TpGroupMixin structure within the instance structure
`handle_repo` : | The connection's handle repository for contacts
`self_handle` : | The handle of the local user in this group, if any

### tp_group_mixin_finalize ()

    void                tp_group_mixin_finalize             (GObject *obj);

Unreference handles and free resources used by this mixin.

`obj` : | An object implementing the group interface using this mixin

### tp_group_mixin_get_self_handle ()

    gboolean            tp_group_mixin_get_self_handle      (GObject *obj,
                                                             guint *ret,
                                                             GError **error);

Set the guint pointed to by ret to the local user's handle in this group, or to 0 if the local user is not present in this group.

`obj` : | An object implementing the group mixin using this interface
`ret` : | Used to return the local user's handle in this group
`error` : | Unused
Returns : | `TRUE`.

### tp_group_mixin_get_group_flags ()

    gboolean            tp_group_mixin_get_group_flags      (GObject *obj,
                                                             guint *ret,
                                                             GError **error);

Set the guint pointed to by ret to this group's flags, to be interpreted according to TpChannelGroupFlags.

`obj` : | An object implementing the group mixin using this interface
`ret` : | Used to return the flags
`error` : | Unused
Returns : | `TRUE`

### tp_group_mixin_add_members ()

    gboolean            tp_group_mixin_add_members          (GObject *obj,
                                                             const GArray *contacts,
                                                             const gchar *message,
                                                             GError **error);

Request that the given contacts be added to the group as if in response to user action. If the group's flags prohibit this, raise PermissionDenied. If any of the handles is invalid, raise InvalidHandle. Otherwise attempt to add the contacts by calling the callbacks provided by the channel implementation.

`obj` : | An object implementing the group interface using this mixin
`contacts` : | A GArray of guint representing contacts
`message` : | A message associated with the addition request, if supported
`error` : | Used to return an error if `FALSE` is returned
Returns : | `TRUE` on success

### tp_group_mixin_remove_members ()

    gboolean            tp_group_mixin_remove_members       (GObject *obj,
                                                             const GArray *contacts,
                                                             const gchar *message,
                                                             GError **error);

Request that the given contacts be removed from the group as if in response to user action. If the group's flags prohibit this, raise PermissionDenied. If any of the handles is invalid, raise InvalidHandle. If any of the handles is absent from the group, raise NotAvailable. Otherwise attempt to remove the contacts by calling the callbacks provided by the channel implementation.

`obj` : | An object implementing the group interface using this mixin
`contacts` : | A GArray of guint representing contacts
`message` : | A message to be sent to those contacts, if supported
`error` : | Used to return an error if `FALSE` is returned
Returns : | `TRUE` on success

### tp_group_mixin_remove_members_with_reason ()

    gboolean            tp_group_mixin_remove_members_with_reason
                                                            (GObject *obj,
                                                             const GArray *contacts,
                                                             const gchar *message,
                                                             guint reason,
                                                             GError **error);

Request that the given contacts be removed from the group as if in response to user action. If the group's flags prohibit this, raise PermissionDenied. If any of the handles is invalid, raise InvalidHandle. If any of the handles is absent from the group, raise NotAvailable. Otherwise attempt to remove the contacts by calling the callbacks provided by the channel implementation.

`obj` : | An object implementing the group interface using this mixin
`contacts` : | A GArray of guint representing contacts
`message` : | A message to be sent to those contacts, if supported
`reason` : | A TpChannelGroupChangeReason
`error` : | Used to return an error if `FALSE` is returned
Returns : | `TRUE` on success

### tp_group_mixin_get_members ()

    gboolean            tp_group_mixin_get_members          (GObject *obj,
                                                             GArray **ret,
                                                             GError **error);

Get the group's current members

`obj` : | An object implementing the group interface using this mixin
`ret` : | Used to return a newly-allocated GArray of guint contact handles
`error` : | Unused
Returns : | `TRUE`

### tp_group_mixin_get_local_pending_members ()

    gboolean            tp_group_mixin_get_local_pending_members
                                                            (GObject *obj,
                                                             GArray **ret,
                                                             GError **error);

Get the group's local-pending members.

`obj` : | An object implementing the group interface using this mixin
`ret` : | Used to return a newly-allocated GArray of guint contact handles
`error` : | Unused
Returns : | `TRUE`

### tp_group_mixin_get_local_pending_members_with_info ()

    gboolean            tp_group_mixin_get_local_pending_members_with_info
                                                            (GObject *obj,
                                                             GPtrArray **ret,
                                                             GError **error);

Get the group's local-pending members and information about their requests to join the channel.

`obj` : | An object implementing the group interface using this mixin
`ret` : | Used to return a newly-allocated GPtrArray of D-Bus structures each containing the handle of a local-pending contact, the handle of a contact responsible for adding them to the group (or 0), the reason code and a related message (e.g. their request to join the group)
`error` : | Unused
Returns : | `TRUE`

### tp_group_mixin_get_remote_pending_members ()

    gboolean            tp_group_mixin_get_remote_pending_members
                                                            (GObject *obj,
                                                             GArray **ret,
                                                             GError **error);

Get the group's remote-pending members.

`obj` : | An object implementing the group interface using this mixin
`ret` : | Used to return a newly-allocated GArray of guint representing the handles of the group's remote pending members
`error` : | Unused
Returns : | `TRUE`

### tp_group_mixin_get_all_members ()

    gboolean            tp_group_mixin_get_all_members      (GObject *obj,
                                                             GArray **members,
                                                             GArray **local_pending,
                                                             GArray **remote_pending,
                                                             GError **error);

Get the group's current and pending members.

`obj` : | An object implementing the group interface using this mixin
`members` : | Used to return a newly-allocated GArray of guint representing the handles of the group's members
`local_pending` : | Used to return a newly-allocated GArray of guint representing the handles of the group's local pending members
`remote_pending` : | Used to return a newly-allocated GArray of guint representing the handles of the group's remote pending members
`error` : | Unused
Returns : | `TRUE`

### tp_group_mixin_get_handle_owners ()

    gboolean            tp_group_mixin_get_handle_owners    (GObject *obj,
                                                             const GArray *handles,
                                                             GArray **ret,
                                                             GError **error);

If the mixin has the flag `TP_CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES`, return the global owners of the given local handles, or 0 where unavailable.

`obj` : | An object implementing the group interface with this mixin
`handles` : | An array of guint representing locally valid handles
`ret` : | Used to return an array of guint representing globally valid handles, or 0 where unavailable, if `TRUE` is returned
`error` : | Used to return an error if `FALSE` is returned
Returns : | `TRUE` (setting `ret`) on success, `FALSE` (setting `error`) on failure

### tp_group_mixin_change_flags ()

    void                tp_group_mixin_change_flags         (GObject *obj,
                                                             TpChannelGroupFlags add,
                                                             TpChannelGroupFlags del);

Request a change to be made to the flags. If any flags were actually set or cleared, emits the GroupFlagsChanged signal with the changes.

It is an error to set any of the same bits in both `add` and `del`.

Changed in 0.7.7: the signal is not emitted if adding `add` and removing `del` had no effect on the existing group flags.

`obj` : | An object implementing the groups interface using this mixin
`add` : | Flags to be added
`del` : | Flags to be removed

### tp_group_mixin_change_members ()

    gboolean            tp_group_mixin_change_members       (GObject *obj,
                                                             const gchar *message,
                                                             const TpIntset *add,
                                                             const TpIntset *del,
                                                             const TpIntset *add_local_pending,
                                                             const TpIntset *add_remote_pending,
                                                             TpHandle actor,
                                                             TpChannelGroupChangeReason reason);

Change the sets of members as given by the arguments, and emit the MembersChanged and MembersChangedDetailed signals if the changes were not a no-op.

This function must be called in response to events on the underlying IM protocol, and must not be called in direct response to user input; it does not respect the permissions flags, but changes the group directly.

If any two of add, del, add_local_pending and add_remote_pending have a non-empty intersection, the result is undefined. Don't do that.

Each of the TpIntset arguments may be `NULL`, which is treated as equivalent to an empty set.

`obj` : | An object implementing the group interface using this mixin
`message` : | A message to be sent to the affected contacts if possible; `NULL` is allowed, and is mapped to an empty string
`add` : | A set of contact handles to be added to the members (if not already present) and removed from local pending and remote pending (if present)
`del` : | A set of contact handles to be removed from members, local pending or remote pending, wherever they are present
`add_local_pending` : | A set of contact handles to be added to local pending, and removed from members and remote pending
`add_remote_pending` : | A set of contact handles to be added to remote pending, and removed from members and local pending
`actor` : | The handle of the contact responsible for this change
`reason` : | The reason for this change
Returns : | `TRUE` if the group was changed and the MembersChanged(Detailed) signals were emitted; `FALSE` if nothing actually changed and the signals were suppressed.

### tp_group_mixin_change_members_detailed ()

    gboolean            tp_group_mixin_change_members_detailed
                                                            (GObject *obj,
                                                             const TpIntset *add,
                                                             const TpIntset *del,
                                                             const TpIntset *add_local_pending,
                                                             const TpIntset *add_remote_pending,
                                                             const GHashTable *details);

Change the sets of members as given by the arguments, and emit the MembersChanged and MembersChangedDetailed signals if the changes were not a no-op.

This function must be called in response to events on the underlying IM protocol, and must not be called in direct response to user input; it does not respect the permissions flags, but changes the group directly.

If any two of add, del, add_local_pending and add_remote_pending have a non-empty intersection, the result is undefined. Don't do that.

Each of the TpIntset arguments may be `NULL`, which is treated as equivalent to an empty set.

details may contain, among other entries, the well-known keys (and corresponding type, wrapped in a GValue) defined by the Group.MembersChangedDetailed signal's specification; these include "actor" (a handle as G_TYPE_UINT), "change-reason" (an element of TpChannelGroupChangeReason as G_TYPE_UINT), "message" (G_TYPE_STRING), "error" (G_TYPE_STRING), "debug-message" (G_TYPE_STRING).

If all of the information in details could be passed to `tp_group_mixin_change_members()` then calling this function instead provides no benefit. Calling this function without setting TP_CHANNEL_GROUP_FLAG_MEMBERS_CHANGED_DETAILED with `tp_group_mixin_change_members()` first is not very useful, as clients will not know to listen for MembersChangedDetailed and thus will miss the details.

`obj` : | An object implementing the group interface using this mixin
`add` : | A set of contact handles to be added to the members (if not already present) and removed from local pending and remote pending (if present)
`del` : | A set of contact handles to be removed from members, local pending or remote pending, wherever they are present
`add_local_pending` : | A set of contact handles to be added to local pending, and removed from members and remote pending
`add_remote_pending` : | A set of contact handles to be added to remote pending, and removed from members and local pending
`details` : | a map from strings to GValues detailing the change
Returns : | `TRUE` if the group was changed and the MembersChanged(Detailed) signals were emitted; `FALSE` if nothing actually changed and the signals were suppressed.

Since 0.7.21

### tp_group_mixin_add_handle_owner ()

    void                tp_group_mixin_add_handle_owner     (GObject *obj,
                                                             TpHandle local_handle,
                                                             TpHandle owner_handle);

Note that the given local handle is an alias within this group for the given globally-valid handle. It will be returned from subsequent GetHandleOwner queries where appropriate.

Changed in 0.7.10: The `owner_handle` may be 0. To comply with telepathy-spec 0.17.6, before adding any channel-specific handle to the members, local-pending members or remote-pending members, you must call either this function or `tp_group_mixin_add_handle_owners()`.

`obj` : | A GObject implementing the group interface with this mixin
`local_handle` : | A contact handle valid within this group (may not be 0)
`owner_handle` : | A contact handle valid globally, or 0 if the owner of the `local_handle` is unknown

### tp_group_mixin_iface_init ()

    void                tp_group_mixin_iface_init           (gpointer g_iface,
                                                             gpointer iface_data);

Fill in the vtable entries needed to implement the group interface using this mixin. This function should usually be called via G_IMPLEMENT_INTERFACE.

`g_iface` : | A TpSvcChannelInterfaceGroupClass
`iface_data` : | Unused

### tp_group_mixin_add_handle_owners ()

    void                tp_group_mixin_add_handle_owners    (GObject *obj,
                                                             GHashTable *local_to_owner_handle);

Note that the given local handles are aliases within this group for the given globally-valid handles.

To comply with telepathy-spec 0.17.6, before adding any channel-specific handle to the members, local-pending members or remote-pending members, you must call either this function or `tp_group_mixin_add_handle_owner()`.

`obj` : | A GObject implementing the group interface with this mixin
`local_to_owner_handle` : | A map from contact handles valid within this group (which may not be 0) to either contact handles valid globally, or 0 if the owner of the corresponding key is unknown; all handles are stored using GUINT_TO_POINTER

Since 0.7.10

### tp_group_mixin_get_dbus_property ()

    void                tp_group_mixin_get_dbus_property    (GObject *object,
                                                             GQuark interface,
                                                             GQuark name,
                                                             GValue *value,
                                                             gpointer unused);

An implementation of TpDBusPropertiesMixinGetter which assumes that the `object` has the group mixin. It can only be used for the Group interface.

`object` : | An object with this mixin
`interface` : | Must be `TP_IFACE_QUARK_CHANNEL_INTERFACE_GROUP`
`name` : | A quark representing the D-Bus property name, either "GroupFlags", "HandleOwners", "LocalPendingMembers", "Members", "RemotePendingMembers" or "SelfHandle"
`value` : | A GValue pre-initialized to the right type, into which to put the value
`unused` : | Ignored

Since 0.7.10

### tp_group_mixin_init_dbus_properties ()

    void                tp_group_mixin_init_dbus_properties (GObjectClass *cls);

Set up TpDBusPropertiesMixinClass to use this mixin's implementation of the Group interface's properties.

This uses `tp_group_mixin_get_dbus_property()` as the property getter and sets up a list of the supported properties for it. Having called this, you should add TP_CHANNEL_GROUP_FLAG_PROPERTIES to any channels of this class with `tp_group_mixin_change_flags()` to indicate that the DBus properties are available.

`cls` : | The class of an object with this mixin

Since 0.7.10

### tp_group_mixin_change_self_handle ()

    void                tp_group_mixin_change_self_handle   (GObject *obj,
                                                             TpHandle new_self_handle);

Change the self-handle for this group to the given value.

`obj` : | An object implementing the group interface using this mixin
`new_self_handle` : | The new self-handle for this group

### tp_external_group_mixin_iface_init ()

    void                tp_external_group_mixin_iface_init  (gpointer g_iface,
                                                             gpointer iface_data);

Fill in the vtable entries needed to implement the group interface using the group mixin of another object. This function should usually be called via G_IMPLEMENT_INTERFACE.

`g_iface` : | A TpSvcChannelInterfaceGroupClass
`iface_data` : | Unused

Since 0.5.13

### tp_external_group_mixin_init ()

    void                tp_external_group_mixin_init        (GObject *obj,
                                                             GObject *obj_with_mixin);

Fill in the qdata needed to implement the group interface using the group mixin of another object. This function should usually be called in the instance constructor.

`obj` : | An object implementing the groups interface using an external group mixin
`obj_with_mixin` : | A GObject with the group mixin

Since 0.5.13

### tp_external_group_mixin_finalize ()

    void                tp_external_group_mixin_finalize    (GObject *obj);

Remove the external group mixin. This function should usually be called in the dispose or finalize function.

`obj` : | An object implementing the groups interface using an external group mixin

Since 0.5.13

### tp_external_group_mixin_init_dbus_properties ()

    void                tp_external_group_mixin_init_dbus_properties
                                                            (GObjectClass *cls);

Set up TpDBusPropertiesMixinClass to use this mixin's implementation of the Group interface's properties.

This uses `tp_group_mixin_get_dbus_property()` as the property getter and sets up a list of the supported properties for it. Having called this, you should add TP_CHANNEL_GROUP_FLAG_PROPERTIES to channels containing the mixin used by this class with `tp_group_mixin_change_flags()` to indicate that the DBus properties are available.

`cls` : | The class of an object with this mixin

Since 0.7.10

### tp_external_group_mixin_get_dbus_property ()

    void                tp_external_group_mixin_get_dbus_property
                                                            (GObject *object,
                                                             GQuark interface,
                                                             GQuark name,
                                                             GValue *value,
                                                             gpointer unused);

An implementation of TpDBusPropertiesMixinGetter which assumes that the `object` has the external group mixin. It can only be used for the Group interface.

`object` : | An object with this mixin
`interface` : | Must be `TP_IFACE_QUARK_CHANNEL_INTERFACE_GROUP`
`name` : | A quark representing the D-Bus property name, either "GroupFlags", "HandleOwners", "LocalPendingMembers", "Members", "RemotePendingMembers" or "SelfHandle"
`value` : | A GValue pre-initialized to the right type, into which to put the value
`unused` : | Ignored

Since 0.7.10

## See Also

TpSvcChannelInterfaceGroup