Yet again large diffs because of documentation/doxygen update

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@531 74dad513-b988-da41-8d7b-12977e46ad98

11 files changed, 312 insertions, 18 deletions

diff --git a/pjmedia/include/pjmedia-codec.h b/pjmedia/include/pjmedia-codec.h
index f160edef..3658cb10 100644
--- a/pjmedia/include/pjmedia-codec.h
+++ b/pjmedia/include/pjmedia-codec.h
@@ -19,6 +19,11 @@
 #ifndef __PJMEDIA_CODEC_PJMEDIA_CODEC_H__
 #define __PJMEDIA_CODEC_PJMEDIA_CODEC_H__
 
+/**
+ * @file pjmedia-codec.h
+ * @brief Include all codecs API in PJMEDIA-CODEC
+ */
+
 #include <pjmedia-codec/l16.h>
 #include <pjmedia-codec/gsm.h>
 #include <pjmedia-codec/speex.h>
diff --git a/pjmedia/include/pjmedia-codec/gsm.h b/pjmedia/include/pjmedia-codec/gsm.h
index 04f526ad..f6d0e99f 100644
--- a/pjmedia/include/pjmedia-codec/gsm.h
+++ b/pjmedia/include/pjmedia-codec/gsm.h
@@ -27,7 +27,7 @@
 #include <pjmedia-codec/types.h>
 
 /**
- * @defgroup PJMED_GSM GSM 06.10
+ * @defgroup PJMED_GSM GSM 06.10 Codec
  * @ingroup PJMEDIA_CODEC
  * @brief Implementation of GSM FR based on GSM 06.10 library
  * @{
diff --git a/pjmedia/include/pjmedia-codec/l16.h b/pjmedia/include/pjmedia-codec/l16.h
index 225c0929..59e222e1 100644
--- a/pjmedia/include/pjmedia-codec/l16.h
+++ b/pjmedia/include/pjmedia-codec/l16.h
@@ -23,7 +23,7 @@
 
 
 /**
- * @defgroup PJMED_L16 L16 Family
+ * @defgroup PJMED_L16 L16 Codec Family
  * @ingroup PJMEDIA_CODEC
  * @brief 16bit linear codecs (useful for debugging)
  * @{
diff --git a/pjmedia/include/pjmedia-codec/speex.h b/pjmedia/include/pjmedia-codec/speex.h
index a773b39e..51b6931c 100644
--- a/pjmedia/include/pjmedia-codec/speex.h
+++ b/pjmedia/include/pjmedia-codec/speex.h
@@ -27,7 +27,7 @@
 #include <pjmedia-codec/types.h>
 
 /**
- * @defgroup PJMED_SPEEX Speex
+ * @defgroup PJMED_SPEEX Speex Codec Family
  * @ingroup PJMEDIA_CODEC
  * @brief Implementation of Speex codecs (narrow/wide/ultrawide-band).
  * @{
diff --git a/pjmedia/include/pjmedia/doxygen.h b/pjmedia/include/pjmedia/doxygen.h
index 9ebd27e6..c9bef719 100644
--- a/pjmedia/include/pjmedia/doxygen.h
+++ b/pjmedia/include/pjmedia/doxygen.h
@@ -61,9 +61,63 @@
  * PJMEDIA-CODEC.
  *
  * \n
+ * @section main_page_get_start_sec Getting Started
+ *
+ * For those who likes to just get start coding, the @ref getting_started_pjmedia
+ * may be a good place to start.
+ *
+ * The @ref page_pjmedia_samples page describes some examples that are available
+ * in the source tree.
+ *
+ *
+ * \n
  * @section pjmedia_lic Copying and Acknowledgements
  *
- * Please see @ref lic_stuffs page for the details.
+ * PJMEDIA and PJMEDIA-CODEC contains various parts obtained from other
+ * places, and each of these would have their own licensing terms.
+ * Please see @ref lic_stuffs page for details.
+ *
+ */
+
+/**
+ * @page pjmed_keywords_page Features Index
+ * @section pjmed_keywords Features Index
+ *
+ * <b>PJMEDIA features</b>, in no particular order (click to go to the relevant
+ * documentation): 
+ * @ref lic_stuffs "Open Source media stack", 
+ * @ref PJMEDIA_CLOCK, 
+ * @ref PJMEDIA_CODEC,
+ * @ref enc_dec_codec,
+ * @ref plc_codec, 
+ * @ref PJMEDIA_CONF, 
+ * @ref PJMED_G711 "G711/G.711 (PCMA/PCMU) codec with PLC",
+ * @ref PJMED_GSM "GSM codec with PLC", 
+ * @ref PJMED_L16 "linear codecs (multiple clockrate, stereo support, etc)",
+ * @ref PJMED_SPEEX "Speex codec (narrowband, wideband, ultra-wideband)",
+ * @ref PJMED_JBUF "portable, adaptive jitter buffer with PLC support",
+ * @ref PJMEDIA_MASTER_PORT, 
+ * @ref PJMEDIA_NULL_PORT,
+ * @ref PJMED_PLC, 
+ * @ref PJMEDIA_PORT_CONCEPT, 
+ * @ref PJMEDIA_PORT_CLOCK,
+ * @ref PJMEDIA_RESAMPLE "high quality resampling/sampling rate conversion",
+ * @ref PJMEDIA_RESAMPLE_PORT, 
+ * @ref PJMED_RTCP "small footprint, portable RTCP with media quality statistics",
+ * @ref PJMED_RTP "very small footprint, modular, DSP ready RTP implementation", 
+ * @ref PJMEDIA_SDP "modular, small footprint, open source SDP implementation", 
+ * @ref PJMEDIA_SDP_NEG "modular SDP negotiation/negotiator abstraction",
+ * @ref PJMED_SES "media session abstraction",
+ * @ref PJMEDIA_SILENCEDET,
+ * @ref PJMED_SND "portable audio/sound hardware/device abstraction for Linux, Unix, Windows, DirectSound, WinCE, Windows Mobile, MacOS X, etc.", 
+ * @ref PJMED_SND_PORT,
+ * @ref PJMEDIA_SPLITCOMB, 
+ * @ref PJMED_STRM "remote stream", 
+ * @ref PJMEDIA_TRANSPORT_H "custom media transport abstraction",
+ * @ref PJMEDIA_TRANSPORT_UDP, 
+ * @ref PJMEDIA_FILE_PLAY "WAV/WAVE file playback", 
+ * @ref PJMEDIA_FILE_REC "WAV/WAVE file recording/capture",
+ * @ref PJMEDIA_WAVE "portable WAV/WAVE header manipulation"
  */
 
 
