Adds the static documentation

coreapi/help/doc/sphinx/CMakeLists.txt

@@ -39,9 +39,27 @@ if (ENABLE_SPHINX_DOC)
 		enum_page.mustache
 		index_page.mustache
 	)
+	set(STATIC_DOCUMENTATION_FILES authentication.rst
+		buddy_list.rst
+		call_control.rst
+		call_logs.rst
+		call_misc.rst
+		chatroom.rst
+		conferencing.rst
+		event_api.rst
+		index.rst
+		initializing.rst
+		linphone_address.rst
+		logo.png
+		media_parameters.rst
+		misc.rst
+		network_parameters.rst
+		proxies.rst
+	)
 	configure_file(conf.py.in source/conf.py)
-	configure_file(index.rst source/index.rst COPYONLY)
-	configure_file(logo.png source/logo.png COPYONLY)
+	foreach(file ${STATIC_DOCUMENTATION_FILES})
+		configure_file(${file} source/${files} COPYONLY)
+	endforeach(file)
 	add_custom_target(sphinx-doc ALL ${PYTHON_EXECUTABLE} '${CMAKE_CURRENT_SOURCE_DIR}/gendoc.py' '${LINPHONE_DOXYGEN_XML_DIR}' -o 'source'
 		COMMAND ${PYTHON_EXECUTABLE} -msphinx -M html 'source' 'build'
 		DEPENDS linphone-doc)

coreapi/help/doc/sphinx/authentication.rst

@@ -0,0 +1,4 @@
+Managing authentication: userid and passwords
+=============================================
+
+

coreapi/help/doc/sphinx/buddy_list.rst

@@ -0,0 +1,57 @@
+Managing Buddies and buddy list and presence
+============================================
+Buddies and buddy list
+----------------------
+
+Each buddy is represented by a :cpp:type:`LinphoneFriend` object created by function :cpp:func:`linphone_friend_new`.
+
+Buddy configuration parameters like :cpp:func:`sip uri <linphone_friend_set_addr>` or :cpp:func:`status publication <linphone_friend_set_inc_subscribe_policy>` policy for
+this :cpp:type:`friend <LinphoneFriend>` are configurable for each buddy.
+
+Here under a typical buddy creation:
+
+.. code-block:: c
+
+	LinphoneFriend* my_friend=linphone_friend_new_with_addr("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
+	linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
+	linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/
+
+:cpp:type:`Friends <LinphoneFriend>` status changes are reported by callback LinphoneCoreVTable.notify_presence_recv
+
+.. code-block:: c
+
+	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));
+	}
+
+Once created a buddy can be added to the buddy list using function :cpp:func:`linphone_core_add_friend`. Added friends will be notified
+about :cpp:func:`local status changes <linphone_core_set_presence_info>`.
+
+Any subsequente modifications to :cpp:type:`LinphoneFriend` must be first started by a call to function :cpp:func:`linphone_friend_edit` and validated by function :cpp:func:`linphone_friend_done`.
+
+.. code-block:: c
+
+	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*/
+
+
+Publishing presence status
+--------------------------
+
+Local presence status can be changed using function :cpp:func:`linphone_core_set_presence_model`. New status is propagated to all
+friends :cpp:func:`previously added <linphone_core_add_friend>` to :cpp:type:`LinphoneCore`.
+
+
+Handling incoming subscription request
+--------------------------------------
+
+New incoming subscription requests are process according to :cpp:func:`the incoming subscription policy state <linphone_friend_set_inc_subscribe_policy>` for subscription
+initiated by :cpp:func:`members of the buddy list <linphone_core_add_friend>`.
+
+For incoming request comming from an unknown buddy, the call back LinphoneCoreVTable.new_subscription_request is invoked.
+
+A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial"

coreapi/help/doc/sphinx/call_control.rst

