linphonefriend.h 9.48 KB
Newer Older
jehan's avatar
jehan committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/*
linphonefriend.h
Copyright (C) 2010  Belledonne Communications SARL

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

#ifndef LINPHONEFRIEND_H_
#define LINPHONEFRIEND_H_
22 23 24

#include "linphonepresence.h"

jehan's avatar
jehan committed
25 26 27
#ifdef __cplusplus
extern "C" {
#endif
28

jehan's avatar
jehan committed
29 30 31 32 33 34 35 36 37 38 39 40
/**
 * @addtogroup buddy_list
 * @{
 */
/**
 * @ingroup buddy_list
 * Enum controlling behavior for incoming subscription request.
 * <br> Use by linphone_friend_set_inc_subscribe_policy()
 */
typedef  enum {
	/**
	 * Does not automatically accept an incoming subscription request.
jehan's avatar
jehan committed
41
	 * This policy implies that a decision has to be taken for each incoming subscription request notified by callback LinphoneCoreVTable.new_subscription_request
jehan's avatar
jehan committed
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
	 *
	 */
	LinphoneSPWait,
	/**
	 * Rejects incoming subscription request.
	 */
	LinphoneSPDeny,
	/**
	 * Automatically accepts a subscription request.
	 */
	LinphoneSPAccept
}LinphoneSubscribePolicy;

/**
 * Enum describing remote friend status
57
 * @deprecated Use #LinphonePresenceModel and #LinphonePresenceActivity instead
jehan's avatar
jehan committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
 */
typedef enum _LinphoneOnlineStatus{
	/**
	 * Offline
	 */
	LinphoneStatusOffline,
	/**
	 * Online
	 */
	LinphoneStatusOnline,
	/**
	 * Busy
	 */
	LinphoneStatusBusy,
	/**
	 * Be right back
	 */
	LinphoneStatusBeRightBack,
	/**
	 * Away
	 */
	LinphoneStatusAway,
	/**
	 * On the phone
	 */
	LinphoneStatusOnThePhone,
	/**
	 * Out to lunch
	 */
	LinphoneStatusOutToLunch,
	/**
	 * Do not disturb
	 */
	LinphoneStatusDoNotDisturb,
	/**
	 * Moved in this sate, call can be redirected if an alternate contact address has been set using function linphone_core_set_presence_info()
	 */
	LinphoneStatusMoved,
	/**
	 * Using another messaging service
	 */
	LinphoneStatusAltService,
	/**
	 * Pending
	 */
	LinphoneStatusPending,

Simon Morlat's avatar
Simon Morlat committed
105 106 107 108 109
        /**
         * Vacation
         */
        LinphoneStatusVacation,

jehan's avatar
jehan committed
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
	LinphoneStatusEnd
}LinphoneOnlineStatus;


struct _LinphoneFriend;
/**
 * Represents a buddy, all presence actions like subscription and status change notification are performed on this object
 */
typedef struct _LinphoneFriend LinphoneFriend;

/**
 * Contructor
 * @return a new empty #LinphoneFriend
 */
LinphoneFriend * linphone_friend_new();
/**
jehan's avatar
jehan committed
126
 * Contructor same as linphone_friend_new() + linphone_friend_set_addr()
jehan's avatar
jehan committed
127 128 129
 * @param addr a buddy address, must be a sip uri like sip:joe@sip.linphone.org
 * @return a new #LinphoneFriend with \link linphone_friend_get_address() address initialized \endlink
 */
130
LINPHONE_PUBLIC	LinphoneFriend *linphone_friend_new_with_addr(const char *addr);
jehan's avatar
jehan committed
131

jehan's avatar
jehan committed
132
/**
jehan's avatar
jehan committed
133 134
 * Destructor
 * @param lf #LinphoneFriend object
jehan's avatar
jehan committed
135
 */
jehan's avatar
jehan committed
136 137
void linphone_friend_destroy(LinphoneFriend *lf);

jehan's avatar
jehan committed
138
/**
jehan's avatar
jehan committed
139
 * set #LinphoneAddress for this friend
jehan's avatar
jehan committed
140
 * @param fr #LinphoneFriend object
jehan's avatar
jehan committed
141 142 143 144
 * @param address #LinphoneAddress
 */