@@ -325,4 +379,141 @@
  *
  */
 
+
+/**
+ @page getting_started_pjmedia Getting Started with PJMEDIA
+ 
+ @section getstart_init_setup_build Setting-up the Build System
+
+ @subsection subsec_build_pjmedia Building PJMEDIA and PJMEDIA-CODEC
+
+ The PJMEDIA and PJMEDIA-CODEC libraries are normally bundled in PJPROJECT
+ source tarball, and they are located in <tt><b>pjmedia</b></tt> sub-directory
+ tree.
+
+ Please follow the instructions in <tt><b>INSTALL.txt</b></tt> in the root
+ PJPROJECT directory to build all projects, including PJMEDIA and PJMEDIA-CODEC.
+
+ @subsection subsec_config_build Setting Up the Build Environment
+
+ In your project, you will need to configure the following.
+ - Add <tt><b>$pjproject/pjmedia/include</b></tt> in the search path for
+   include files.
+ - Add <tt><b>$pjproject/pjmedia/lib</b></tt> in the search path for
+   library files.
+ - Add PJMEDIA and PJMEDIA static libraries in the link command.
+
+ @subsection subsec_inc_pjmedia Include PJMEDIA and PJMEDIA-CODEC in Source Files
+
+ To include all features from PJMEDIA and PJMEDIA-CODEC, use the following:
+
+ \code
+   #include <pjlib.h>
+   #include <pjmedia.h>
+   #include <pjmedia-codec.h>
+ \endcode
+
+ Alternatively, you may include only specific parts of the library (for example
+ to speed up compilation by just a fraction), for example:
+
+ \code
+   #include <pjmedia/conference.h>
+   #include <pjmedia/jbuf.h>
+   #include <pjmedia-codec/speex.h>
+ \endcode
+
+  Note that you need to give <b>"pjmedia/"</b> and <b>"pjmedia-codec/"</b> 
+  prefix to include specific files.
+
+
+ @section getstart_using Using PJMEDIA
+
+  I wish I could explain more, but for now, please have a look at the 
+  @ref page_pjmedia_samples page on some examples.
+ */
+
+/**
+  @page page_pjmedia_samples PJMEDIA and PJMEDIA-CODEC Examples
+
+  @section pjmedia_samples_sec PJMEDIA and PJMEDIA-CODEC Examples
+
+  Please find below some PJMEDIA related examples that may help in giving
+  some more info:
+
+  - @ref page_pjmedia_samples_level_c\n
+    This is a good place to start learning about @ref PJMEDIA_PORT_CONCEPT,
+    as it shows that @ref PJMEDIA_PORT_CONCEPT are only "passive" objects
+    with <tt>get_frame()</tt> and <tt>put_frame()</tt> interface, and
+    someone has to call these to retrieve/store media frames.
+
+  - @ref page_pjmedia_samples_playfile_c\n
+    This example shows that when application connects a media port (in this
+    case a @ref PJMEDIA_FILE_PLAY) to @ref PJMED_SND_PORT, media will flow
+    automatically since the @ref PJMED_SND_PORT provides @ref PJMEDIA_PORT_CLOCK.
+
+  - @ref page_pjmedia_samples_recfile_c\n
+    Demonstrates how to capture audio from microphone to WAV file.
+
+  - @ref page_pjmedia_samples_playsine_c\n
+    Demonstrates how to create a custom @ref PJMEDIA_PORT_CONCEPT (in this
+    case a sine wave generator) and integrate it to PJMEDIA.
+
+  - @ref page_pjmedia_samples_confsample_c\n
+    This demonstrates how to use the @ref PJMEDIA_CONF. The sample program can 
+    open multiple WAV files, and instruct the conference bridge to mix the
+    signal before playing it to the sound device.
+
+  - @ref page_pjmedia_samples_confbench_c\n
+    I use this to benchmark/optimize the conference bridge algorithm, but
+    readers may find the source useful.
+
+  - @ref page_pjmedia_samples_resampleplay_c\n
+    Demonstrates how to use @ref PJMEDIA_RESAMPLE_PORT to change the
+    sampling rate of a media port (in this case, a @ref PJMEDIA_FILE_PLAY).
+
+  - @ref page_pjmedia_samples_sndtest_c\n
+    This program performs some tests to the sound device to get some
+    quality parameters (such as sound jitter and clock drifts).\n
+    Screenshots on WinXP: \image html sndtest.jpg "sndtest screenshot on WinXP"
+
+  - @ref page_pjmedia_samples_streamutil_c\n
+    This example mainly demonstrates how to stream media (in this case a
+    @ref PJMEDIA_FILE_PLAY) to remote peer using RTP.
+
+  - @ref page_pjmedia_samples_siprtp_c\n
+    This is a useful program (integrated with PJSIP) to actively measure 
+    the network quality/impairment parameters by making one or more SIP 
+    calls (or receiving one or more SIP calls) and display the network
+    impairment of each stream direction at the end of the call.
+    The program is able to measure network quality parameters such as
+    jitter, packet lost/reorder/duplicate, round trip time, etc.\n
+    Note that the remote peer MUST support RTCP so that network quality
+    of each direction can be calculated. Using siprtp for both endpoints
+    is recommended.\n
+    Screenshots on WinXP: \image html siprtp.jpg "siprtp screenshot on WinXP"
+
+ */
+
+/**
+ * \page page_pjmedia_samples_siprtp_c Samples: Using SIP and Custom RTP/RTCP to Monitor Quality
+ *
+ * This source is an example to demonstrate using SIP and RTP/RTCP framework
+ * to measure the network quality/impairment from the SIP call. This
+ * program can be used to make calls or to receive calls from other
+ * SIP endpoint (or other siprtp program), and to display the media
+ * quality statistics at the end of the call.
+ *
+ * Note that the remote peer must support RTCP.
+ *
+ * The layout of the program has been designed so that custom reporting
+ * can be generated instead of plain human readable text.
+ *
+ * The source code of the file is pjsip-apps/src/samples/siprtp.c
+ *
+ * Screenshots on WinXP: \image html siprtp.jpg
+ *
+ * \includelineno siprtp.c
+ */
+
 #endif /* __PJMEDIA_DOXYGEN_H__ */
