linphonefriend.h 7.92 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
/*
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_
#ifdef __cplusplus
extern "C" {
#endif
/**
 * @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
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 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 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 105 106 107 108 109 110 111 112 113 114 115
	 *
	 */
	LinphoneSPWait,
	/**
	 * Rejects incoming subscription request.
	 */
	LinphoneSPDeny,
	/**
	 * Automatically accepts a subscription request.
	 */
	LinphoneSPAccept
}LinphoneSubscribePolicy;

/**
 * Enum describing remote friend status
 */
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,

	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
116
 * Contructor same as linphone_friend_new() + linphone_friend_set_addr()
117 118 119
 * @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
 */
120
LINPHONE_PUBLIC	LinphoneFriend *linphone_friend_new_with_addr(const char *addr);
jehan's avatar
jehan committed
121

122
/**
jehan's avatar
jehan committed
123 124
 * Destructor
 * @param lf #LinphoneFriend object
125
 */
jehan's avatar
jehan committed
126 127
void linphone_friend_destroy(LinphoneFriend *lf);

128
/**
jehan's avatar
jehan committed
129
 * set #LinphoneAddress for this friend
130
 * @param fr #LinphoneFriend object
jehan's avatar
jehan committed
131 132 133 134
 * @param address #LinphoneAddress
 */
int linphone_friend_set_addr(LinphoneFriend *fr, const LinphoneAddress* address);

135 136 137 138 139 140 141
/**
 * 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
142 143 144 145 146
/**
 * get address of this friend
 * @param lf #LinphoneFriend object
 * @return #LinphoneAddress
 */
147
LINPHONE_PUBLIC	const LinphoneAddress *linphone_friend_get_address(const LinphoneFriend *lf);
jehan's avatar
jehan committed
148 149 150 151
/**
 * get subscription flag value
 * @param lf #LinphoneFriend object
 * @return returns true is subscription is activated for this friend
152 153
 *
 */
jehan's avatar
jehan committed
154 155 156
bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
#define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled

157 158 159 160 161 162
/**
 * Configure #LinphoneFriend to subscribe to presence information
 * @param fr #LinphoneFriend object
 * @param val if TRUE this friend will receive subscription message
 */

163
LINPHONE_PUBLIC	int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
164 165 166 167 168 169 170 171

#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
172 173 174 175 176 177 178 179
/**
 * get current subscription policy for this #LinphoneFriend
 * @param lf #LinphoneFriend object
 * @return #LinphoneSubscribePolicy
 *
 */
LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);

180 181 182 183 184
/**
 * 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
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 187 188
 * Once the modifications are done, then the application must call
 * linphone_friend_done() to commit the changes.
**/
189
LINPHONE_PUBLIC	void linphone_friend_edit(LinphoneFriend *fr);
190 191 192 193
/**
 * Commits modification made to the friend configuration.
 * @param fr #LinphoneFriend object
**/
194
LINPHONE_PUBLIC	void linphone_friend_done(LinphoneFriend *fr);
jehan's avatar
jehan committed
195 196 197 198




199 200 201 202 203 204 205 206 207 208 209 210
/**
 * get friend status
 * @return #LinphoneOnlineStatus
 */
LinphoneOnlineStatus linphone_friend_get_status(const LinphoneFriend *lf);
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
211 212 213 214 215 216 217
/**
 * return humain readable presence status
 * @param ss
 */
const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);


218 219 220 221 222 223 224
/**
 * Set my presence status
 * @param lc #LinphoneCore object
 * @param minutes_away how long in away
 * @param alternative_contact sip uri used to redirect call in state #LinphoneStatusMoved
 * @param os #LinphoneOnlineStatus
 */
225
LINPHONE_PUBLIC void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *alternative_contact,LinphoneOnlineStatus os);
226 227 228 229 230 231 232 233 234 235 236 237 238
/**
 * get my presence status
 * @param lc #LinphoneCore object
 * @return #LinphoneOnlineStatus
 */
LinphoneOnlineStatus linphone_core_get_presence_info(const LinphoneCore *lc);

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
 */
239
LINPHONE_PUBLIC	void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
240 241 242 243 244 245 246 247 248
/**
 * 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
249
 * @param lf #LinphoneFriend to add
250 251 252 253 254 255
 */
void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
/**
 * get Buddy list of LinphoneFriend
 * @param lc #LinphoneCore object
 * */
256
LINPHONE_PUBLIC	const MSList * linphone_core_get_friend_list(const LinphoneCore *lc);
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274
/**
 *  notify all friends that have subscribed
 * @param lc #LinphoneCore object
 * @param os #LinphoneOnlineStatus to notify
 *  */
void linphone_core_notify_all_friends(LinphoneCore *lc, LinphoneOnlineStatus os);
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_ */