From d0dfd9be6ae8cebd132964d777a174415e5218f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Grisez?= Date: Tue, 3 Apr 2018 17:47:24 +0200 Subject: [PATCH] Adds the static documentation --- coreapi/help/doc/sphinx/CMakeLists.txt | 22 +++++- coreapi/help/doc/sphinx/authentication.rst | 4 + coreapi/help/doc/sphinx/buddy_list.rst | 57 ++++++++++++++ coreapi/help/doc/sphinx/call_control.rst | 9 +++ coreapi/help/doc/sphinx/call_logs.rst | 2 + coreapi/help/doc/sphinx/call_misc.rst | 4 + coreapi/help/doc/sphinx/chatroom.rst | 28 +++++++ coreapi/help/doc/sphinx/conferencing.rst | 21 +++++ coreapi/help/doc/sphinx/event_api.rst | 4 + coreapi/help/doc/sphinx/index.rst | 62 +++++++++++++-- coreapi/help/doc/sphinx/initializing.rst | 4 + coreapi/help/doc/sphinx/linphone_address.rst | 4 + coreapi/help/doc/sphinx/media_parameters.rst | 11 +++ coreapi/help/doc/sphinx/misc.rst | 3 + .../help/doc/sphinx/network_parameters.rst | 2 + coreapi/help/doc/sphinx/proxies.rst | 76 +++++++++++++++++++ 16 files changed, 305 insertions(+), 8 deletions(-) create mode 100644 coreapi/help/doc/sphinx/authentication.rst create mode 100644 coreapi/help/doc/sphinx/buddy_list.rst create mode 100644 coreapi/help/doc/sphinx/call_control.rst create mode 100644 coreapi/help/doc/sphinx/call_logs.rst create mode 100644 coreapi/help/doc/sphinx/call_misc.rst create mode 100644 coreapi/help/doc/sphinx/chatroom.rst create mode 100644 coreapi/help/doc/sphinx/conferencing.rst create mode 100644 coreapi/help/doc/sphinx/event_api.rst create mode 100644 coreapi/help/doc/sphinx/initializing.rst create mode 100644 coreapi/help/doc/sphinx/linphone_address.rst create mode 100644 coreapi/help/doc/sphinx/media_parameters.rst create mode 100644 coreapi/help/doc/sphinx/misc.rst create mode 100644 coreapi/help/doc/sphinx/network_parameters.rst create mode 100644 coreapi/help/doc/sphinx/proxies.rst diff --git a/coreapi/help/doc/sphinx/CMakeLists.txt b/coreapi/help/doc/sphinx/CMakeLists.txt index 05d7159a2..78727b5d5 100644 --- a/coreapi/help/doc/sphinx/CMakeLists.txt +++ b/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) diff --git a/coreapi/help/doc/sphinx/authentication.rst b/coreapi/help/doc/sphinx/authentication.rst new file mode 100644 index 000000000..464997164 --- /dev/null +++ b/coreapi/help/doc/sphinx/authentication.rst @@ -0,0 +1,4 @@ +Managing authentication: userid and passwords +============================================= + + diff --git a/coreapi/help/doc/sphinx/buddy_list.rst b/coreapi/help/doc/sphinx/buddy_list.rst new file mode 100644 index 000000000..c0a0591c5 --- /dev/null +++ b/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 ` or :cpp:func:`status publication ` policy for +this :cpp:type:`friend ` 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 ` 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 `. + +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 ` to :cpp:type:`LinphoneCore`. + + +Handling incoming subscription request +-------------------------------------- + +New incoming subscription requests are process according to :cpp:func:`the incoming subscription policy state ` for subscription +initiated by :cpp:func:`members of the buddy list `. + +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" diff --git a/coreapi/help/doc/sphinx/call_control.rst b/coreapi/help/doc/sphinx/call_control.rst new file mode 100644 index 000000000..81567befa --- /dev/null +++ b/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". diff --git a/coreapi/help/doc/sphinx/call_logs.rst b/coreapi/help/doc/sphinx/call_logs.rst new file mode 100644 index 000000000..cf68f06fe --- /dev/null +++ b/coreapi/help/doc/sphinx/call_logs.rst @@ -0,0 +1,2 @@ +Managing call logs +================== diff --git a/coreapi/help/doc/sphinx/call_misc.rst b/coreapi/help/doc/sphinx/call_misc.rst new file mode 100644 index 000000000..d77b63b60 --- /dev/null +++ b/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. diff --git a/coreapi/help/doc/sphinx/chatroom.rst b/coreapi/help/doc/sphinx/chatroom.rst new file mode 100644 index 000000000..e8ccb2399 --- /dev/null +++ b/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 ` +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" + diff --git a/coreapi/help/doc/sphinx/conferencing.rst b/coreapi/help/doc/sphinx/conferencing.rst new file mode 100644 index 000000000..e89b2e3f7 --- /dev/null +++ b/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. diff --git a/coreapi/help/doc/sphinx/event_api.rst b/coreapi/help/doc/sphinx/event_api.rst new file mode 100644 index 000000000..b45f77fca --- /dev/null +++ b/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. diff --git a/coreapi/help/doc/sphinx/index.rst b/coreapi/help/doc/sphinx/index.rst index 5a34626a7..2ae1a83e8 100644 --- a/coreapi/help/doc/sphinx/index.rst +++ b/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 diff --git a/coreapi/help/doc/sphinx/initializing.rst b/coreapi/help/doc/sphinx/initializing.rst new file mode 100644 index 000000000..c0e46073d --- /dev/null +++ b/coreapi/help/doc/sphinx/initializing.rst @@ -0,0 +1,4 @@ +Initializing liblinphone +======================== + + diff --git a/coreapi/help/doc/sphinx/linphone_address.rst b/coreapi/help/doc/sphinx/linphone_address.rst new file mode 100644 index 000000000..8dacb147e --- /dev/null +++ b/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). diff --git a/coreapi/help/doc/sphinx/media_parameters.rst b/coreapi/help/doc/sphinx/media_parameters.rst new file mode 100644 index 000000000..9a9318a66 --- /dev/null +++ b/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. diff --git a/coreapi/help/doc/sphinx/misc.rst b/coreapi/help/doc/sphinx/misc.rst new file mode 100644 index 000000000..292840e05 --- /dev/null +++ b/coreapi/help/doc/sphinx/misc.rst @@ -0,0 +1,3 @@ +Miscenalleous: logs, version strings, config storage +==================================================== + diff --git a/coreapi/help/doc/sphinx/network_parameters.rst b/coreapi/help/doc/sphinx/network_parameters.rst new file mode 100644 index 000000000..86faebce6 --- /dev/null +++ b/coreapi/help/doc/sphinx/network_parameters.rst @@ -0,0 +1,2 @@ +Controlling network parameters (ports, mtu…) +============================================ diff --git a/coreapi/help/doc/sphinx/proxies.rst b/coreapi/help/doc/sphinx/proxies.rst new file mode 100644 index 000000000..b41734b90 --- /dev/null +++ b/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 `, +:cpp:func:`user id `, :cpp:func:`refresh period `, 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 ` using function :cpp:func:`linphone_core_set_default_proxy`. Once done, +if :cpp:type:`proxy config ` has been configured with attribute :cpp:func:`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 ` 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" +