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