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