Yet again large diffs because of documentation/doxygen update
git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@531 74dad513-b988-da41-8d7b-12977e46ad98
diff --git a/pjmedia/include/pjmedia-codec.h b/pjmedia/include/pjmedia-codec.h
index f160ede..3658cb1 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 04f526a..f6d0e99 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 225c092..59e222e 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 a773b39..51b6931 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 9ebd27e..c9bef71 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 6b80d18..6a4be4d 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 edad178..220a863 100644
--- a/pjmedia/include/pjmedia/rtp.h
+++ b/pjmedia/include/pjmedia/rtp.h
@@ -37,7 +37,8 @@
*
* 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 f105c42..4a07cfe 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 b09d69d..9cd2bbc 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 1bd1bd2..d110448 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 @@
+PJ_END_DECL
+
+/**
+ * @}
+ */
#endif /* __PJMEDIA_SPLITCOMB_H__ */
diff --git a/pjmedia/include/pjmedia/wav_port.h b/pjmedia/include/pjmedia/wav_port.h
index 6806f33..99de617 100644
--- a/pjmedia/include/pjmedia/wav_port.h
+++ b/pjmedia/include/pjmedia/wav_port.h
@@ -31,7 +31,7 @@
/**
- * @defgroup PJMEDIA_FILE_PLAY File Player
+ * @defgroup PJMEDIA_FILE_PLAY WAV File Player
* @ingroup PJMEDIA_PORT
* @brief WAV File Player
* @{
@@ -77,18 +77,52 @@
/**
- * 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 @@
* @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 @@
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));
+
/**
* @}