From d36a324b7bd2d6246fcb230ceaf8fbb5d0725768 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Grisez?= Date: Thu, 5 Apr 2018 14:45:04 +0200 Subject: [PATCH] Add source code examples --- coreapi/help/doc/sphinx/CMakeLists.txt | 4 + .../help/doc/sphinx/guides/call_control.rst | 2 +- coreapi/help/doc/sphinx/guides/chatroom.rst | 2 +- coreapi/help/doc/sphinx/guides/proxies.rst | 2 +- coreapi/help/doc/sphinx/index.rst | 3 + coreapi/help/doc/sphinx/samples/samples.rst | 106 ++++++++++++++++++ coreapi/help/examples/C/CMakeLists.txt | 14 ++- 7 files changed, 128 insertions(+), 5 deletions(-) create mode 100644 coreapi/help/doc/sphinx/samples/samples.rst diff --git a/coreapi/help/doc/sphinx/CMakeLists.txt b/coreapi/help/doc/sphinx/CMakeLists.txt index df0cee4e7..e3b9a250e 100644 --- a/coreapi/help/doc/sphinx/CMakeLists.txt +++ b/coreapi/help/doc/sphinx/CMakeLists.txt @@ -57,12 +57,16 @@ if (ENABLE_SPHINX_DOC) guides/proxies.rst index.rst logo.png + samples/samples.rst toc.rst ) configure_file(conf.py.in source/conf.py) foreach(file ${STATIC_DOCUMENTATION_FILES}) configure_file(${file} source/${file} COPYONLY) endforeach(file) + foreach(source ${LINPHONE_C_EXAMPLES_SOURCE}) + configure_file(${source} source/samples/ COPYONLY) + endforeach(source) 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/guides/call_control.rst b/coreapi/help/doc/sphinx/guides/call_control.rst index 81567befa..e6e959348 100644 --- a/coreapi/help/doc/sphinx/guides/call_control.rst +++ b/coreapi/help/doc/sphinx/guides/call_control.rst @@ -6,4 +6,4 @@ The :cpp:type:`LinphoneCall` object represents an incoming or outgoing call mana 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". +.. seealso:: :ref:`"Basic Call" ` source code. diff --git a/coreapi/help/doc/sphinx/guides/chatroom.rst b/coreapi/help/doc/sphinx/guides/chatroom.rst index e8ccb2399..5d391845c 100644 --- a/coreapi/help/doc/sphinx/guides/chatroom.rst +++ b/coreapi/help/doc/sphinx/guides/chatroom.rst @@ -24,5 +24,5 @@ Incoming message are received from call back LinphoneCoreVTable.text_received 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" +.. seealso:: A complete tutorial can be found at :ref:`"Chatroom and messaging" ` source code. diff --git a/coreapi/help/doc/sphinx/guides/proxies.rst b/coreapi/help/doc/sphinx/guides/proxies.rst index b41734b90..dd852b0b8 100644 --- a/coreapi/help/doc/sphinx/guides/proxies.rst +++ b/coreapi/help/doc/sphinx/guides/proxies.rst @@ -72,5 +72,5 @@ This pseudo code shows how to unregister a user associated to a #LinphoneProxyCo 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" +.. seealso:: A complete tutorial can be found at: :ref:`"Basic registration" ` source code. diff --git a/coreapi/help/doc/sphinx/index.rst b/coreapi/help/doc/sphinx/index.rst index c036cd442..8b6728012 100644 --- a/coreapi/help/doc/sphinx/index.rst +++ b/coreapi/help/doc/sphinx/index.rst @@ -52,7 +52,10 @@ Beginners' guides Code samples ------------ +.. toctree:: + :maxdepth: 1 + samples/samples API's reference documentation diff --git a/coreapi/help/doc/sphinx/samples/samples.rst b/coreapi/help/doc/sphinx/samples/samples.rst new file mode 100644 index 000000000..8d4cc6024 --- /dev/null +++ b/coreapi/help/doc/sphinx/samples/samples.rst @@ -0,0 +1,106 @@ +.. _basic_call_code_sample: + +Basic call +========== + +This program is a *very* simple usage example of liblinphone. It just takes a sip-uri as first argument and attempts to call it + +.. literalinclude:: helloworld.c + :language: c + + +.. _basic_registration_code_sample: + +Basic registration +================== + +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* . Registration is cleared +on *SIGINT*. + +Example: ``registration sip:jehan@sip.linphone.org secret`` + +.. literalinclude:: registration.c + :language: c + + +.. _subscribe_notify_code_sample: + +Generic subscribe/notify example +================================ + +This program is a *very* simple usage example of liblinphone. It demonstrates how to listen to a SIP subscription. +It then sends notify requests back periodically. First argument must be like sip:jehan@sip.linphone.org , second must be *password*. +Registration is cleared on *SIGINT*. + +Example: ``registration sip:jehan@sip.linphone.org secret`` + +.. literalinclude:: registration.c + :language: c + + + +.. _buddy_status_notification_code_sample: + +Basic buddy status notification +=============================== + +This program is a *very* simple usage example of liblinphone, demonstrating how to initiate SIP subscriptions and receive +notifications from a sip uri identity passed from the command line. Argument must be like sip:jehan@sip.linphone.org . +Subscription is cleared on *SIGINT* signal. + +Example: ``budy_list sip:jehan@sip.linphone.org`` + +.. literalinclude:: buddy_status.c + :language: c + + +.. _chatroom_code_sample: + +Chat room and messaging +======================= + +This program is a *very* simple usage example of liblinphone, desmonstrating how to send/receive SIP MESSAGE from a sip uri +identity passed from the command line. Argument must be like sip:jehan@sip.linphone.org . + +Example: ``chatroom sip:jehan@sip.linphone.org`` + +.. literalinclude:: chatroom.c + :language: c + + +.. _file_transfer_code_sample: + +File transfer +============= + +.. literalinclude:: filetransfer.c + :language: c + + + +.. _RT text receiver_code_sample: + +Real Time Text Receiver +======================= + +This program is able to receive chat message in real time on port 5060. Use realtimetext_sender to generate chat message + +Example: ``./realtimetext_receiver`` + +.. literalinclude:: realtimetext_sender.c + :language: c + + +.. _RT_text_sender_code_sample: + +Real Time Text Sender +===================== + +This program just send chat message in real time to dest uri. Use realtimetext_receiver to receive message. + +Example: ``./realtimetext_sender sip:localhost:5060`` + +.. literalinclude:: realtimetext_sender.c + :language: c + diff --git a/coreapi/help/examples/C/CMakeLists.txt b/coreapi/help/examples/C/CMakeLists.txt index e89cde8db..cc0ef95a4 100644 --- a/coreapi/help/examples/C/CMakeLists.txt +++ b/coreapi/help/examples/C/CMakeLists.txt @@ -24,8 +24,18 @@ if (ENABLE_TOOLS) if (IOS) set(USE_BUNDLE MACOSX_BUNDLE) endif() - file(GLOB EXECUTABLES_SOURCE RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} "*.c") - foreach(EXECUTABLE ${EXECUTABLES_SOURCE}) + set(LINPHONE_C_EXAMPLES_SOURCE + ${CMAKE_CURRENT_SOURCE_DIR}/buddy_status.c + ${CMAKE_CURRENT_SOURCE_DIR}/chatroom.c + ${CMAKE_CURRENT_SOURCE_DIR}/filetransfer.c + ${CMAKE_CURRENT_SOURCE_DIR}/helloworld.c + ${CMAKE_CURRENT_SOURCE_DIR}/notify.c + ${CMAKE_CURRENT_SOURCE_DIR}/realtimetext_receiver.c + ${CMAKE_CURRENT_SOURCE_DIR}/realtimetext_sender.c + ${CMAKE_CURRENT_SOURCE_DIR}/registration.c + PARENT_SCOPE + ) + foreach(EXECUTABLE ${LINPHONE_C_EXAMPLES_SOURCE}) string(REPLACE ".c" "" EXECUTABLE_NAME ${EXECUTABLE}) bc_apply_compile_flags(${EXECUTABLE} STRICT_OPTIONS_CPP STRICT_OPTIONS_C) add_executable(${EXECUTABLE_NAME} ${USE_BUNDLE} ${EXECUTABLE})