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