int linphone_friend_set_addr(LinphoneFriend *fr, const LinphoneAddress* address);

145 146 147 148 149 150 151
/**
 * set the display name for this friend
 * @param lf #LinphoneFriend object
 * @param name 
 */
int linphone_friend_set_name(LinphoneFriend *lf, const char *name);

jehan's avatar
jehan committed
152 153 154 155 156
/**
 * get address of this friend
 * @param lf #LinphoneFriend object
 * @return #LinphoneAddress
 */
157
LINPHONE_PUBLIC	const LinphoneAddress *linphone_friend_get_address(const LinphoneFriend *lf);
jehan's avatar
jehan committed
158 159 160 161
/**
 * get subscription flag value
 * @param lf #LinphoneFriend object
 * @return returns true is subscription is activated for this friend
jehan's avatar
jehan committed
162 163
 *
 */
jehan's avatar
jehan committed
164 165 166
bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
#define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled

jehan's avatar
jehan committed
167 168 169 170 171 172
/**
 * Configure #LinphoneFriend to subscribe to presence information
 * @param fr #LinphoneFriend object
 * @param val if TRUE this friend will receive subscription message
 */

173
LINPHONE_PUBLIC	int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
jehan's avatar
jehan committed
174 175 176 177 178 179 180 181

#define linphone_friend_send_subscribe linphone_friend_enable_subscribes
/**
 * Configure incoming subscription policy for this friend.
 * @param fr #LinphoneFriend object
 * @param pol #LinphoneSubscribePolicy policy to apply.
 */
int linphone_friend_set_inc_subscribe_policy(LinphoneFriend *fr, LinphoneSubscribePolicy pol);
jehan's avatar
jehan committed
182 183 184 185 186 187 188 189
/**
 * get current subscription policy for this #LinphoneFriend
 * @param lf #LinphoneFriend object
 * @return #LinphoneSubscribePolicy
 *
 */
LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);

jehan's avatar
jehan committed
190 191 192 193 194
/**
 * Starts editing a friend configuration.
 *
 * Because friend configuration must be consistent, applications MUST
 * call linphone_friend_edit() before doing any attempts to modify
jehan's avatar
jehan committed
195
 * 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).
jehan's avatar
jehan committed
196 197 198
 * Once the modifications are done, then the application must call
 * linphone_friend_done() to commit the changes.
**/
199
LINPHONE_PUBLIC	void linphone_friend_edit(LinphoneFriend *fr);
jehan's avatar
jehan committed
200 201 202 203
/**
 * Commits modification made to the friend configuration.
 * @param fr #LinphoneFriend object
**/
204
LINPHONE_PUBLIC	void linphone_friend_done(LinphoneFriend *fr);
jehan's avatar
jehan committed
205 206 207 208




jehan's avatar
jehan committed
209
/**
210 211
 * @brief Get the status of a friend
 * @param[in] lf A #LinphoneFriend object
jehan's avatar
jehan committed
212
 * @return #LinphoneOnlineStatus
213
 * @deprecated Use linphone_friend_get_presence_model() instead
jehan's avatar
jehan committed
214 215
 */
LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
216

217 218 219
/**
 * @brief Get the presence information of a friend
 * @param[in] lf A #LinphoneFriend object
Ghislain MARY's avatar
Ghislain MARY committed
220
 * @return A #LinphonePresenceModel object, or NULL if the friend do not have presence information (in which case he is considered offline)
221
 */
222
const LinphonePresenceModel * linphone_friend_get_presence_model(LinphoneFriend *lf);
223

jehan's avatar
jehan committed
224 225 226 227 228 229 230
BuddyInfo * linphone_friend_get_info(const LinphoneFriend *lf);
void linphone_friend_set_ref_key(LinphoneFriend *lf, const char *key);
const char *linphone_friend_get_ref_key(const LinphoneFriend *lf);
bool_t linphone_friend_in_list(const LinphoneFriend *lf);

