folks/group-details.vala

   1 /*
   2  * Copyright (C) 2010 Collabora Ltd.
   3  *
   4  * This library is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Authors:
  18  *       Travis Reitter <travis.reitter@collabora.co.uk>
  19  */
  20
  21 using GLib;
  22 using Gee;
  23
  24 /**
  25  * Interface for {@link Persona}s or {@link Individual}s which can be grouped
  26  * into sets of similar objects.
  27  */
  28 public interface Folks.GroupDetails : Object
  29 {
  30   /**
  31    * The reason a group member has changed its membership in the group.
  32    *
  33    * These closely follow the
  34    * [[http://telepathy.freedesktop.org/spec/Channel_Interface_Group.html#Channel_Group_Change_Reason|Channel_Group_Change_Reason]]
  35    * interface in the Telepathy specification.
  36    */
  37   public enum ChangeReason
  38     {
  39       /**
  40        * No reason was provided for this change.
  41        *
  42        * This is used when a member joins or leaves a group normally.
  43        */
  44       NONE = 0,
  45       /**
  46        * The change is due to a member going offline.
  47        *
  48        * Also used when member is already offline, but this wasn't known
  49        * previously.
  50        */
  51       OFFLINE = 1,
  52       /**
  53        * The change is due to a kick operation.
  54        */
  55       KICKED = 2,
  56       /**
  57        * The change is due to a busy indication.
  58        */
  59       BUSY = 3,
  60       /**
  61        * The change is due to an invitation.
  62        */
  63       INVITED = 4,
  64       /**
  65        * The change is due to a kick+ban operation.
  66        */
  67       BANNED = 5,
  68       /**
  69        * The change is due to an error occurring.
  70        */
  71       ERROR = 6,
  72       /**
  73        * The change is because the requested member does not exist.
  74        *
  75        * For instance, if the user invites a nonexistent contact to a chatroom
  76        * or attempts to call a nonexistent contact
  77        */
  78       INVALID_MEMBER = 7,
  79       /**
  80        * The change is because the requested contact did not respond.
  81        */
  82       NO_ANSWER = 8,
  83       /**
  84        * The change is because a member's unique identifier changed.
  85        *
  86        * There must be exactly one member in the removed set and exactly one
  87        * member in one of the added sets.
  88        */
  89       RENAMED = 9,
  90       /**
  91        * The change is because there was no permission to contact the requested
  92        * member.
  93        */
  94       PERMISSION_DENIED = 10,
  95       /**
  96        * If members are removed with this reason code, the change is because the
  97        * group has split into unconnected parts which can only communicate
  98        * within themselves (e.g. netsplits on IRC use this reason code).
  99        *
 100        * If members are added with this reason code, the change is because
 101        * unconnected parts of the group have rejoined. If this channel carries
 102        * messages (e.g. Text or Tubes channels) applications must assume that
 103        * the contacts being added are likely to have missed some messages as a
 104        * result of the separation, and that the contacts in the group are likely
 105        * to have missed some messages from the contacts being added.
 106        *
 107        * Note that from the added contacts' perspective, they have been in the
 108        * group all along, and the contacts we indicate to be in the group
 109        * (including the local user) have just rejoined the group with reason
 110        * Separated. Application protocols in Tubes should be prepared to cope
 111        * with this situation.
 112        */
 113       SEPARATED = 11
 114     }
 115
 116   /**
 117    * A mapping of group ID to whether the contact is a member.
 118    *
 119    * Freeform group IDs are mapped to a boolean which is `true` if the
 120    * contact is a member of the group, and `false` otherwise.
 121    *
 122    * @since 0.5.1
 123    */
 124   public abstract Set<string> groups { get; set; }
 125
 126   /**
 127    * Add or remove the contact from the specified group.
 128    *
 129    * If `is_member` is `true`, the contact will be added to the `group`. If
 130    * it is `false`, they will be removed from the `group`.
 131    *
 132    * @param group a freeform group identifier
 133    * @param is_member whether the contact should be a member of the group
 134    * @since 0.1.11
 135    */
 136   public async abstract void change_group (string group, bool is_member)
 137     throws GLib.Error;
 138
 139   /**
 140    * Emitted when the contact's membership status changes for a group.
 141    *
 142    * This is emitted if the contact becomes a member of a group they weren't in
 143    * before, or leaves a group they were in.
 144    *
 145    * @param group a freeform group identifier for the group being left or joined
 146    * @param is_member whether the contact is joining or leaving the group
 147    * @since 0.1.11
 148    */
 149   public async signal void group_changed (string group, bool is_member);
 150 }