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/docs/doxygen.cfg b/pjmedia/docs/doxygen.cfg
index 1a466a4..5397ade 100644
--- a/pjmedia/docs/doxygen.cfg
+++ b/pjmedia/docs/doxygen.cfg
@@ -345,7 +345,7 @@
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = include
+INPUT = include ../pjsip-apps/src/samples
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -354,7 +354,7 @@
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
# *.h++ *.idl *.odl
-FILE_PATTERNS = *.h
+FILE_PATTERNS = *.h *.c
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
@@ -383,7 +383,7 @@
# directories that contain example code fragments that are included (see
# the \include command).
-EXAMPLE_PATH =
+EXAMPLE_PATH = ../pjsip-apps/src/samples
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
diff --git a/pjmedia/docs/siprtp.jpg b/pjmedia/docs/siprtp.jpg
new file mode 100644
index 0000000..975f1fa
--- /dev/null
+++ b/pjmedia/docs/siprtp.jpg
Binary files differ
diff --git a/pjmedia/docs/sndtest.jpg b/pjmedia/docs/sndtest.jpg
new file mode 100644
index 0000000..ba1ab98
--- /dev/null
+++ b/pjmedia/docs/sndtest.jpg
Binary files differ
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));
+
/**
* @}
diff --git a/pjmedia/src/pjmedia/conference.c b/pjmedia/src/pjmedia/conference.c
index abf522b..7c4ed92 100644
--- a/pjmedia/src/pjmedia/conference.c
+++ b/pjmedia/src/pjmedia/conference.c
@@ -1055,7 +1055,7 @@
(int)cport->name.slen, cport->name.ptr,
count));
- status = (cport->port->get_frame)(cport->port, &f);
+ status = pjmedia_port_get_frame(cport->port, &f);
*type = f.type;
@@ -1460,6 +1460,10 @@
*/
continue;
}
+
+ /* Check that the port is not removed when we call get_frame() */
+ if (conf->ports[i] == NULL)
+ continue;
}
/* If we need to adjust the RX level from this port, adjust the level
diff --git a/pjmedia/src/pjmedia/wav_player.c b/pjmedia/src/pjmedia/wav_player.c
index e7c3df4..8261f08 100644
--- a/pjmedia/src/pjmedia/wav_player.c
+++ b/pjmedia/src/pjmedia/wav_player.c
@@ -30,7 +30,7 @@
#define THIS_FILE "wav_player.c"
-#define SIGNATURE ('F'<<24|'P'<<16|'L'<<8|'Y')
+#define SIGNATURE PJMEDIA_PORT_SIGNATURE('F', 'P', 'l', 'y')
#define BYTES_PER_SAMPLE 2
@@ -65,6 +65,7 @@
pj_off_t fpos;
pj_oshandle_t fd;
+ pj_status_t (*cb)(pjmedia_port*, void*);
};
@@ -116,9 +117,9 @@
pj_ssize_t size;
pj_status_t status;
- if (fport->eof) {
+ /* Can't read file if EOF and loop flag is disabled */
+ if (fport->eof)
return PJ_EEOF;
- }
while (size_left > 0) {
@@ -141,6 +142,27 @@
* encountered EOF. Rewind the file.
*/
if (size < (pj_ssize_t)size_to_read) {
+ /* Call callback, if any. */
+ if (fport->cb) {
+ PJ_LOG(5,(THIS_FILE,
+ "File port %.*s EOF, calling callback",
+ (int)fport->base.info.name.slen,
+ fport->base.info.name.ptr));
+
+ fport->eof = PJ_TRUE;
+ status = (*fport->cb)(&fport->base, fport->base.user_data);
+ if (status != PJ_SUCCESS) {
+ /* This will crash if file port is destroyed in the
+ * callback, that's why we set the eof flag before
+ * calling the callback:
+ fport->eof = PJ_TRUE;
+ */
+ return status;
+ }
+
+ fport->eof = PJ_FALSE;
+ }
+
if (fport->options & PJMEDIA_FILE_NO_LOOP) {
PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, stopping..",
(int)fport->base.info.name.slen,
@@ -335,19 +357,23 @@
* Set position.
*/
PJ_DEF(pj_status_t) pjmedia_wav_player_port_set_pos(pjmedia_port *port,
- pj_uint32_t samples )
+ pj_uint32_t bytes )
{
struct file_port *fport;
- PJ_ASSERT_RETURN(port, PJ_EINVAL);
+ /* Sanity check */
+ PJ_ASSERT_RETURN(port, -PJ_EINVAL);
+
+ /* Check that this is really a player port */
+ PJ_ASSERT_RETURN(port->info.signature == SIGNATURE, -PJ_EINVALIDOP);
+
fport = (struct file_port*) port;
- PJ_ASSERT_RETURN(samples*BYTES_PER_SAMPLE < fport->fsize -
- sizeof(pjmedia_wave_hdr), PJ_EINVAL);
+ PJ_ASSERT_RETURN(bytes < fport->fsize - sizeof(pjmedia_wave_hdr),
+ PJ_EINVAL);
- fport->fpos = sizeof(struct pjmedia_wave_hdr) +
- samples * BYTES_PER_SAMPLE;
+ fport->fpos = sizeof(struct pjmedia_wave_hdr) + bytes;
pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET);
fport->eof = PJ_FALSE;
@@ -356,6 +382,58 @@
/*
+ * Get the file play position of WAV player.
+ */
+PJ_DEF(pj_ssize_t) pjmedia_wav_player_port_get_pos( pjmedia_port *port )
+{
+ struct file_port *fport;
+ pj_size_t payload_pos;
+
+ /* Sanity check */
+ PJ_ASSERT_RETURN(port, -PJ_EINVAL);
+
+ /* Check that this is really a player port */
+ PJ_ASSERT_RETURN(port->info.signature == SIGNATURE, -PJ_EINVALIDOP);
+
+ fport = (struct file_port*) port;
+
+ payload_pos = (pj_size_t)(fport->fpos - sizeof(pjmedia_wave_hdr));
+ if (payload_pos >= fport->bufsize)
+ return payload_pos - fport->bufsize + (fport->readpos - fport->buf);
+ else
+ return (fport->readpos - fport->buf) % payload_pos;
+}
+
+
+
+/*
+ * Register a callback to be called when the file reading has reached the
+ * end of file.
+ */
+PJ_DEF(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))
+{
+ struct file_port *fport;
+
+ /* Sanity check */
+ PJ_ASSERT_RETURN(port, -PJ_EINVAL);
+
+ /* Check that this is really a player port */
+ PJ_ASSERT_RETURN(port->info.signature == SIGNATURE, -PJ_EINVALIDOP);
+
+ fport = (struct file_port*) port;
+
+ fport->base.user_data = user_data;
+ fport->cb = cb;
+
+ return PJ_SUCCESS;
+}
+
+
+/*
* Put frame to file.
*/
static pj_status_t file_put_frame(pjmedia_port *this_port,
diff --git a/pjmedia/src/pjmedia/wav_writer.c b/pjmedia/src/pjmedia/wav_writer.c
index 24816b2..a4b4f74 100644
--- a/pjmedia/src/pjmedia/wav_writer.c
+++ b/pjmedia/src/pjmedia/wav_writer.c
@@ -28,7 +28,7 @@
#define THIS_FILE "wav_writer.c"
-#define SIGNATURE ('F'<<24|'W'<<16|'R'<<8|'T')
+#define SIGNATURE PJMEDIA_PORT_SIGNATURE('F', 'W', 'R', 'T')
#define BYTES_PER_SAMPLE 2
@@ -38,8 +38,12 @@
pj_size_t bufsize;
char *buf;
char *writepos;
+ pj_size_t total;
pj_oshandle_t fd;
+
+ pj_size_t cb_size;
+ pj_status_t (*cb)(pjmedia_port*, void*);
};
static pj_status_t file_put_frame(pjmedia_port *this_port,
@@ -177,6 +181,54 @@
}
+
+/*
+ * Get current writing position.
+ */
+PJ_DEF(pj_ssize_t) pjmedia_wav_writer_port_get_pos( pjmedia_port *port )
+{
+ struct file_port *fport;
+
+ /* Sanity check */
+ PJ_ASSERT_RETURN(port, -PJ_EINVAL);
+
+ /* Check that this is really a writer port */
+ PJ_ASSERT_RETURN(port->info.signature == SIGNATURE, -PJ_EINVALIDOP);
+
+ fport = (struct file_port*) port;
+
+ return fport->total;
+}
+
+
+/*
+ * Register callback.
+ */
+PJ_DEF(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))
+{
+ struct file_port *fport;
+
+ /* Sanity check */
+ PJ_ASSERT_RETURN(port && cb, PJ_EINVAL);
+
+ /* Check that this is really a writer port */
+ PJ_ASSERT_RETURN(port->info.signature == SIGNATURE, PJ_EINVALIDOP);
+
+ fport = (struct file_port*) port;
+
+ fport->cb_size = pos;
+ fport->base.user_data = user_data;
+ fport->cb = cb;
+
+ return PJ_SUCCESS;
+}
+
+
#if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
static void swap_samples(pj_int16_t *samples, unsigned count)
{
@@ -234,6 +286,19 @@
pj_memcpy(fport->writepos, frame->buf, frame->size);
fport->writepos += frame->size;
+ /* Increment total written, and check if we need to call callback */
+ fport->total += frame->size;
+ if (fport->cb && fport->total >= fport->cb_size) {
+ pj_status_t (*cb)(pjmedia_port*, void*);
+ pj_status_t status;
+
+ cb = fport->cb;
+ fport->cb = NULL;
+
+ status = (*cb)(this_port, this_port->user_data);
+ return status;
+ }
+
return PJ_SUCCESS;
}
diff --git a/pjsip-apps/src/samples/confbench.c b/pjsip-apps/src/samples/confbench.c
index 2dae32b..26a0fac 100644
--- a/pjsip-apps/src/samples/confbench.c
+++ b/pjsip-apps/src/samples/confbench.c
@@ -17,11 +17,19 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
-/*
+
+/**
+ * \page page_pjmedia_samples_confbench_c Samples: Benchmarking Conference Bridge
+ *
* Benchmarking pjmedia (conference bridge+resample). For my use only,
* and it only works in Win32.
+ *
+ * This file is pjsip-apps/src/samples/confbench.c
+ *
+ * \includelineno confbench.c
*/
+
#include <pjmedia.h>
#include <pjlib-util.h> /* pj_getopt */
#include <pjlib.h>
@@ -38,8 +46,8 @@
* HAS_RESAMPLE will activate resampling on about half
* the port.
*/
-#define TEST_SET SMALL_SET
-#define HAS_RESAMPLE 1
+#define TEST_SET LARGE_SET
+#define HAS_RESAMPLE 0
#define SMALL_SET 16
@@ -265,7 +273,10 @@
return 1;
}
+ printf("Resampling is %s\n", (HAS_RESAMPLE?"active":"disabled"));
+
/* Create Null ports */
+ printf("Creating %d null ports..\n", NULL_COUNT);
for (i=0; i<NULL_COUNT; ++i) {
status = pjmedia_null_port_create(pool, CLOCK_RATE, 1, SAMPLES_PER_FRAME*2, 16, &nulls[i]);
PJ_ASSERT_RETURN(status == PJ_SUCCESS, 1);
@@ -275,6 +286,7 @@
}
/* Create sine ports. */
+ printf("Creating %d sine generator ports..\n", SINE_COUNT);
for (i=0; i<SINE_COUNT; ++i) {
unsigned j, slot;
@@ -304,6 +316,7 @@
}
/* Create idle ports */
+ printf("Creating %d idle ports..\n", IDLE_COUNT);
for (i=0; i<IDLE_COUNT; ++i) {
pjmedia_port *dummy;
status = pjmedia_null_port_create(pool, CLOCK_RATE, 1, SAMPLES_PER_FRAME, 16, &dummy);
diff --git a/pjsip-apps/src/samples/confsample.c b/pjsip-apps/src/samples/confsample.c
index 7ae80cd..d87a916 100644
--- a/pjsip-apps/src/samples/confsample.c
+++ b/pjsip-apps/src/samples/confsample.c
@@ -26,6 +26,18 @@
#include "util.h"
+/**
+ * \page page_pjmedia_samples_confsample_c Samples: Using Conference Bridge
+ *
+ * Sample to mix multiple files in the conference bridge and play the
+ * result to sound device.
+ *
+ * This file is pjsip-apps/src/samples/confsample.c
+ *
+ * \includelineno confsample.c
+ */
+
+
/* For logging purpose. */
#define THIS_FILE "confsample.c"
diff --git a/pjsip-apps/src/samples/level.c b/pjsip-apps/src/samples/level.c
index e216984..dcf6499 100644
--- a/pjsip-apps/src/samples/level.c
+++ b/pjsip-apps/src/samples/level.c
@@ -17,6 +17,19 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
+
+/**
+ * \page page_pjmedia_samples_level_c Samples: Reading from WAV File
+ *
+ * This is a very simple example to use the @ref PJMEDIA_FILE_PLAY, to
+ * directly read the samples from the file.
+ *
+ * This file is pjsip-apps/src/samples/level.c
+ *
+ * \includelineno level.c
+ */
+
+
static const char *desc =
" FILE: \n"
" level.c \n"
diff --git a/pjsip-apps/src/samples/playfile.c b/pjsip-apps/src/samples/playfile.c
index 5b26cd5..754304b 100644
--- a/pjsip-apps/src/samples/playfile.c
+++ b/pjsip-apps/src/samples/playfile.c
@@ -26,6 +26,22 @@
#include "util.h"
+/**
+ * \page page_pjmedia_samples_playfile_c Samples: Playing WAV File to Sound Device
+ *
+ * This is a very simple example to use the @ref PJMEDIA_FILE_PLAY and
+ * @ref PJMED_SND_PORT. In this example, we open both the file and sound
+ * device, and connect the two of them, and voila! Sound will be playing
+ * the contents of the file.
+ *
+ * @see page_pjmedia_samples_recfile_c
+ *
+ * This file is pjsip-apps/src/samples/playfile.c
+ *
+ * \includelineno playfile.c
+ */
+
+
/*
* playfile.c
*
diff --git a/pjsip-apps/src/samples/playsine.c b/pjsip-apps/src/samples/playsine.c
index 931f912..ae4bec8 100644
--- a/pjsip-apps/src/samples/playsine.c
+++ b/pjsip-apps/src/samples/playsine.c
@@ -17,6 +17,18 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
+
+/**
+ * \page page_pjmedia_samples_playsine_c Samples: Using Custom Ports (Sine Wave Generator)
+ *
+ * This example demonstrate how to create a custom media port (in this case, a
+ * sine wave generator) and connect it to the sound device.
+ *
+ * This file is pjsip-apps/src/samples/playsine.c
+ *
+ * \includelineno playsine.c
+ */
+
/*
* playsine.c
*
diff --git a/pjsip-apps/src/samples/recfile.c b/pjsip-apps/src/samples/recfile.c
index 2236dca..29aa832 100644
--- a/pjsip-apps/src/samples/recfile.c
+++ b/pjsip-apps/src/samples/recfile.c
@@ -17,6 +17,18 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
+/**
+ * \page page_pjmedia_samples_recfile_c Samples: Capturing Audio to WAV File
+ *
+ * In this example, we capture audio from the sound device and save it to
+ * WAVE file.
+ *
+ * @see page_pjmedia_samples_playfile_c
+ *
+ * This file is pjsip-apps/src/samples/recfile.c
+ *
+ * \includelineno recfile.c
+ */
#include <pjmedia.h>
#include <pjlib.h>
@@ -26,6 +38,7 @@
/* For logging purpose. */
#define THIS_FILE "recfile.c"
+
/* Configs */
#define CLOCK_RATE 44100
#define SAMPLES_PER_FRAME (CLOCK_RATE * 20 / 1000)
diff --git a/pjsip-apps/src/samples/resampleplay.c b/pjsip-apps/src/samples/resampleplay.c
index f876859..9c7b2f1 100644
--- a/pjsip-apps/src/samples/resampleplay.c
+++ b/pjsip-apps/src/samples/resampleplay.c
@@ -16,6 +16,18 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
+
+/**
+ * \page page_pjmedia_samples_resampleplay_c Samples: Using Resample Port
+ *
+ * This example demonstrates how to use @ref PJMEDIA_RESAMPLE_PORT to
+ * change the sampling rate of the media streams.
+ *
+ * This file is pjsip-apps/src/samples/resampleplay.c
+ *
+ * \includelineno resampleplay.c
+ */
+
#include <pjmedia.h>
#include <pjlib-util.h>
#include <pjlib.h>
diff --git a/pjsip-apps/src/samples/siprtp.c b/pjsip-apps/src/samples/siprtp.c
index 4270966..4ffe012 100644
--- a/pjsip-apps/src/samples/siprtp.c
+++ b/pjsip-apps/src/samples/siprtp.c
@@ -20,6 +20,7 @@
+
/* Usage */
static const char *USAGE =
" PURPOSE: \n"
diff --git a/pjsip-apps/src/samples/sipstateless.c b/pjsip-apps/src/samples/sipstateless.c
index c3cfe07..4c8354c 100644
--- a/pjsip-apps/src/samples/sipstateless.c
+++ b/pjsip-apps/src/samples/sipstateless.c
@@ -103,20 +103,13 @@
/* Create global endpoint: */
{
- const pj_str_t *hostname;
- const char *endpt_name;
-
/* Endpoint MUST be assigned a globally unique name.
- * The name will be used as the hostname in Warning header.
+ * Ideally we should put hostname or public IP address, but
+ * we'll just use an arbitrary name here.
*/
- /* For this implementation, we'll use hostname for simplicity */
- hostname = pj_gethostname();
- endpt_name = hostname->ptr;
-
/* Create the endpoint: */
-
- status = pjsip_endpt_create(&cp.factory, endpt_name,
+ status = pjsip_endpt_create(&cp.factory, "sipstateless",
&sip_endpt);
PJ_ASSERT_RETURN(status == PJ_SUCCESS, 1);
}
diff --git a/pjsip-apps/src/samples/sndtest.c b/pjsip-apps/src/samples/sndtest.c
index 2c46977..c2b75b9 100644
--- a/pjsip-apps/src/samples/sndtest.c
+++ b/pjsip-apps/src/samples/sndtest.c
@@ -17,6 +17,21 @@
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
+/**
+ * \page page_pjmedia_samples_sndtest_c Samples: Sound Card Benchmark
+ *
+ * This example can be used to benchmark the quality of the sound card
+ * installed in the system. At the end of the test, it will report
+ * the jitter and clock drifts of the device.
+ *
+ * This file is pjsip-apps/src/samples/sndtest.c
+ *
+ * Screenshots on WinXP: \image html sndtest.jpg
+ *
+ * \includelineno sndtest.c
+ */
+
+
#include <pjmedia.h>
#include <pjlib.h>
#include <pjlib-util.h>
diff --git a/pjsip-apps/src/samples/streamutil.c b/pjsip-apps/src/samples/streamutil.c
index 29ba520..4609df0 100644
--- a/pjsip-apps/src/samples/streamutil.c
+++ b/pjsip-apps/src/samples/streamutil.c
@@ -18,6 +18,18 @@
*/
+/**
+ * \page page_pjmedia_samples_streamutil_c Samples: Remote Streaming
+ *
+ * This example mainly demonstrates how to stream media file to remote
+ * peer using RTP.
+ *
+ * This file is pjsip-apps/src/samples/streamutil.c
+ *
+ * \includelineno streamutil.c
+ */
+
+
static const char *desc =
" streamutil \n"
" \n"
diff --git a/pjsip/docs/doxygen.cfg b/pjsip/docs/doxygen.cfg
index 3edc5bf..59d6e65 100644
--- a/pjsip/docs/doxygen.cfg
+++ b/pjsip/docs/doxygen.cfg
@@ -384,7 +384,7 @@
# directories that contain example code fragments that are included (see
# the \include command).
-EXAMPLE_PATH =
+EXAMPLE_PATH = ../pjsip-apps/src/samples ../pjsip-apps/src/pjsua
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@@ -404,7 +404,7 @@
# directories that contain image that are included in the documentation (see
# the \image command).
-IMAGE_PATH =
+IMAGE_PATH = docs ../pjmedia/docs
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/pjsip/docs/doxygen.h b/pjsip/docs/doxygen.h
index d13ae20..604284f 100644
--- a/pjsip/docs/doxygen.h
+++ b/pjsip/docs/doxygen.h
@@ -181,3 +181,96 @@
*/
+/**
+ @page page_pjsip_samples PJSIP Samples
+
+ I wish I could write more samples, but for now here are some samples or
+ working applications that are available from the source tree:
+
+ - @ref page_pjsip_sample_sipstateless_c\n
+ This is about the simplest SIP application with PJSIP, all it does is
+ respond all incoming requests with 501 (Not Implemented) response
+ statelessly.
+
+ - @ref page_pjsip_sample_simple_ua_c\n
+ This is a very simple SIP User Agent application that only use PJSIP
+ (without PJSIP-UA). It's able to make and receive call, and play
+ media to the sound device.
+
+ - @ref page_pjsip_samples_pjsua\n
+ This is the reference implementation for PJSIP and PJMEDIA.
+ PJSUA is a console based application, designed to be simple enough
+ to be readble, but powerful enough to demonstrate all features
+ available in PJSIP and PJMEDIA.\n
+ Screenshot on WinXP: \image html pjsua.jpg "pjsua on WinXP"
+
+ - @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_pjsip_samples_pjsua PJSUA
+ *
+ * This is the reference implementation for PJSIP and PJMEDIA.
+ * PJSUA is a console based application, designed to be simple enough
+ * to be readble, but powerful enough to demonstrate all features
+ * available in PJSIP and PJMEDIA.
+ *
+ * This file is pjsip-apps/src/pjsua/pjsua_app.c
+ *
+ * Screenshot on WinXP: \image html pjsua.jpg "pjsua on WinXP"
+ *
+ * \includelineno pjsua_app.c
+ */
+
+/**
+ * \page page_pjsip_sample_simple_ua_c Samples: Simple UA
+ *
+ * This is a very simple SIP User Agent application that only use PJSIP
+ * (without PJSIP-UA). It's able to make and receive call, and play
+ * media to the sound device.
+ *
+ * \includelineno simpleua.c
+ */
+
+/**
+ * \page page_pjsip_sample_sipstateless_c Samples: Stateless SIP Endpoint
+ *
+ * This is about the simplest SIP application with PJSIP, all it does is
+ * respond all incoming requests with 501 (Not Implemented) response
+ * statelessly.
+ *
+ * \includelineno sipstateless.c
+ */
+
+/**
+ * \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
+ */
+
diff --git a/pjsip/docs/pjsua.jpg b/pjsip/docs/pjsua.jpg
new file mode 100644
index 0000000..479567b
--- /dev/null
+++ b/pjsip/docs/pjsua.jpg
Binary files differ
