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