--- /dev/null
+
+/*
+linphone
+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.
+*/
+
+/**
+ * @defgroup buddy_tutorials Basic buddy status notification
+ * @ingroup tutorials
+ *This program is a _very_ simple usage example of liblinphone.
+ *Desmonstrating how to initiate a SIP subscription and receive notification from a sip uri identity passed from the command line.
+ *<br>Argument must be like sip:jehan@sip.linphone.org .
+ *<br>
+ *ex registration sip:jehan@sip.linphone.org secret
+ *<br>Subscription is cleared on SIGINT
+ *<br>
+ *@include buddy_status.c
+
+ *
+ */
+
+#include "linphonecore.h"
+
+#include <signal.h>
+
+static bool_t running=TRUE;
+
+static void stop(int signum){
+ running=FALSE;
+}
+
+/**
+ * presence state change notification callback
+ */
+static void notify_presence_recv_updated (struct _LinphoneCore *lc, LinphoneFriend *friend) {
+ const LinphoneAddress* friend_address = linphone_friend_get_address(friend);
+ printf("New state state [%s] for user id [%s] \n"
+ ,linphone_online_status_to_string(linphone_friend_get_status(friend))
+ ,linphone_address_as_string (friend_address));
+}
+
+LinphoneCore *lc;
+int main(int argc, char *argv[]){
+ LinphoneCoreVTable vtable={0};
+
+ char* dest_friend=NULL;
+
+
+ /* takes sip uri identity from the command line arguments */
+ if (argc>1){
+ dest_friend=argv[1];
+ }
+
+ signal(SIGINT,stop);
+#define DEBUG
+#ifdef DEBUG
+ linphone_core_enable_logs(NULL); /*enable liblinphone logs.*/
+#endif
+ /*
+ Fill the LinphoneCoreVTable with application callbacks.
+ All are optional. Here we only use the registration_state_changed callbacks
+ in order to get notifications about the progress of the registration.
+ */
+ vtable.notify_presence_recv=notify_presence_recv_updated;
+
+ /*
+ Instanciate a LinphoneCore object given the LinphoneCoreVTable
+ */
+ lc=linphone_core_new(&vtable,NULL,NULL,NULL);
+ LinphoneFriend* my_friend=NULL;
+
+ if (dest_friend) {
+ my_friend = linphone_friend_new_with_addr(dest_friend); /*creates friend object from dest*/
+ if (my_friend == NULL) {
+ printf("bad destination uri for friend [%s]\n",dest_friend);
+ goto end;
+ }
+
+ linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
+ linphone_friend_set_name(my_friend,"My best friend"); /* add a nickname to this buddy */
+ //linphone_friend_set_inc_subscribe_policy(my_friend,)
+ linphone_core_add_friend(lc,my_friend); /* add my friend to the buddy list, initiate SUBSCRIBE message*/
+
+ }
+
+ /* main loop for receiving notifications and doing background linphonecore work: */
+ while(running){
+ linphone_core_iterate(lc); /* first iterate initiates registration */
+ ms_usleep(50000);
+ }
+
+ linphone_friend_edit(my_friend); /* start editing friend */
+ linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/
+ linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/
+
+
+end:
+ printf("Shutting down...\n");
+ linphone_core_destroy(lc);
+ printf("Exited\n");
+ return 0;
+}
+
* The application doesn't own a reference to the returned LinphoneCall object.
* Use linphone_call_ref() to safely keep the LinphoneCall pointer valid within your application.
*
- * @Returns a LinphoneCall object or NULL in case of failure
+ * @return a LinphoneCall object or NULL in case of failure
**/
LinphoneCall * linphone_core_invite(LinphoneCore *lc, const char *url){
LinphoneCall *call;
* The application doesn't own a reference to the returned LinphoneCall object.
* Use linphone_call_ref() to safely keep the LinphoneCall pointer valid within your application.
*
- * @Returns a LinphoneCall object or NULL in case of failure
+ * @return a LinphoneCall object or NULL in case of failure
**/
LinphoneCall * linphone_core_invite_with_params(LinphoneCore *lc, const char *url, const LinphoneCallParams *p){
LinphoneAddress *addr=linphone_core_interpret_url(lc,url);
* The application doesn't own a reference to the returned LinphoneCall object.
* Use linphone_call_ref() to safely keep the LinphoneCall pointer valid within your application.
*
- * @Returns a LinphoneCall object or NULL in case of failure
+ * @return a LinphoneCall object or NULL in case of failure
**/
LinphoneCall * linphone_core_invite_address(LinphoneCore *lc, const LinphoneAddress *addr){
LinphoneCall *call;
* The application doesn't own a reference to the returned LinphoneCall object.
* Use linphone_call_ref() to safely keep the LinphoneCall pointer valid within your application.
*
- * @Returns a LinphoneCall object or NULL in case of failure
+ * @return a LinphoneCall object or NULL in case of failure
**/
LinphoneCall * linphone_core_invite_address_with_params(LinphoneCore *lc, const LinphoneAddress *addr, const LinphoneCallParams *params)
{
*
* For the moment, this is limited to enabling or disabling the video stream.
*
- * @Returns 0 if successful, -1 otherwise.
+ * @return 0 if successful, -1 otherwise.
**/
int linphone_core_update_call(LinphoneCore *lc, LinphoneCall *call, LinphoneCallParams *params){
int err;
const char *linphone_call_get_remote_user_agent(LinphoneCall *call);
void *linphone_call_get_user_pointer(LinphoneCall *call);
void linphone_call_set_user_pointer(LinphoneCall *call, void *user_pointer);
-
-typedef enum{
+/**
+ * @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.
+ *
+ */
LinphoneSPWait,
+ /**
+ * Rejects incoming subscription request.
+ */
LinphoneSPDeny,
+ /**
+ * Automatically accepts a subscription request.
+ */
LinphoneSPAccept
}LinphoneSubscribePolicy;
+/**
+ * @ingroup buddy_list
+ */
typedef enum _LinphoneOnlineStatus{
LinphoneStatusOffline,
LinphoneStatusOnline,
LinphoneStatusPending,
LinphoneStatusEnd
}LinphoneOnlineStatus;
-
+/**
+ * @ingroup buddy_list
+ * return humain readable presence status
+ * @param ss
+ */
const char *linphone_online_status_to_string(LinphoneOnlineStatus ss);
+/**
+ * @addtogroup buddy_list
+ * @{
+ */
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();
+/**
+ * Contructor same as linphone_friend_new() + linphone_friend_set_sip_addr()
+ * @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
+ */
LinphoneFriend *linphone_friend_new_with_addr(const char *addr);
+/**
+ * Configure #LinphoneFriend with a new address.
+ * @param uri a buddy address, must be a sip uri like sip:joe@sip.linphone.org
+ * @return 0 if succeed
+ */
int linphone_friend_set_sip_addr(LinphoneFriend *fr, const char *uri);
+/**
+ * modify friend nickname
+ * @param fr #LinphoneFriend object
+ * @param new name
+ * @return 0 if succeed
+ *
+ */
int linphone_friend_set_name(LinphoneFriend *fr, const char *name);
-int linphone_friend_send_subscribe(LinphoneFriend *fr, bool_t val);
+/**
+ * Configure #LinphoneFriend to subscribe to presence information
+ * @param fr #LinphoneFriend object
+ * @param val if TRUE this friend will receive subscription message
+ */
+
+int linphone_friend_enable_subscribes(LinphoneFriend *fr, bool_t val);
+
+#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);
+/**
+ * Starts editing a friend configuration.
+ *
+ * Because friend configuration must be consistent, applications MUST
+ * call linphone_friend_edit() before doing any attempts to modify
+ * friend configuration (such as \link linphone_friend_set_name() nick name \endlink , \link linphone_friend_set_sip_addr() address \endlink and so on).
+ * Once the modifications are done, then the application must call
+ * linphone_friend_done() to commit the changes.
+**/
void linphone_friend_edit(LinphoneFriend *fr);
+/**
+ * Commits modification made to the friend configuration.
+ * @param fr #LinphoneFriend object
+**/
void linphone_friend_done(LinphoneFriend *fr);
+/**
+ * Destructor
+ * @param fr #LinphoneFriend object
+ */
void linphone_friend_destroy(LinphoneFriend *lf);
+/**
+ * get address of this friend
+ * @param lf #LinphoneFriend object
+ * @return #LinphoneAddress
+ */
const LinphoneAddress *linphone_friend_get_address(const LinphoneFriend *lf);
-bool_t linphone_friend_get_send_subscribe(const LinphoneFriend *lf);
+/**
+ * get subscription flag value
+ * @param lf #LinphoneFriend object
+ * @return returns true is subscription is activated for this friend
+ *
+ */
+bool_t linphone_friend_subscribes_enabled(const LinphoneFriend *lf);
+#define linphone_friend_get_send_subscribe linphone_friend_subscribes_enabled
+/**
+ * get current subscription policy for this #LinphoneFriend
+ * @param lf #LinphoneFriend object
+ * @return #LinphoneSubscribePolicy
+ *
+ */
LinphoneSubscribePolicy linphone_friend_get_inc_subscribe_policy(const LinphoneFriend *lf);
+/**
+ * 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);
bool_t linphone_friend_in_list(const LinphoneFriend *lf);
#define linphone_friend_url(lf) ((lf)->url)
-
+/**
+ * @}
+ */
/**
* @addtogroup proxies
void linphone_auth_info_destroy(LinphoneAuthInfo *info);
LinphoneAuthInfo * linphone_auth_info_new_from_config_file(struct _LpConfig *config, int pos);
+
struct _LinphoneChatRoom;
typedef struct _LinphoneChatRoom LinphoneChatRoom;
typedef void (*LinphoneCoreCbFunc)(struct _LinphoneCore *lc,void * user_data);
/** Callback prototype */
typedef void (*NotifyReceivedCb)(struct _LinphoneCore *lc, LinphoneCall *call, const char *from, const char *event);
-/** Callback prototype */
-typedef void (*NotifyPresenceReceivedCb)(struct _LinphoneCore *lc, LinphoneFriend * fid);
+/**
+ * Report status change for a friend previously \link linphone_core_add_friend() added \endlink to #LinphoneCore.
+ * @param lc #LinphoneCore object .
+ * @param fr Updated #LinphoneFriend .
+ */
+typedef void (*NotifyPresenceReceivedCb)(struct _LinphoneCore *lc, LinphoneFriend * fr);
/** Callback prototype */
typedef void (*NewUnknownSubscriberCb)(struct _LinphoneCore *lc, LinphoneFriend *lf, const char *url);
/** Callback prototype */
bool_t linphone_core_get_rtp_no_xmit_on_audio_mute(const LinphoneCore *lc);
void linphone_core_set_rtp_no_xmit_on_audio_mute(LinphoneCore *lc, bool_t val);
+/**
+ * @addtogroup buddy_list
+ * @{
+ */
void linphone_core_set_presence_info(LinphoneCore *lc,int minutes_away,const char *contact,LinphoneOnlineStatus os);
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
+ */
void linphone_core_add_friend(LinphoneCore *lc, LinphoneFriend *fr);
+/**
+ *
+ */
void linphone_core_remove_friend(LinphoneCore *lc, LinphoneFriend *fr);
void linphone_core_reject_subscriber(LinphoneCore *lc, LinphoneFriend *lf);
/* a list of LinphoneFriend */
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);
+/**
+ * @}
+ */
/* returns a list of LinphoneCallLog */
const MSList * linphone_core_get_call_logs(LinphoneCore *lc);
void linphone_core_clear_call_logs(LinphoneCore *lc);
projects / linphone / commitdiff