+
diff --git a/pjmedia/include/pjmedia/plc.h b/pjmedia/include/pjmedia/plc.h
index 6b80d18a..6a4be4d2 100644
--- a/pjmedia/include/pjmedia/plc.h
+++ b/pjmedia/include/pjmedia/plc.h
@@ -27,7 +27,7 @@
 #include <pjmedia/types.h>
 
 /**
- * @defgroup PJMED_PLC Packet Lost Concealment
+ * @defgroup PJMED_PLC Packet Lost Concealment (PLC)
  * @ingroup PJMEDIA_FRAME_OP
  * @{
  * This section describes PJMEDIA's implementation of Packet Lost
diff --git a/pjmedia/include/pjmedia/rtp.h b/pjmedia/include/pjmedia/rtp.h
index edad178a..220a8634 100644
--- a/pjmedia/include/pjmedia/rtp.h
+++ b/pjmedia/include/pjmedia/rtp.h
@@ -37,7 +37,8 @@ PJ_BEGIN_DECL
  *
  * The RTP module is designed to be dependent only to PJLIB, it does not depend
  * on any other parts of PJMEDIA library. The RTP module does not even depend
- * on any transports (sockets), to promote even more use.
+ * on any transports (sockets), to promote even more use, such as in DSP
+ * development (where transport may be handled by different processor).
  *
  * An RTCP implementation is available, in separate module. Please see 
  * @ref PJMED_RTCP.
diff --git a/pjmedia/include/pjmedia/sdp_neg.h b/pjmedia/include/pjmedia/sdp_neg.h
index f105c42f..4a07cfe6 100644
--- a/pjmedia/include/pjmedia/sdp_neg.h
+++ b/pjmedia/include/pjmedia/sdp_neg.h
@@ -25,8 +25,9 @@
  * @brief SDP negotiator header file.
  */
 /**
- * @defgroup PJMEDIA_SDP_NEG SDP Negotiator
+ * @defgroup PJMEDIA_SDP_NEG SDP Negotiation
  * @ingroup PJMEDIA_SESSION
+ * @brief Abstraction to perform SDP negotiation
  * @{
  *
  * The header file <b><pjmedia/sdp_neg.h></b> contains the declaration
diff --git a/pjmedia/include/pjmedia/sound.h b/pjmedia/include/pjmedia/sound.h
index b09d69d3..9cd2bbca 100644
--- a/pjmedia/include/pjmedia/sound.h
+++ b/pjmedia/include/pjmedia/sound.h
@@ -30,7 +30,7 @@
 PJ_BEGIN_DECL
 
 /**
- * @defgroup PJMED_SND Sound Hardware Abstraction
+ * @defgroup PJMED_SND Portable Sound Hardware Abstraction
  * @ingroup PJMED_SND_PORT
  * @brief PJMEDIA abstraction for sound device hardware
  * @{
diff --git a/pjmedia/include/pjmedia/splitcomb.h b/pjmedia/include/pjmedia/splitcomb.h
index 1bd1bd23..d1104488 100644
--- a/pjmedia/include/pjmedia/splitcomb.h
+++ b/pjmedia/include/pjmedia/splitcomb.h
@@ -21,6 +21,25 @@
 
 
 /**
+ * @file splitcomb.h
+ * @brief Media channel splitter/combiner port.
+ */
+#include <pjmedia/types.h>
+
+
+/**
+ * @addtogroup PJMEDIA_SPLITCOMB Media channel splitter/combiner
+ * @ingroup PJMEDIA_PORT
+ * @brief Split and combine media channels in media streams
+ * @{
+ * This section describes media port to split and combine media
+ * channels in the stream.
+ */
+
+PJ_BEGIN_DECL
+
+
+/**
  * Create a media splitter/combiner with the specified parameters.
  * A splitter/combiner splits a single stereo/multichannel audio frame into
  * multiple mono audio frames to each channel when put_frame() is called, 
@@ -107,6 +126,11 @@ pjmedia_splitcomb_create_rev_channel( pj_pool_t *pool,
 
 
 
+PJ_END_DECL
+
+/**
+ * @}
+ */
 
 #endif	/* __PJMEDIA_SPLITCOMB_H__ */
 
