From 98baa615da37276c8662c1c257687e0d6b3e82f0 Mon Sep 17 00:00:00 2001 From: Jehan Monnier Date: Thu, 7 Oct 2010 16:54:26 +0200 Subject: [PATCH] enhance docs for proxy management --- .cproject | 455 ++++++++++++++++++------------------ .gitignore | 1 - configure.ac | 1 - coreapi/help/Makefile.am | 13 +- coreapi/help/doxygen.dox | 128 ++++++++++ coreapi/help/doxygen.dox.in | 11 + coreapi/help/helloworld.c | 6 +- coreapi/help/registration.c | 138 +++++++++++ coreapi/linphonecore.h | 19 +- m4/exosip.m4 | 2 +- 10 files changed, 538 insertions(+), 236 deletions(-) create mode 100644 coreapi/help/doxygen.dox create mode 100644 coreapi/help/registration.c diff --git a/.cproject b/.cproject index 869153cf..3ccb2595 100644 --- a/.cproject +++ b/.cproject @@ -2,231 +2,232 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -make -all -true -true -true - - -make - -install -true -true -true - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + make + + all + true + false + true + + + make + install + true + true + true + + + + + + + + diff --git a/.gitignore b/.gitignore index 7de3a426..a8905782 100644 --- a/.gitignore +++ b/.gitignore @@ -39,7 +39,6 @@ INSTALL Specfile .anjuta/ .anjuta_sym_db.db -coreapi/help/doxygen.dox gtk-glade/version_date.h share/linphone.desktop diff --git a/configure.ac b/configure.ac index 0ab60928..b7863a4b 100644 --- a/configure.ac +++ b/configure.ac @@ -468,7 +468,6 @@ pixmaps/Makefile coreapi/Makefile coreapi/help/Makefile coreapi/help/Doxyfile -coreapi/help/doxygen.dox gtk/Makefile console/Makefile share/Makefile diff --git a/coreapi/help/Makefile.am b/coreapi/help/Makefile.am index 0cdd3f8f..3e7eb67b 100644 --- a/coreapi/help/Makefile.am +++ b/coreapi/help/Makefile.am @@ -1,7 +1,7 @@ -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) diff --git a/coreapi/help/doxygen.dox b/coreapi/help/doxygen.dox new file mode 100644 index 00000000..00ab5475 --- /dev/null +++ b/coreapi/help/doxygen.dox @@ -0,0 +1,128 @@ +/** + * @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.
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 + *
A created proxy config using linphone_proxy_config_new(), once configured, must be added to #LinphoneCore using function linphone_core_add_proxy_config(). + *
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. + *
Registration status is reported by #LinphoneRegistrationStateCb. + *
+ *
This pseudo code demonstrate basic registration operation: + *
\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 + *
+ * 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 + *
Authentication: + *
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 . + *
+ *
Unregistration: + *
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() + *
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 +
+ 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: + * +**/ + + + diff --git a/coreapi/help/doxygen.dox.in b/coreapi/help/doxygen.dox.in index cb05e05d..81b9a698 100644 --- a/coreapi/help/doxygen.dox.in +++ b/coreapi/help/doxygen.dox.in @@ -42,6 +42,17 @@ /** * @defgroup proxies Managing proxies + *User registration is control by #LinphoneProxyConfig settings.
Each #LinphoneProxyConfig object can be configured with Registration information like proxy address, user id, refresh period, etc + *
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(). + *
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. + *
Registration status is reported by #LinphoneRegistrationStateCb. + *
+ *
This pseudo code demonstrte basic registration operation + *
+ *
Authentication + *
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 . + *
+ *
Unregistration **/ /** diff --git a/coreapi/help/helloworld.c b/coreapi/help/helloworld.c index 77eda06d..ce874d6d 100644 --- a/coreapi/help/helloworld.c +++ b/coreapi/help/helloworld.c @@ -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 diff --git a/coreapi/help/registration.c b/coreapi/help/registration.c new file mode 100644 index 00000000..23b70e82 --- /dev/null +++ b/coreapi/help/registration.c @@ -0,0 +1,138 @@ + +/* +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 . + *
+ *ex registration sip:jehan@sip.linphone.org secret + *
Registration is cleared on SIGINT + *
+ *@include registration.c + + * + */ + +#include "linphonecore.h" + +#include + +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; +} + diff --git a/coreapi/linphonecore.h b/coreapi/linphonecore.h index f536bdd7..7647df8b 100644 --- a/coreapi/linphonecore.h +++ b/coreapi/linphonecore.h @@ -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 . + *
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 */ diff --git a/m4/exosip.m4 b/m4/exosip.m4 index fb75e672..725def2b 100644 --- a/m4/exosip.m4 +++ b/m4/exosip.m4 @@ -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 -- 2.39.2