Commit 9fe6b93c authored by jehan's avatar jehan

add docs for subscribe/notify

parent efa62f1d
......@@ -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 \
......
/*
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;
}
......@@ -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
**/
......
......@@ -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;
......
......@@ -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.
* <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,
......@@ -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);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment