From 9fe6b93cc6d750648c51dd56d31379462744d091 Mon Sep 17 00:00:00 2001 From: Jehan Monnier Date: Fri, 8 Oct 2010 18:02:51 +0200 Subject: [PATCH] add docs for subscribe/notify --- coreapi/help/Makefile.am | 8 +- coreapi/help/buddy_status.c | 117 ++++++++++++++++++++++++++++++ coreapi/help/doxygen.dox | 5 ++ coreapi/linphonecore.c | 10 +-- coreapi/linphonecore.h | 141 +++++++++++++++++++++++++++++++++--- 5 files changed, 265 insertions(+), 16 deletions(-) create mode 100644 coreapi/help/buddy_status.c diff --git a/coreapi/help/Makefile.am b/coreapi/help/Makefile.am index 3e7eb67b5..c24672180 100644 --- a/coreapi/help/Makefile.am +++ b/coreapi/help/Makefile.am @@ -32,7 +32,7 @@ endif clean-local: rm -rf doc -noinst_PROGRAMS=helloworld registration +noinst_PROGRAMS=helloworld registration buddy_status helloworld_SOURCES=helloworld.c @@ -45,6 +45,12 @@ registration_SOURCES=registration.c registration_LDADD=$(top_builddir)/coreapi/liblinphone.la \ $(MEDIASTREAMER_LIBS) \ $(ORTP_LIBS) + +buddy_status_SOURCES=buddy_status.c + +buddy_status_LDADD=$(top_builddir)/coreapi/liblinphone.la \ + $(MEDIASTREAMER_LIBS) \ + $(ORTP_LIBS) INCLUDES=-I$(top_srcdir)/coreapi \ diff --git a/coreapi/help/buddy_status.c b/coreapi/help/buddy_status.c new file mode 100644 index 000000000..79ecd282a --- /dev/null +++ b/coreapi/help/buddy_status.c @@ -0,0 +1,117 @@ + +/* +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. + *
Argument must be like sip:jehan@sip.linphone.org . + *
+ *ex registration sip:jehan@sip.linphone.org secret + *
Subscription is cleared on SIGINT + *
+ *@include buddy_status.c + + * + */ + +#include "linphonecore.h" + +#include + +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; +} + diff --git a/coreapi/help/doxygen.dox b/coreapi/help/doxygen.dox index 00ab54758..37788e458 100644 --- a/coreapi/help/doxygen.dox +++ b/coreapi/help/doxygen.dox @@ -105,6 +105,11 @@ * @defgroup authentication Managing authentication: userid and passwords **/ +/** +* @defgroup buddy_list Managing Buddies and buddy list +*/ + + /** * @defgroup call_logs Managing call logs **/ diff --git a/coreapi/linphonecore.c b/coreapi/linphonecore.c index 77e79b1a2..79caf88b4 100644 --- a/coreapi/linphonecore.c +++ b/coreapi/linphonecore.c @@ -1965,7 +1965,7 @@ int linphone_core_start_invite(LinphoneCore *lc, LinphoneCall *call, LinphonePro * 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; @@ -1987,7 +1987,7 @@ LinphoneCall * linphone_core_invite(LinphoneCore *lc, const char *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_with_params(LinphoneCore *lc, const char *url, const LinphoneCallParams *p){ LinphoneAddress *addr=linphone_core_interpret_url(lc,url); @@ -2012,7 +2012,7 @@ LinphoneCall * linphone_core_invite_with_params(LinphoneCore *lc, const char *ur * 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; @@ -2036,7 +2036,7 @@ LinphoneCall * linphone_core_invite_address(LinphoneCore *lc, const LinphoneAddr * 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) { @@ -2148,7 +2148,7 @@ bool_t linphone_core_inc_invite_pending(LinphoneCore*lc){ * * 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; diff --git a/coreapi/linphonecore.h b/coreapi/linphonecore.h index e15f6cb44..6dd4acc36 100644 --- a/coreapi/linphonecore.h +++ b/coreapi/linphonecore.h @@ -230,13 +230,30 @@ LinphoneError linphone_call_get_error(const LinphoneCall *call); 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. + *
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, @@ -251,25 +268,107 @@ typedef enum _LinphoneOnlineStatus{ 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); @@ -277,7 +376,9 @@ 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) - +/** + * @} + */ /** * @addtogroup proxies @@ -437,6 +538,7 @@ const char *linphone_auth_info_get_userid(const LinphoneAuthInfo *i); 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; @@ -481,8 +583,12 @@ typedef void (*DisplayUrlCb)(struct _LinphoneCore *lc, const char *message, cons 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 */ @@ -789,12 +895,24 @@ bool_t linphone_core_is_rtp_muted(LinphoneCore *lc); 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 */ @@ -804,6 +922,9 @@ 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); +/** + * @} + */ /* returns a list of LinphoneCallLog */ const MSList * linphone_core_get_call_logs(LinphoneCore *lc); void linphone_core_clear_call_logs(LinphoneCore *lc);