src/core/sipe-group.h

   1 /**
   2  * @file sipe-group.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2011-2016 SIPE Project <http://sipe.sourceforge.net/>
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  */
  22
  23 /* Forward declarations */
  24 struct sipe_buddy;
  25 struct sipe_core_private;
  26 struct sipe_ucs_transaction;
  27
  28 struct sipe_group {
  29         gchar *name;
  30         gchar *exchange_key;
  31         gchar *change_key;
  32         guint id;
  33         gboolean is_obsolete;
  34 };
  35
  36 struct sipe_group *sipe_group_find_by_id(struct sipe_core_private *sipe_private,
  37                                          guint id);
  38
  39 struct sipe_group *sipe_group_find_by_name(struct sipe_core_private *sipe_private,
  40                                            const gchar * name);
  41
  42 /**
  43  * Request creation of group @c name on the server and add buddy @c who to it
  44  *
  45  * @param sipe_private SIPE core data
  46  * @param trans        UCS transaction (@c NULL when UCS is not in use)
  47  * @param name         name of group
  48  * @param who          SIP URI of buddy (may be @c NULL, i.e. empty group)
  49  */
  50 void sipe_group_create(struct sipe_core_private *sipe_private,
  51                        struct sipe_ucs_transaction *trans,
  52                        const gchar *name,
  53                        const gchar *who);
  54
  55 gboolean sipe_group_rename(struct sipe_core_private *sipe_private,
  56                            struct sipe_group *group,
  57                            const gchar *name);
  58
  59 /**
  60  * Creates @c sipe_group structure for a new group and adds it into the group
  61  * list of given account. If buddy is already in the list, its existing
  62  * structure is returned.
  63  *
  64  * @param sipe_private SIPE core data
  65  * @param name         name of group (may be @c NULL)
  66  * @param exchange_key Exchange key (may be @c NULL)
  67  * @param change_key   Change key (may be @c NULL)
  68  * @param id           numeric ID of group
  69  *
  70  * @return @c sipe_group structure or @c NULL if group creation failed
  71  */
  72 struct sipe_group *sipe_group_add(struct sipe_core_private *sipe_private,
  73                                   const gchar *name,
  74                                   const gchar *exchange_key,
  75                                   const gchar *change_key,
  76                                   guint id);
  77
  78 /* remove group from core & backend */
  79 void sipe_group_remove(struct sipe_core_private *sipe_private,
  80                        struct sipe_group *group);
  81
  82 /* update alias/group list for a buddy on the server */
  83 void sipe_group_update_buddy(struct sipe_core_private *sipe_private,
  84                              struct sipe_buddy *buddy);
  85
  86 /**
  87  * Prepare group list for an update
  88  *
  89  * @param sipe_private SIPE core data
  90  */
  91 void sipe_group_update_start(struct sipe_core_private *sipe_private);
  92
  93 /**
  94  * Finish group list update. This will remove obsolete groups.
  95  *
  96  * NOTE: this must be call after sipe_buddy_update_finish(), i.e. it
  97  *       assumes that the group is no longer associated with any buddy.
  98  *
  99  * @param sipe_private SIPE core data
 100  */
 101 void sipe_group_update_finish(struct sipe_core_private *sipe_private);
 102
 103 /**
 104  * Return first group
 105  *
 106  * @param sipe_private SIPE core data
 107  *
 108  * @return sipe_group structure or @c NULL if there are no groups
 109  */
 110 struct sipe_group *sipe_group_first(struct sipe_core_private *sipe_private);
 111
 112 /**
 113  * Number of groups
 114  *
 115  * @param sipe_private SIPE core data
 116  */
 117 guint sipe_group_count(struct sipe_core_private *sipe_private);
 118
 119 /**
 120  * Initialize group data
 121  *
 122  * @param sipe_private SIPE core data
 123  */
 124 void sipe_group_init(struct sipe_core_private *sipe_private);
 125
 126 /**
 127  * Free group data
 128  *
 129  * @param sipe_private SIPE core data
 130  */
 131 void sipe_group_free(struct sipe_core_private *sipe_private);