src/core/sipe-buddy.h

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