sjero.net Git - linphone/blob - coreapi/linphonefriend.h

   1 /*
   2 linphonefriend.h
   3 Copyright (C) 2010  Belledonne Communications SARL
   4
   5 This program is free software; you can redistribute it and/or
   6 modify it under the terms of the GNU General Public License
   7 as published by the Free Software Foundation; either version 2
   8 of the License, or (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  18 */
  19
  20 #ifndef LINPHONEFRIEND_H_
  21 #define LINPHONEFRIEND_H_
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25 /**
  26  * @addtogroup buddy_list
  27  * @{
  28  */
  29 /**
  30  * @ingroup buddy_list
  31  * Enum controlling behavior for incoming subscription request.
  32  * <br> Use by linphone_friend_set_inc_subscribe_policy()
  33  */
  34 typedef  enum {
  35         /**
  36          * Does not automatically accept an incoming subscription request.
  37          * This policy implies that a decision has to be taken for each incoming subscription request notified by callback LinphoneCoreVTable.new_subscription_request
  38          *
  39          */
  40         LinphoneSPWait,
  41         /**
  42          * Rejects incoming subscription request.
  43          */
  44         LinphoneSPDeny,
  45         /**
  46          * Automatically accepts a subscription request.
  47          */
  48         LinphoneSPAccept
  49 }LinphoneSubscribePolicy;
  50
  51 /**
  52  * Enum describing remote friend status
  53  */
  54 typedef enum _LinphoneOnlineStatus{
  55         /**
  56          * Offline
  57          */
  58         LinphoneStatusOffline,
  59         /**
  60          * Online
  61          */
  62         LinphoneStatusOnline,
  63         /**
  64          * Busy
  65          */
  66         LinphoneStatusBusy,
  67         /**
  68          * Be right back
  69          */
  70         LinphoneStatusBeRightBack,
  71         /**
  72          * Away
  73          */
  74         LinphoneStatusAway,
  75         /**
  76          * On the phone
  77          */
  78         LinphoneStatusOnThePhone,
  79         /**
  80          * Out to lunch
  81          */
  82         LinphoneStatusOutToLunch,
  83         /**
  84          * Do not disturb
  85          */
  86         LinphoneStatusDoNotDisturb,
  87         /**
  88          * Moved in this sate, call can be redirected if an alternate contact address has been set using function linphone_core_set_presence_info()
  89          */
  90         LinphoneStatusMoved,
  91         /**
  92          * Using another messaging service
  93          */
  94         LinphoneStatusAltService,
  95         /**
  96          * Pending
  97          */
  98         LinphoneStatusPending,
  99
 100         LinphoneStatusEnd
 101 }LinphoneOnlineStatus;
 102
 103
 104 struct _LinphoneFriend;
 105 /**
 106  * Represents a buddy, all presence actions like subscription and status change notification are performed on this object
 107  */
 108 typedef struct _LinphoneFriend LinphoneFriend;
 109
 110 /**
 111  * Contructor
 112  * @return a new empty #LinphoneFriend
 113  */
 114 LinphoneFriend * linphone_friend_new();
 115 /**
 116  * Contructor same as linphone_friend_new() + linphone_friend_set_addr()
 117  * @param addr a buddy address, must be a sip uri like sip:joe@sip.linphone.org
 118  * @return a new #LinphoneFriend with \link linphone_friend_get_address() address initialized \endlink
 119  */
 120 LinphoneFriend *linphone_friend_new_with_addr(const char *addr);
 121
 122 /**
 123  * Destructor
 124  * @param lf #LinphoneFriend object
 125  */
 126 void linphone_friend_destroy(LinphoneFriend *lf);
 127
 128 /**
 129  * set #LinphoneAddress for this friend
 130  * @param fr #LinphoneFriend object
 131  * @param address #LinphoneAddress
 132  */
 133 int linphone_friend_set_addr(LinphoneFriend *fr, const LinphoneAddress* address);
 134
 135 /**
 136  * set the display name for this friend
 137  * @param lf #LinphoneFriend object
 138  * @param name
 139  */
 140 int linphone_friend_set_name(LinphoneFriend *lf, const char *name);
 141
 142 /**
 143  * get address of this friend
 144  * @param lf #LinphoneFriend object
 145  * @return #LinphoneAddress
 146  */
 147 const LinphoneAddress *linphone_friend_get_address(const LinphoneFriend *lf);
 148 /**
 149  * get subscription flag value
 150  * @param lf #LinphoneFriend object
 151  * @return returns true is subscription is activated for this friend
 152  *
 153  */
 154 bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
 155 #define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled
 156
 157 /**
 158  * Configure #LinphoneFriend to subscribe to presence information
 159  * @param fr #LinphoneFriend object
 160  * @param val if TRUE this friend will receive subscription message
 161  */
 162
 163 int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
 164
 165 #define linphone_friend_send_subscribe linphone_friend_enable_subscribes
 166 /**
 167  * Configure incoming subscription policy for this friend.
 168  * @param fr #LinphoneFriend object
 169  * @param pol #LinphoneSubscribePolicy policy to apply.
 170  */
 171 int linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol);
 172 /**
 173  * get current subscription policy for this #LinphoneFriend
 174  * @param lf #LinphoneFriend object
 175  * @return #LinphoneSubscribePolicy
 176  *
 177  */
 178 LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);
 179
 180 /**
 181  * Starts editing a friend configuration.
 182  *
 183  * Because friend configuration must be consistent, applications MUST
 184  * call linphone_friend_edit() before doing any attempts to modify
 185  * friend configuration (such as \link linphone_friend_set_addr() address \endlink  or \link linphone_friend_set_inc_subscribe_policy() subscription policy\endlink  and so on).
 186  * Once the modifications are done, then the application must call
 187  * linphone_friend_done() to commit the changes.
 188 **/
 189 void linphone_friend_edit(LinphoneFriend *fr);
 190 /**
 191  * Commits modification made to the friend configuration.
 192  * @param fr #LinphoneFriend object
 193 **/
 194 void linphone_friend_done(LinphoneFriend *fr);
 195
 196
 197
 198
 199 /**
 200  * get friend status
 201  * @return #LinphoneOnlineStatus
 202  */
 203 LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
 204 BuddyInfo * linphone_friend_get_info(const LinphoneFriend *lf);
 205 void linphone_friend_set_ref_key(LinphoneFriend *lf, const char *key);
 206 const char *linphone_friend_get_ref_key(const LinphoneFriend *lf);
 207 bool_t linphone_friend_in_list(const LinphoneFriend *lf);
 208
 209 #define linphone_friend_url(lf) ((lf)->url)
 210
 211 /**
 212  * return humain readable presence status
 213  * @param ss
 214  */
 215 const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);
 216
 217
 218 /**
 219  * Set my presence status
 220  * @param lc #LinphoneCore object
 221  * @param minutes_away how long in away
 222  * @param alternative_contact sip uri used to redirect call in state #LinphoneStatusMoved
 223  * @param os #LinphoneOnlineStatus
 224  */
 225 void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *alternative_contact,LinphoneOnlineStatus os);
 226 /**
 227  * get my presence status
 228  * @param lc #LinphoneCore object
 229  * @return #LinphoneOnlineStatus
 230  */
 231 LinphoneOnlineStatus linphone_core_get_presence_info(const LinphoneCore *lc);
 232
 233 void linphone_core_interpret_friend_uri(LinphoneCore *lc, const char *uri, char **result);
 234 /**
 235  * Add a friend to the current buddy list, if \link linphone_friend_enable_subscribes() subscription attribute \endlink is set, a SIP SUBSCRIBE message is sent.
 236  * @param lc #LinphoneCore object
 237  * @param fr #LinphoneFriend to add
 238  */
 239 void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
 240 /**
 241  * remove a friend from the buddy list
 242  * @param lc #LinphoneCore object
 243  * @param fr #LinphoneFriend to add
 244  */
 245 void linphone_core_remove_friend(LinphoneCore *lc, LinphoneFriend *fr);
 246 /**
 247  * Black list a friend. same as linphone_friend_set_inc_subscribe_policy() with #LinphoneSPDeny policy;
 248  * @param lc #LinphoneCore object
 249  * @param lf #LinphoneFriend to add
 250  */
 251 void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
 252 /**
 253  * get Buddy list of LinphoneFriend
 254  * @param lc #LinphoneCore object
 255  * */
 256 const MSList * linphone_core_get_friend_list(const LinphoneCore *lc);
 257 /**
 258  *  notify all friends that have subscribed
 259  * @param lc #LinphoneCore object
 260  * @param os #LinphoneOnlineStatus to notify
 261  *  */
 262 void linphone_core_notify_all_friends(LinphoneCore *lc, LinphoneOnlineStatus os);
 263 LinphoneFriend *linphone_core_get_friend_by_address(const LinphoneCore *lc, const char *addr);
 264 LinphoneFriend *linphone_core_get_friend_by_ref_key(const LinphoneCore *lc, const char *key);
 265
 266 /**
 267  * @}
 268  */
 269
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273
 274 #endif /* LINPHONEFRIEND_H_ */