src/core/sipe-buddy.h

   1 /**
   2  * @file sipe-buddy.h
   3  *
   4  * pidgin-sipe
   5  *
   6  * Copyright (C) 2010-2013 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_cal_working_hours;
  25 struct sipe_core_private;
  26 struct sipe_group;
  27
  28 struct sipe_buddy {
  29         gchar *name;
  30         gchar *exchange_key;
  31         gchar *change_key;
  32         gchar *activity;
  33         gchar *meeting_subject;
  34         gchar *meeting_location;
  35         /* Sipe internal format for Note is HTML.
  36          * All incoming plain text should be html-escaped
  37          * for example by g_markup_escape_text()
  38          */
  39         gchar *note;
  40         gboolean is_oof_note;
  41         time_t note_since;
  42
  43         /* Calendar related fields */
  44         gchar *cal_start_time;
  45         int cal_granularity;
  46         gchar *cal_free_busy_base64;
  47         gchar *cal_free_busy;
  48         time_t cal_free_busy_published;
  49         /* for 2005 systems */
  50         int user_avail;
  51         time_t user_avail_since;
  52         time_t activity_since;
  53         const char *last_non_cal_status_id;
  54         gchar *last_non_cal_activity;
  55
  56         struct sipe_cal_working_hours *cal_working_hours;
  57
  58         gchar *device_name;
  59         GSList *groups;
  60          /** flag to control sending 'context' element in 2007 subscriptions */
  61         gboolean just_added;
  62         gboolean is_obsolete;
  63 };
  64
  65 /**
  66  * Creates @c sipe_buddy structure for a new buddy and adds it into the buddy
  67  * list of given account. If buddy is already in the list, its existing
  68  * structure is returned.
  69  *
  70  * @param sipe_private SIPE core data
  71  * @param uri          SIP URI of a buddy
  72  * @param exchange_key Exchange key (may be @c NULL)
  73  * @param change_key   Change key (may be @c NULL)
  74  *
  75  * @return @c sipe_buddy structure
  76  */
  77 struct sipe_buddy *sipe_buddy_add(struct sipe_core_private *sipe_private,
  78                                   const gchar *uri,
  79                                   const gchar *exchange_key,
  80                                   const gchar *change_key);
  81
  82 /**
  83  * Add buddy to a group.
  84  *
  85  * @param sipe_private SIPE core data
  86  * @param buddy        sipe_buddy data structure
  87  * @param group        sipe_group data structure
  88  * @param alias        alias for the buddy in that group (may be @c NULL)
  89  */
  90 void sipe_buddy_add_to_group(struct sipe_core_private *sipe_private,
  91                              struct sipe_buddy *buddy,
  92                              struct sipe_group *group,
  93                              const gchar *alias);
  94
  95 /**
  96  * Insert a group to buddy group list
  97  *
  98  * @param buddy        sipe_buddy data structure
  99  * @param group        sipe_group data structure
 100  */
 101 void sipe_buddy_insert_group(struct sipe_buddy *buddy,
 102                              struct sipe_group *group);
 103
 104 /**
 105  * Update group list for a buddy
 106  *
 107  * @param sipe_private SIPE core data
 108  * @param buddy        sipe_buddy data structure
 109  * @param group        list with new sipe_group data structures
 110  */
 111 void sipe_buddy_update_groups(struct sipe_core_private *sipe_private,
 112                               struct sipe_buddy *buddy,
 113                               GSList *new_groups);
 114
 115 /**
 116  * Remove entries from local buddy list that do not have corresponding entries
 117  * in the ones in the contact list sent by the server
 118  *
 119  * @param sipe_private SIPE core data
 120  */
 121 void sipe_buddy_cleanup_local_list(struct sipe_core_private *sipe_private);
 122
 123 /**
 124  * Prepare buddy list for an update
 125  *
 126  * @param sipe_private SIPE core data
 127  */
 128 void sipe_buddy_update_start(struct sipe_core_private *sipe_private);
 129
 130 /**
 131  * Finish buddy list update. This will remove obsolete buddies.
 132  *
 133  * @param sipe_private SIPE core data
 134  */
 135 void sipe_buddy_update_finish(struct sipe_core_private *sipe_private);
 136
 137 /**
 138  * Find buddy by URI
 139  *
 140  * @param sipe_private SIPE core data
 141  * @param uri          SIP URI of a buddy
 142  *
 143  * @return @c sipe_buddy structure
 144  */
 145 struct sipe_buddy *sipe_buddy_find_by_uri(struct sipe_core_private *sipe_private,
 146                                           const gchar *uri);
 147
 148 /**
 149  * Find buddy by Exchange Key
 150  *
 151  * @param sipe_private SIPE core data
 152  * @param uri          Exchange Key of a buddy
 153  *
 154  * @return @c sipe_buddy structure
 155  */
 156 struct sipe_buddy *sipe_buddy_find_by_exchange_key(struct sipe_core_private *sipe_private,
 157                                                    const gchar *exchange_key);
 158
 159 /**
 160  * Iterate buddy list
 161  *
 162  * @param sipe_private SIPE core data
 163  * @param callback          function to call on each buddy
 164  * @param callback_data     user data for the callback
 165  */
 166 void sipe_buddy_foreach(struct sipe_core_private *sipe_private,
 167                         GHFunc callback,
 168                         gpointer callback_data);
 169
 170 /**
 171  * Cancels buddy subscriptions and then deletes the buddy
 172  *
 173  * @param sipe_private SIPE core data
 174  * @param buddy        @c sipe_buddy structure to remove
 175  */
 176 void sipe_buddy_remove(struct sipe_core_private *sipe_private,
 177                        struct sipe_buddy *buddy);
 178
 179 /**
 180  * Tries to retrieve a real user's name associated with given SIP URI.
 181  *
 182  * Result must be g_free'd after use.
 183  *
 184  * @param sipe_private SIPE core data
 185  * @param with         a SIP URI
 186  *
 187  * @return Name of the user if the URI is found in buddy list, otherwise @c NULL
 188  */
 189 gchar *sipe_buddy_get_alias(struct sipe_core_private *sipe_private,
 190                             const gchar *with);
 191
 192 /**
 193  * Update the value of a buddy property with given SIP URI
 194  *
 195  * @param sipe_private   SIPE core data
 196  * @param uri            a SIP URI
 197  * @param propkey        property id (see sipe-backend.h)
 198  * @param property_value new value for the property
 199  */
 200 void sipe_buddy_update_property(struct sipe_core_private *sipe_private,
 201                                 const gchar *uri,
 202                                 sipe_buddy_info_fields propkey,
 203                                 gchar *property_value);
 204
 205 /**
 206  * Triggers a download of all buddy photos that were changed on the server.
 207  *
 208  * @param sipe_private SIPE core data
 209  */
 210 void sipe_buddy_refresh_photos(struct sipe_core_private *sipe_private);
 211
 212 /**
 213  * Number of buddies
 214  *
 215  * @param sipe_private SIPE core data
 216  */
 217 guint sipe_buddy_count(struct sipe_core_private *sipe_private);
 218
 219 /**
 220  * Initialize buddy data
 221  *
 222  * @param sipe_private SIPE core data
 223  */
 224 void sipe_buddy_init(struct sipe_core_private *sipe_private);
 225
 226 /**
 227  * Free buddy data
 228  *
 229  * @param sipe_private SIPE core data
 230  */
 231 void sipe_buddy_free(struct sipe_core_private *sipe_private);