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  * get address of this friend
 137  * @param lf #LinphoneFriend object
 138  * @return #LinphoneAddress
 139  */
 140 const LinphoneAddress *linphone_friend_get_address(const LinphoneFriend *lf);
 141 /**
 142  * get subscription flag value
 143  * @param lf #LinphoneFriend object
 144  * @return returns true is subscription is activated for this friend
 145  *
 146  */
 147 bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
 148 #define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled
 149
 150 /**
 151  * Configure #LinphoneFriend to subscribe to presence information
 152  * @param fr #LinphoneFriend object
 153  * @param val if TRUE this friend will receive subscription message
 154  */
 155
 156 int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
 157
 158 #define linphone_friend_send_subscribe linphone_friend_enable_subscribes
 159 /**
 160  * Configure incoming subscription policy for this friend.
 161  * @param fr #LinphoneFriend object
 162  * @param pol #LinphoneSubscribePolicy policy to apply.
 163  */
 164 int linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol);
 165 /**
 166  * get current subscription policy for this #LinphoneFriend
 167  * @param lf #LinphoneFriend object
 168  * @return #LinphoneSubscribePolicy
 169  *
 170  */
 171 LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);
 172
 173 /**
 174  * Starts editing a friend configuration.
 175  *
 176  * Because friend configuration must be consistent, applications MUST
 177  * call linphone_friend_edit() before doing any attempts to modify
 178  * 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).
 179  * Once the modifications are done, then the application must call
 180  * linphone_friend_done() to commit the changes.
 181 **/
 182 void linphone_friend_edit(LinphoneFriend *fr);
 183 /**
 184  * Commits modification made to the friend configuration.
 185  * @param fr #LinphoneFriend object
 186 **/
 187 void linphone_friend_done(LinphoneFriend *fr);
 188
 189
 190
 191
 192 /**
 193  * get friend status
 194  * @return #LinphoneOnlineStatus
 195  */
 196 LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
 197 BuddyInfo * linphone_friend_get_info(const LinphoneFriend *lf);
 198 void linphone_friend_set_ref_key(LinphoneFriend *lf, const char *key);
 199 const char *linphone_friend_get_ref_key(const LinphoneFriend *lf);
 200 bool_t linphone_friend_in_list(const LinphoneFriend *lf);
 201
 202 #define linphone_friend_url(lf) ((lf)->url)
 203
 204 /**
 205  * return humain readable presence status
 206  * @param ss
 207  */
 208 const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);
 209
 210
 211 /**
 212  * Set my presence status
 213  * @param lc #LinphoneCore object
 214  * @param minutes_away how long in away
 215  * @param alternative_contact sip uri used to redirect call in state #LinphoneStatusMoved
 216  * @param os #LinphoneOnlineStatus
 217  */
 218 void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *alternative_contact,LinphoneOnlineStatus os);
 219 /**
 220  * get my presence status
 221  * @param lc #LinphoneCore object
 222  * @return #LinphoneOnlineStatus
 223  */
 224 LinphoneOnlineStatus linphone_core_get_presence_info(const LinphoneCore *lc);
 225
 226 void linphone_core_interpret_friend_uri(LinphoneCore *lc, const char *uri, char **result);
 227 /**
 228  * 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.
 229  * @param lc #LinphoneCore object
 230  * @param fr #LinphoneFriend to add
 231  */
 232 void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
 233 /**
 234  * remove a friend from the buddy list
 235  * @param lc #LinphoneCore object
 236  * @param fr #LinphoneFriend to add
 237  */
 238 void linphone_core_remove_friend(LinphoneCore *lc, LinphoneFriend *fr);
 239 /**
 240  * Black list a friend. same as linphone_friend_set_inc_subscribe_policy() with #LinphoneSPDeny policy;
 241  * @param lc #LinphoneCore object
 242  * @param lf #LinphoneFriend to add
 243  */
 244 void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
 245 /**
 246  * get Buddy list of LinphoneFriend
 247  * @param lc #LinphoneCore object
 248  * */
 249 const MSList * linphone_core_get_friend_list(const LinphoneCore *lc);
 250 /**
 251  *  notify all friends that have subscribed
 252  * @param lc #LinphoneCore object
 253  * @param os #LinphoneOnlineStatus to notify
 254  *  */
 255 void linphone_core_notify_all_friends(LinphoneCore *lc, LinphoneOnlineStatus os);
 256 LinphoneFriend *linphone_core_get_friend_by_address(const LinphoneCore *lc, const char *addr);
 257 LinphoneFriend *linphone_core_get_friend_by_ref_key(const LinphoneCore *lc, const char *key);
 258
 259 /**
 260  * @}
 261  */
 262
 263 #ifdef __cplusplus
 264 }
 265 #endif
 266
 267 #endif /* LINPHONEFRIEND_H_ */