TpGroupMixin

TpGroupMixin — a mixin implementation of the groups interface

Synopsis


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


gboolean            (*TpGroupMixinAddMemberFunc)        (GObject *obj,
                                                         TpHandle handle,
                                                         const gchar *message,
                                                         GError **error);
gboolean            (*TpGroupMixinRemMemberFunc)        (GObject *obj,
                                                         TpHandle handle,
                                                         const gchar *message,
                                                         GError **error);
                    TpGroupMixin;
                    TpGroupMixinClass;
void                tp_group_mixin_class_init           (GObjectClass *obj_cls,
                                                         glong offset,
                                                         TpGroupMixinAddMemberFunc add_func,
                                                         TpGroupMixinRemMemberFunc rem_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_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 remove);
gboolean            tp_group_mixin_change_members       (GObject *obj,
                                                         const gchar *message,
                                                         TpIntSet *add,
                                                         TpIntSet *remove,
                                                         TpIntSet *add_local_pending,
                                                         TpIntSet *add_remote_pending,
                                                         TpHandle actor,
                                                         TpChannelGroupChangeReason reason);
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);


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.

Details

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

TpGroupMixin

typedef struct {
  TpHandleRepoIface *handle_repo;
  TpHandle self_handle;

  TpChannelGroupFlags group_flags;

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

  TpGroupMixinPrivate *priv;
} TpGroupMixin;

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 (FIXME: how do we do self-renaming?)
TpChannelGroupFlags group_flags; This group's flags. Set using tp_group_mixin_change_flags().
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

TpGroupMixinClass

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

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

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_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 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 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 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 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 GArray of guint representing the handles of the group's members
local_pending : Used to return a GArray of guint representing the handles of the group's local pending members
remote_pending : Used to return a 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 remove);

Request a change to be made to the flags. Emits the GroupFlagsChanged signal with the changes which were actually made.

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

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

tp_group_mixin_change_members ()

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

Change the sets of members as given by the arguments, and emit the MembersChanged signal 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, remove, add_local_pending and add_remote_pending have a non-empty intersection, the result is undefined. Don't do that.

obj : An object implementing the group interface using this mixin
message : A message to be sent to the affected contacts if possible
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)
remove : 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 signal was emitted; FALSE if nothing actually changed and the signal was suppressed.

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.

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 (may not be 0)

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

See Also

TpSvcChannelInterfaceGroup