@@ -0,0 +1,9 @@
+Placing and receiving calls
+===========================
+
+The :cpp:type:`LinphoneCall` object represents an incoming or outgoing call managed by the :cpp:type:`LinphoneCore`.
+
+Outgoing calls can be created using :cpp:func:`linphone_core_invite` or :cpp:func:`linphone_core_invite_address`, while incoming calls are notified to the application
+through the LinphoneCoreVTable::call_state_changed callback.
+
+See the basic call \ref basic_call_tutorials "tutorial".

coreapi/help/doc/sphinx/call_logs.rst

@@ -0,0 +1,2 @@
+Managing call logs
+==================

coreapi/help/doc/sphinx/call_misc.rst

@@ -0,0 +1,4 @@
+Obtaining information about a running call: sound volumes, quality indicators
+=============================================================================
+
+When a call is running, it is possible to retrieve in real time current measured volumes and quality indicator.

coreapi/help/doc/sphinx/chatroom.rst

@@ -0,0 +1,28 @@
+Chat room and messaging
+=======================
+Exchanging text messages
+------------------------
+
+Messages are sent using :cpp:type:`LinphoneChatRoom` object. First step is to create a :cpp:func:`chat room <linphone_core_get_chat_room>`
+from a peer sip uri.
+
+.. code-block:: c
+
+	LinphoneChatRoom* chat_room = linphone_core_get_chat_room(lc,"sip:joe@sip.linphone.org");
+
+Once created, messages are sent using function :cpp:func:`linphone_chat_room_send_message`.
+
+.. code-block:: c
+
+	linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/
+
+Incoming message are received from call back LinphoneCoreVTable.text_received
+
+.. code-block:: c
+
+	void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) {
+		printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from));
+	}
+
+A complete tutorial can be found at : \ref chatroom_tuto "Chat room tutorial"
+

coreapi/help/doc/sphinx/conferencing.rst

@@ -0,0 +1,21 @@
+Making an audio conference
+==========================
+
+This API allows to create a conference entirely managed by the client. No server capabilities are required.
+
+The way such conference is created is by doing the following:
+
+#. The application shall makes "normal" calls to several destinations (using :cpp:func:`linphone_core_invite`), one after another.
+#. While initiating the second call, the first one is automatically paused.
+#. Then, once the second call is established, the application has the possibility to merge the two calls to form a conference where each participant
+   (the local participant, the remote destination of the first call, the remote destination of the second call) can talk together.
+   This must be done by adding the two calls to the conference using :cpp:func:`linphone_core_add_to_conference`.
+
+Once merged into a conference the :cpp:type:`LinphoneCall` objects representing the calls that were established remain unchanged, except that
+they are tagged as part of the conference (see :cpp:func:`linphone_call_is_in_conference`). The calls in a conference are in the :cpp:enumerator:`LinphoneCallStreamsRunning` state.
+
+Only a single conference can be created: the purpose of this feature is to allow the local user to create, take part and manage the conference.
+This API is not designed to create a conference server application.
+
+Up to 10 calls can be merged into the conference, however depending on the CPU usage required for doing the encoding/decoding of the streams of each participants,
+the effective limit can be lower.

coreapi/help/doc/sphinx/event_api.rst

@@ -0,0 +1,4 @@
+Managing generic subscriptions and publishes
+============================================
+
+The :cpp:type:`LinphoneEvent` api allows application to control subscriptions, receive notifications and make publish to peers, in a generic manner.

coreapi/help/doc/sphinx/index.rst

@@ -5,12 +5,62 @@
 
 Welcome to Linphone API's documentation!
 ========================================
+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)
+* linphone for iOS
+* linphone for Android
+
+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).
+
+
+Beginners' guides
+-----------------
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+	:maxdepth: 1
+
+	initializing
+	call_control
+	call_misc
+	media_parameters
+	proxies
+	network_parameters
+	authentication
+	buddy_list
+	chatroom
+	call_logs
+	linphone_address
+	conferencing
+	event_api
+	misc
+
+
+Code samples
+------------
+
+
+
+
+API's reference documentation
+-----------------------------
+
+.. toctree::
+   :maxdepth: 1
    