diff --git a/pjmedia/include/pjmedia/wav_port.h b/pjmedia/include/pjmedia/wav_port.h
index 6806f33f..99de617b 100644
--- a/pjmedia/include/pjmedia/wav_port.h
+++ b/pjmedia/include/pjmedia/wav_port.h
@@ -31,7 +31,7 @@ PJ_BEGIN_DECL
 
 
 /**
- * @defgroup PJMEDIA_FILE_PLAY File Player
+ * @defgroup PJMEDIA_FILE_PLAY WAV File Player
  * @ingroup PJMEDIA_PORT
  * @brief WAV File Player
  * @{
@@ -77,18 +77,52 @@ PJ_DECL(pj_status_t) pjmedia_wav_player_port_create( pj_pool_t *pool,
 
 
 /**
- * Set the play position of WAV player.
+ * Set the file play position of WAV player.
  *
  * @param port		The file player port.
- * @param samples	Sample position (zero as start of file).
+ * @param offset	Playback position in bytes, relative to the start of
+ *			the payload.
  *
  * @return		PJ_SUCCESS on success.
  */
 PJ_DECL(pj_status_t) pjmedia_wav_player_port_set_pos( pjmedia_port *port,
-						      pj_uint32_t samples );
+						      pj_uint32_t offset );
 
 
 /**
+ * Get the file play position of WAV player.
+ *
+ * @param port		The file player port.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_ssize_t) pjmedia_wav_player_port_get_pos( pjmedia_port *port );
+
+
+/**
+ * Register a callback to be called when the file reading has reached the
+ * end of file. If the file is set to play repeatedly, then the callback
+ * will be called multiple times. Note that only one callback can be 
+ * registered for each file port.
+ *
+ * @param port		The file player port.
+ * @param user_data	User data to be specified in the callback. Note that
+ *			this overwrites the user data previously set when
+ *			the file port is created.
+ * @param cb		Callback to be called. If the callback returns non-
+ *			PJ_SUCCESS, the playback will stop. Note that if
+ *			application destroys the file port in the callback,
+ *			it must return non-PJ_SUCCESS here.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) 
+pjmedia_wav_player_set_eof_cb( pjmedia_port *port,
+			       void *user_data,
+			       pj_status_t (*cb)(pjmedia_port *port,
+						 void *usr_data));
+
+/**
  * @}
  */
 
