Commit 98baa615 authored by jehan's avatar jehan

enhance docs for proxy management

parent e4a2f0ff
This diff is collapsed.
......@@ -39,7 +39,6 @@ INSTALL
Specfile
.anjuta/
.anjuta_sym_db.db
coreapi/help/doxygen.dox
gtk-glade/version_date.h
share/linphone.desktop
......@@ -468,7 +468,6 @@ pixmaps/Makefile
coreapi/Makefile
coreapi/help/Makefile
coreapi/help/Doxyfile
coreapi/help/doxygen.dox
gtk/Makefile
console/Makefile
share/Makefile
......
EXTRA_DIST = Doxyfile.in doxygen.dox.in
EXTRA_DIST = Doxyfile.in doxygen.dox
SOURCES=$(top_srcdir)/coreapi/*.h $(top_srcdir)/coreapi/*.c
SOURCES= doxygen.dox *.c $(top_srcdir)/coreapi/*.c $(top_srcdir)/coreapi/*.h
#html doc
......@@ -32,7 +32,7 @@ endif
clean-local:
rm -rf doc
noinst_PROGRAMS=helloworld
noinst_PROGRAMS=helloworld registration
helloworld_SOURCES=helloworld.c
......@@ -40,6 +40,13 @@ helloworld_LDADD=$(top_builddir)/coreapi/liblinphone.la \
$(MEDIASTREAMER_LIBS) \
$(ORTP_LIBS)
registration_SOURCES=registration.c
registration_LDADD=$(top_builddir)/coreapi/liblinphone.la \
$(MEDIASTREAMER_LIBS) \
$(ORTP_LIBS)
INCLUDES=-I$(top_srcdir)/coreapi \
$(MEDIASTREAMER_CFLAGS)
......
/**
* @mainpage
*
* @see http://www.linphone.org
*
* @section what_is_it What is liblinphone
*
* Liblinphone is a high level library for bringing SIP video call functionnality
* into an application. It aims at making easy the integration of the SIP
* video calls into any applications. All variants of linphone are directly based
* on it:
* - linphone (gtk interface)
*
* - linphonec (console interface)
*
* Liblinphone is GPL (see COPYING file). Please understand the licencing details
* before using it!
*
* For any use of this library beyond the rights granted to you by the
* GPL license, please contact Belledonne Communications
* (contact@belledonne-communications.com)
*
*
**/
/**
* @page liblinphone_license COPYING
* @verbinclude COPYING
*/
/**
* @defgroup initializing Initializing liblinphone
**/
/**
* @defgroup call_control Placing and receiving calls
**/
/**
* @defgroup media_parameters Controlling media parameters
**/
/**
* @defgroup proxies Managing proxies
*User registration is control by #LinphoneProxyConfig settings.<br> Each #LinphoneProxyConfig object can be configured with registration information
*like \link linphone_proxy_config_set_server_addr() proxy address \endlink , \link linphone_proxy_config_set_identity() user id \endlink, \link linphone_proxy_config_expires() refresh period \endlink, etc
*<br> A created proxy config using linphone_proxy_config_new(), once configured, must be added to #LinphoneCore using function linphone_core_add_proxy_config().
*<br> It is recommended to set a default \link #LinphoneProxyConfig proxy config \endlink using function linphone_core_set_default_proxy(). Once done, if \link #LinphoneProxyConfig a proxy config \endlink has been configured with attribute \link linphone_proxy_config_enable_register() enable register \endlink , next call to linphone_core_iterate() triggers a SIP register.
*<br> Registration status is reported by #LinphoneRegistrationStateCb.
*<br>
*<br> This pseudo code demonstrate basic registration operation:
*<br> \code
*
* LinphoneProxyConfig* proxy_cfg;
* /*create proxy config*/
* proxy_cfg = linphone_proxy_config_new();
* /*parse identity*/
* LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
* LinphoneAuthInfo *info;
* if (password!=NULL){
* info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/
* linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
* }
* // configure proxy entries
* linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
* const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
* linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
* linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
* linphone_address_destroy(from); /*release resource*/
*
* linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
* linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/ \endcode
*<br>
* Registration sate call back:
\code
static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
printf("New registration state %s for user id [%s] at proxy [%s]\n"
,linphone_registration_state_to_string(cstate)
,linphone_proxy_config_get_identity(cfg)
,linphone_proxy_config_get_addr(cfg));
}
\endcode
*<br><b>Authentication:</b>
*<br>Most of the time, registration requires \ref authentication "authentication" to succed. #LinphoneAuthInfo info must be either added to #LinphoneCore using function linphone_core_add_auth_info() before #LinphoneProxyConfig is added to Linphone core, or on demand from call back #AuthInfoRequested .
*<br>
*<br><b>Unregistration:</b>
*<br> Unregistration or any change to #LinphoneProxyConfig must be first started by a call to function linphone_proxy_config_edit() and validated by a call to function linphone_proxy_config_done()
*<br> This pseudo code show how to unregister a user associated to a #LinphoneProxyConfig
*\code
LinphoneProxyConfig* proxy_cfg;
linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/
\endcode
<br>
For more complete tutorial can be found see : \ref registration_tutorials "Registration tutorial"
**/
/**
* @defgroup network_parameters Controlling network parameters (ports, mtu...)
**/
/**
* @defgroup authentication Managing authentication: userid and passwords
**/
/**
* @defgroup call_logs Managing call logs
**/
/**
* @defgroup linphone_address SIP address parser API.
* This api is useful for manipulating SIP addresses ('from' or 'to' headers).
**/
/**
* @defgroup misc Miscenalleous: logs, version strings, config storage
**/
/**
* @defgroup tutorials Tutorials:
*
**/
......@@ -42,6 +42,17 @@
/**
* @defgroup proxies Managing proxies
*User registration is control by #LinphoneProxyConfig settings.<br> Each #LinphoneProxyConfig object can be configured with Registration information like proxy address, user id, refresh period, etc
*<br> A created proxy config using linphone_proxy_config_new(void) once configured #LinphoneProxyConfig must be added to #LinphoneCore using function linphone_core_add_proxy_config().
*<br> It is recommanded to set a default proxy config using function linphone_core_set_default_proxy(). Once done, if proxy config has been configured with attribute enable register linphone_proxy_config_enable_register() , next call to linphone_core_iterate() triggers a SIP registration.
*<br> Registration status is reported by #LinphoneRegistrationStateCb.
*<br>
*<br> This pseudo code demonstrte basic registration operation
*<br>
*<br><b>Authentication</b>
*<br>Most of the time, registration requires \ref authentication "authentication" to succed. #LinphoneAuthInfo info must be either added to #LinphoneCore using function linphone_core_add_auth_info() before #LinphoneProxyConfig is added to Linphone core, or on demand from call back #AuthInfoRequested .
*<br>
*<br><b>Unregistration</b>
**/
/**
......
......@@ -19,9 +19,13 @@ along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
/*
/**
* @defgroup basic_call_tutorials Basic call
* @ingroup tutorials
This program is a _very_ simple usage example of liblinphone.
It just takes a sip-uri as first argument and attempts to call it
@include helloworld.c
*/
#include <linphonecore.h>
......
/*
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 registration_tutorials Basic registration
* @ingroup tutorials
*This program is a _very_ simple usage example of liblinphone.
*Desmonstrating how to initiate a SIP registration from a sip uri identity passed from the command line.
*first argument must be like sip:jehan@sip.linphone.org , second must be password .
*<br>
*ex registration sip:jehan@sip.linphone.org secret
*<br>Registration is cleared on SIGINT
*<br>
*@include registration.c
*
*/
#include "linphonecore.h"
#include <signal.h>
static bool_t running=TRUE;
static void stop(int signum){
running=FALSE;
}
/**
* Registration state notification callback
*/
static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
printf("New registration state %s for user id [%s] at proxy [%s]\n"
,linphone_registration_state_to_string(cstate)
,linphone_proxy_config_get_identity(cfg)
,linphone_proxy_config_get_addr(cfg));
}
LinphoneCore *lc;
int main(int argc, char *argv[]){
LinphoneCoreVTable vtable={0};
char* identity=NULL;
char* password=NULL;
/* takes sip uri identity from the command line arguments */
if (argc>1){
identity=argv[1];
}
/* takes password from the command line arguments */
if (argc>2){
password=argv[2];
}
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.registration_state_changed=registration_state_changed;
/*
Instanciate a LinphoneCore object given the LinphoneCoreVTable
*/
lc=linphone_core_new(&vtable,NULL,NULL,NULL);
LinphoneProxyConfig* proxy_cfg;
/*create proxy config*/
proxy_cfg = linphone_proxy_config_new();
/*parse identity*/
LinphoneAddress *from = linphone_address_new(identity);
if (from==NULL){
printf("%s not a valid sip uri, must be like sip:toto@sip.linphone.org \n",identity);
goto end;
}
LinphoneAuthInfo *info;
if (password!=NULL){
info=linphone_auth_info_new(linphone_address_get_username(from),NULL,password,NULL,NULL); /*create authentication structure from identity*/
linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
}
// configure proxy entries
linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
linphone_address_destroy(from); /*release resource*/
linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/
/* main loop for receiving notifications and doing background linphonecore work: */
while(running){
linphone_core_iterate(lc); /* first iterate initiates registration */
ms_usleep(50000);
}
linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/
while(linphone_proxy_config_get_state(proxy_cfg) == LinphoneRegistrationOk){
linphone_core_iterate(lc); /*to make sure we receive call backs before shutting down*/
ms_usleep(50000);
}
end:
printf("Shutting down...\n");
linphone_core_destroy(lc);
printf("Exited\n");
return 0;
}
......@@ -311,6 +311,10 @@ typedef enum _LinphoneRegistrationState{
LinphoneRegistrationFailed
}LinphoneRegistrationState;
/**
* Human readable version of the #LinphoneRegistrationState
* @param cs sate
*/
const char *linphone_registration_state_to_string(LinphoneRegistrationState cs);
LinphoneProxyConfig *linphone_proxy_config_new(void);
......@@ -318,6 +322,12 @@ int linphone_proxy_config_set_server_addr(LinphoneProxyConfig *obj, const char *
int linphone_proxy_config_set_identity(LinphoneProxyConfig *obj, const char *identity);
int linphone_proxy_config_set_route(LinphoneProxyConfig *obj, const char *route);
void linphone_proxy_config_expires(LinphoneProxyConfig *obj, int expires);
/**
* Indicates either or not, REGISTRATION must be issued for this #LinphoneProxyConfig .
* <br> In case this #LinphoneProxyConfig has been added to #LinphoneCore, follows the linphone_proxy_config_edit() rule.
* @param obj object pointer
* @param val if true, registration will be engaged
*/
void linphone_proxy_config_enable_register(LinphoneProxyConfig *obj, bool_t val);
#define linphone_proxy_config_enableregister linphone_proxy_config_enable_register
void linphone_proxy_config_edit(LinphoneProxyConfig *obj);
......@@ -454,7 +464,9 @@ const char *linphone_global_state_to_string(LinphoneGlobalState gs);
typedef void (*LinphoneGlobalStateCb)(struct _LinphoneCore *lc, LinphoneGlobalState gstate, const char *message);
/**Call state notification callback prototype*/
typedef void (*LinphoneCallStateCb)(struct _LinphoneCore *lc, LinphoneCall *call, LinphoneCallState cstate, const char *message);
/**Registration state notification callback prototype*/
/** @ingroup Proxies
* Registration state notification callback prototype
* */
typedef void (*LinphoneRegistrationStateCb)(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message);
/** Callback prototype */
typedef void (*ShowInterfaceCb)(struct _LinphoneCore *lc);
......@@ -533,7 +545,10 @@ typedef enum _LinphoneWaitingState{
LinphoneWaitingFinished
} LinphoneWaitingState;
typedef void * (*LinphoneWaitingCallback)(struct _LinphoneCore *lc, void *context, LinphoneWaitingState ws, const char *purpose, float progress);
/**
* Linphone core main object created by function linphone_core_new() .
* @ingroup initializing
*/
typedef struct _LinphoneCore LinphoneCore;
/* THE main API */
......
......@@ -6,7 +6,7 @@ AC_REQUIRE([LP_CHECK_OSIP2])
case $target_os in
*darwin*)
OSIP_LIBS="$OSIP_LIBS -framework CoreFoundation -framework CFNetwork "
OSIP_LIBS="$OSIP_LIBS -framework CoreFoundation -framework CoreServices "
;;
esac
......
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