-   c/index.rst
-   cpp/index.rst
-   java/index.rst
-   csharp/index.rst
+   c/index
+   cpp/index
+   java/index
+   csharp/index

coreapi/help/doc/sphinx/initializing.rst

@@ -0,0 +1,4 @@
+Initializing liblinphone
+========================
+
+

coreapi/help/doc/sphinx/linphone_address.rst

@@ -0,0 +1,4 @@
+SIP address parser API
+======================
+
+This api is useful for manipulating SIP addresses ('from' or 'to' headers).

coreapi/help/doc/sphinx/media_parameters.rst

@@ -0,0 +1,11 @@
+Controlling media parameters
+============================
+
+Multicast
+---------
+
+Call using rtp multicast addresses are supported for both audio and video with some limitations. Limitations are, no stun, no ice, no encryption.
+
+* Incoming call with multicast address are automatically accepted. The called party switches in a media receive only mode.
+* Outgoing call willing to send media to a multicast address can activate multicast using :cpp:func:`linphone_core_enable_video_multicast`
+  or :cpp:func:`linphone_core_enable_audio_multicast`. The calling party switches in a media listen send only mode.

coreapi/help/doc/sphinx/misc.rst

@@ -0,0 +1,3 @@
+Miscenalleous: logs, version strings, config storage
+====================================================
+

coreapi/help/doc/sphinx/network_parameters.rst

@@ -0,0 +1,2 @@
+Controlling network parameters (ports, mtu…)
+============================================

coreapi/help/doc/sphinx/proxies.rst

@@ -0,0 +1,76 @@
+Managing proxies
+================
+
+User registration is controled by  :cpp:type:`LinphoneProxyConfig` settings.
+
+Each :cpp:type:`LinphoneProxyConfig` object can be configured with registration informations like :cpp:func:`proxy address <linphone_proxy_config_set_server_addr>`,
+:cpp:func:`user id <linphone_proxy_config_set_identity>`, :cpp:func:`refresh period <linphone_proxy_config_expires>`, and so on.
+
+A created proxy config using :cpp:func:`linphone_proxy_config_new`, once configured, must be added to :cpp:type:`LinphoneCore` using function :cpp:func:`linphone_core_add_proxy_config`.
+
+It is recommended to set a default :cpp:type:`proxy config <LinphoneProxyConfig>` using function :cpp:func:`linphone_core_set_default_proxy`. Once done,
+if :cpp:type:`proxy config <LinphoneProxyConfig>` has been configured with attribute :cpp:func:`enable register <linphone_proxy_config_enable_register>`,
+next call to :cpp:func:`linphone_core_iterate` triggers SIP register.
+
+Registration status is reported by LinphoneCoreRegistrationStateChangedCb.
+
+This pseudo code demonstrates basic registration operations:
+
+.. code-block:: c
+
+	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*/
+
+Registration sate call back:
+
+.. code-block:: c
+
+	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));
+	}
+
+Authentication
+--------------
+
+Most of the time, registration requires :doc:`authentication <authentication>` to succeed. :cpp:type:`LinphoneAuthInfo` info must be either added
+to :cpp:type:`LinphoneCore` using function :cpp:func:`linphone_core_add_auth_info` before :cpp:type:`LinphoneProxyConfig` is added to Linphone core, or on demand
+from call back #LinphoneCoreAuthInfoRequestedCb.
+
+Unregistration
+--------------
+
+Unregistration or any changes to :cpp:type:`LinphoneProxyConfig` must be first started by a call to function :cpp:func:`linphone_proxy_config_edit` and validated by
+function :cpp:func:`linphone_proxy_config_done`.
+
+This pseudo code shows how to unregister a user associated to a #LinphoneProxyConfig:
+
+.. code-block:: c
+
+	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*/
+
+A complete tutorial can be found at : \ref registration_tutorials "Registration tutorial"
+