@@ -114,13 +148,13 @@ PJ_DECL(pj_status_t) pjmedia_wav_player_port_set_pos( pjmedia_port *port,
  * @param samples_per_frame Number of samples per frame.
  * @param bits_per_sample   Number of bits per sample (eg 16).
  * @param flags		    Port creation flags (must be 0 at present).
- * @param buff_size	Buffer size to be allocated. If the value is zero or
- *			negative, the port will use default buffer size (which
- *			is about 4KB).
- * @param user_data	User data to be associated with the file writer port.
- * @param p_port	Pointer to receive the file port instance.
+ * @param buff_size	    Buffer size to be allocated. If the value is 
+ *			    zero or negative, the port will use default buffer
+ *			    size (which is about 4KB).
+ * @param user_data	    User data to be associated with the file port.
+ * @param p_port	    Pointer to receive the file port instance.
  *
- * @return		PJ_SUCCESS on success.
+ * @return		    PJ_SUCCESS on success.
  */
 PJ_DECL(pj_status_t) pjmedia_wav_writer_port_create(pj_pool_t *pool,
 						    const char *filename,
@@ -134,6 +168,44 @@ PJ_DECL(pj_status_t) pjmedia_wav_writer_port_create(pj_pool_t *pool,
 						    pjmedia_port **p_port );
 
 
+/**
+ * Get current writing position. Note that this does not necessarily match
+ * the size written to the file, since the WAV writer employs some internal
+ * buffering. Also the value reported here only indicates the payload size
+ * (it does not include the size of the WAV header),
+ *
+ * @param port		The file writer port.
+ *
+ * @return		Positive value to indicate the position (in bytes), 
+ *			or negative value containing the error code.
+ */
+PJ_DECL(pj_ssize_t) pjmedia_wav_writer_port_get_pos( pjmedia_port *port );
+
+
+/**
+ * Register the callback to be called when the file writing has reached
+ * certain size. Application can use this callback, for example, to limit
+ * the size of the output file.
+ *
+ * @param port		The file writer port.
+ * @param pos		The file position on which the callback will be called.
+ * @param user_data	User data to be specified in the callback. Note that
+ *			this overwrites the user data previously set when
+ *			the file port is created.
+ * @param cb		Callback to be called. If the callback returns non-
+ *			PJ_SUCCESS, the writing will stop. Note that if 
+ *			application destroys the port in the callback, it must
+ *			return non-PJ_SUCCESS here.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) 
+pjmedia_wav_writer_port_set_cb( pjmedia_port *port,
+				pj_size_t pos,
+				void *user_data,
+				pj_status_t (*cb)(pjmedia_port *port,
+						  void *usr_data));
+
 
 /**
  * @}