#define linphone_friend_url(lf) ((lf)->url)

jehan's avatar
jehan committed
231
/**
232
 * Return humain readable presence status
jehan's avatar
jehan committed
233
 * @param ss
234
 * @deprecated Use #LinphonePresenceModel, #LinphonePresenceActivity and linphone_presence_activity_to_string() instead.
jehan's avatar
jehan committed
235 236 237 238
 */
const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);


jehan's avatar
jehan committed
239
/**
240 241 242 243 244 245
 * @brief Set my presence status
 * @param[in] lc #LinphoneCore object
 * @param[in] minutes_away how long in away
 * @param[in] alternative_contact sip uri used to redirect call in state #LinphoneStatusMoved
 * @param[in] os #LinphoneOnlineStatus
 * @deprecated Use linphone_core_set_presence_model() instead
jehan's avatar
jehan committed
246
 */
247
LINPHONE_PUBLIC void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *alternative_contact,LinphoneOnlineStatus os);
248 249

/**
250 251 252 253 254
 * @brief Set my presence status
 * @param[in] lc #LinphoneCore object
 * @param[in] minutes_away how long in away
 * @param[in] alternative_contact sip uri used to redirect call in state #LinphoneStatusMoved
 * @param[in] presence #LinphonePresenceModel
255 256 257
 */
LINPHONE_PUBLIC void linphone_core_set_presence_model(LinphoneCore *lc, int minutes_away, const char *alternative_contact, LinphonePresenceModel *presence);

jehan's avatar
jehan committed
258
/**
259 260
 * @brief Get my presence status
 * @param[in] lc #LinphoneCore object
jehan's avatar
jehan committed
261
 * @return #LinphoneOnlineStatus
262
 * @deprecated Use linphone_core_get_presence_model() instead
jehan's avatar
jehan committed
263 264 265
 */
LinphoneOnlineStatus linphone_core_get_presence_info(const LinphoneCore *lc);

266
/**
267 268 269
 * @brief Get my presence status
 * @param[in] lc #LinphoneCore object
 * @return A #LinphonePresenceModel object, or NULL if no presence model has been set.
270 271 272
 */
LinphonePresenceModel * linphone_core_get_presence_model(const LinphoneCore *lc);

jehan's avatar
jehan committed
273 274 275 276 277 278
void linphone_core_interpret_friend_uri(LinphoneCore *lc, const char *uri, char **result);
/**
 * 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.
 * @param lc #LinphoneCore object
 * @param fr #LinphoneFriend to add
 */
279
LINPHONE_PUBLIC	void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
jehan's avatar
jehan committed
280 281 282 283 284 285 286 287 288
/**
 * remove a friend from the buddy list
 * @param lc #LinphoneCore object
 * @param fr #LinphoneFriend to add
 */
void linphone_core_remove_friend(LinphoneCore *lc, LinphoneFriend *fr);
/**
 * Black list a friend. same as linphone_friend_set_inc_subscribe_policy() with #LinphoneSPDeny policy;
 * @param lc #LinphoneCore object
jehan's avatar
jehan committed
289
 * @param lf #LinphoneFriend to add
jehan's avatar
jehan committed
290 291 292 293 294 295
 */
void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
/**
 * get Buddy list of LinphoneFriend
 * @param lc #LinphoneCore object
 * */
296
LINPHONE_PUBLIC	const MSList * linphone_core_get_friend_list(const LinphoneCore *lc);
jehan's avatar
jehan committed
297 298 299 300 301
/**
 *  notify all friends that have subscribed
 * @param lc #LinphoneCore object
 * @param os #LinphoneOnlineStatus to notify
 *  */
302
void linphone_core_notify_all_friends(LinphoneCore *lc, LinphonePresenceModel *presence);
jehan's avatar
jehan committed
303 304 305 306 307 308 309 310 311 312 313 314
LinphoneFriend *linphone_core_get_friend_by_address(const LinphoneCore *lc, const char *addr);
LinphoneFriend *linphone_core_get_friend_by_ref_key(const LinphoneCore *lc, const char *key);

/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* LINPHONEFRIEND_H_ */