diff options
| author | Benny Prijono <bennylp@teluu.com> | 2008-06-20 21:39:02 +0000 |
|---|---|---|
| committer | Benny Prijono <bennylp@teluu.com> | 2008-06-20 21:39:02 +0000 |
| commit | dcadef7fc04bb899333fb0ab472679c8ac280e09 (patch) | |
| tree | 2338aea1588dac3380a1cbaf80b50a0a57dc3d80 | |
| parent | f06496992c8bbc62f899e4ee782889a3a4b08a4e (diff) | |
Updated doxygen documentations
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2037 74dad513-b988-da41-8d7b-12977e46ad98
88 files changed, 364 insertions, 683 deletions
@@ -7,7 +7,7 @@ ifdef MINSIZE MAKE_FLAGS := MINSIZE=1 endif -all clean dep depend distclean doc print realclean: +all clean dep depend distclean print realclean: for dir in $(DIRS); do \ if $(MAKE) $(MAKE_FLAGS) -C $$dir/build $@; then \ true; \ @@ -16,6 +16,19 @@ all clean dep depend distclean doc print realclean: fi; \ done +doc: + @if test \( ! "$(WWWDIR)" == "" \) -a \( ! -d $(WWWDIR)/pjlib/docs/html \) ; then \ + echo 'Directory "$(WWWDIR)" does not look like a valid pjsip web directory'; \ + exit 1; \ + fi + for dir in $(DIRS); do \ + if $(MAKE) $(MAKE_FLAGS) -C $$dir/build $@; then \ + true; \ + else \ + exit 1; \ + fi; \ + done + LIBS = pjlib/lib/libpj-$(TARGET_NAME).a \ pjlib-util/lib/libpjlib-util-$(TARGET_NAME).a \ pjnath/lib/libpjnath-$(TARGET_NAME).a \ diff --git a/pjlib-util/build/Makefile b/pjlib-util/build/Makefile index c2977854..df735d4a 100644 --- a/pjlib-util/build/Makefile +++ b/pjlib-util/build/Makefile @@ -54,7 +54,11 @@ TARGETS := pjlib-util pjlib-util-test all: $(TARGETS) doc: - cd .. && doxygen docs/doxygen.cfg + cd .. && rm -rf docs/html docs/latex && doxygen docs/doxygen.cfg + @if test ! "$(WWWDIR)" == ""; then \ + echo "Copying to $(WWWDIR)/pjlib-util/docs/html.." ; \ + cp -a ../docs/html/* $(WWWDIR)/pjlib-util/docs/html/ ; \ + fi dep: depend distclean: realclean diff --git a/pjlib-util/docs/doxygen.cfg b/pjlib-util/docs/doxygen.cfg index 5790dd5d..1c2e15de 100644 --- a/pjlib-util/docs/doxygen.cfg +++ b/pjlib-util/docs/doxygen.cfg @@ -294,6 +294,7 @@ OPTIMIZE_OUTPUT_JAVA = NO # list will mention the files that were used to generate the documentation.
SHOW_USED_FILES = YES
+TYPEDEF_HIDES_STRUCT = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
@@ -874,12 +875,12 @@ SKIP_FUNCTION_MACROS = YES # The TAGFILES tag can be used to specify one or more tagfiles.
-TAGFILES =
+TAGFILES = ../pjlib/docs/pjlib.tag=../../../pjlib/docs/html ../pjnath/docs/pjnath.tag=../../../pjnath/docs/html ../pjsip/docs/pjsip.tag=../../../pjsip/docs/html ../pjmedia/docs/pjmedia.tag=../../../pjmedia/docs/html
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = docs/pjlib-util.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
@@ -891,12 +892,13 @@ ALLEXTERNALS = NO # in the modules index. If set to NO, only the current project's groups will
# be listed.
-EXTERNAL_GROUPS = YES
+EXTERNAL_GROUPS = NO
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
-PERL_PATH = /usr/bin/perl
+#PERL_PATH = /usr/bin/perl
+PERL_PATH = /c/Perl/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
diff --git a/pjlib-util/docs/footer.html b/pjlib-util/docs/footer.html index 96c82062..e888b357 100644 --- a/pjlib-util/docs/footer.html +++ b/pjlib-util/docs/footer.html @@ -1,7 +1,7 @@ <p> </p>
<hr><center>
PJLIB-UTIL Open Source, small footprint, and portable asynchronous/caching DNS resolver, text scanner, STUN client, and XML library<br>
-(C)2001-2007 Benny Prijono
+(C)2001-2008 Benny Prijono
</center>
diff --git a/pjlib-util/include/pjlib-util/config.h b/pjlib-util/include/pjlib-util/config.h index f01ade58..6393abe1 100644 --- a/pjlib-util/include/pjlib-util/config.h +++ b/pjlib-util/include/pjlib-util/config.h @@ -26,8 +26,8 @@ */ /** - * @defgroup PJLIB_UTIL_CONFIG PJLIB-UTIL Configuration - * @ingroup PJLIB_UTIL + * @defgroup PJLIB_UTIL_CONFIG Configuration + * @ingroup PJLIB_UTIL_BASE * @{ */ diff --git a/pjlib-util/include/pjlib-util/dns.h b/pjlib-util/include/pjlib-util/dns.h index a537169a..11ea4a6e 100644 --- a/pjlib-util/include/pjlib-util/dns.h +++ b/pjlib-util/include/pjlib-util/dns.h @@ -31,7 +31,7 @@ PJ_BEGIN_DECL /** * @defgroup PJ_DNS DNS and Asynchronous DNS Resolver - * @ingroup PJLIB_UTIL + * @ingroup PJ_PROTOCOLS */ /** diff --git a/pjlib-util/include/pjlib-util/dns_server.h b/pjlib-util/include/pjlib-util/dns_server.h index 742b3c8e..3ff15f86 100644 --- a/pjlib-util/include/pjlib-util/dns_server.h +++ b/pjlib-util/include/pjlib-util/dns_server.h @@ -30,7 +30,7 @@ PJ_BEGIN_DECL /** * @defgroup PJ_DNS_SERVER Simple DNS Server - * @ingroup PJLIB_UTIL + * @ingroup PJ_DNS * @{ * This contains a simple but fully working DNS server implementation, * mostly for testing purposes. It supports serving various DNS resource diff --git a/pjlib-util/include/pjlib-util/errno.h b/pjlib-util/include/pjlib-util/errno.h index 8db99f6a..8e098f1b 100644 --- a/pjlib-util/include/pjlib-util/errno.h +++ b/pjlib-util/include/pjlib-util/errno.h @@ -23,8 +23,8 @@ #include <pj/errno.h> /** - * @defgroup PJLIB_UTIL_ERROR PJLIB-UTIL Error Codes - * @ingroup PJLIB_UTIL + * @defgroup PJLIB_UTIL_ERROR Error Codes + * @ingroup PJLIB_UTIL_BASE * @{ */ diff --git a/pjlib-util/include/pjlib-util/getopt.h b/pjlib-util/include/pjlib-util/getopt.h index 4b48f9db..6c304d2e 100644 --- a/pjlib-util/include/pjlib-util/getopt.h +++ b/pjlib-util/include/pjlib-util/getopt.h @@ -29,7 +29,7 @@ /** * @defgroup PJLIB_UTIL_GETOPT Getopt - * @ingroup PJLIB_UTIL + * @ingroup PJLIB_TEXT * @{ */ diff --git a/pjlib-util/include/pjlib-util/pcap.h b/pjlib-util/include/pjlib-util/pcap.h index 58d39a9f..492df0f3 100644 --- a/pjlib-util/include/pjlib-util/pcap.h +++ b/pjlib-util/include/pjlib-util/pcap.h @@ -30,7 +30,7 @@ PJ_BEGIN_DECL /** * @defgroup PJ_PCAP Simple PCAP file reader - * @ingroup PJLIB_UTIL + * @ingroup PJ_FILE_FMT * @{ * This module describes simple utility to read PCAP file. It is not intended * to support all PCAP features (that's what libpcap is for!), but it can diff --git a/pjlib-util/include/pjlib-util/scanner.h b/pjlib-util/include/pjlib-util/scanner.h index 2460391f..d7bb8ff0 100644 --- a/pjlib-util/include/pjlib-util/scanner.h +++ b/pjlib-util/include/pjlib-util/scanner.h @@ -30,7 +30,7 @@ PJ_BEGIN_DECL /** * @defgroup PJ_SCAN Fast Text Scanning - * @ingroup PJLIB_UTIL + * @ingroup PJLIB_TEXT * @brief Text scanning utility. * * This module describes a fast text scanning functions. diff --git a/pjlib-util/include/pjlib-util/string.h b/pjlib-util/include/pjlib-util/string.h index 1ede956e..67763a74 100644 --- a/pjlib-util/include/pjlib-util/string.h +++ b/pjlib-util/include/pjlib-util/string.h @@ -29,7 +29,7 @@ /** * @defgroup PJLIB_UTIL_STRING String Escaping Utilities - * @ingroup PJLIB_UTIL + * @ingroup PJLIB_TEXT * @{ */ diff --git a/pjlib-util/include/pjlib-util/stun_simple.h b/pjlib-util/include/pjlib-util/stun_simple.h index 02309082..3d456f56 100644 --- a/pjlib-util/include/pjlib-util/stun_simple.h +++ b/pjlib-util/include/pjlib-util/stun_simple.h @@ -144,7 +144,7 @@ PJ_DECL(void*) pjstun_msg_find_attr( pjstun_msg *msg, pjstun_attr_type t); /** * @defgroup PJLIB_UTIL_STUN_CLIENT Simple STUN Helper - * @ingroup PJLIB_UTIL_STUN + * @ingroup PJ_PROTOCOLS * @brief A simple and small footprint STUN resolution helper * @{ * diff --git a/pjlib-util/include/pjlib-util/types.h b/pjlib-util/include/pjlib-util/types.h index a512f435..67764e5f 100644 --- a/pjlib-util/include/pjlib-util/types.h +++ b/pjlib-util/include/pjlib-util/types.h @@ -28,7 +28,7 @@ #include <pjlib-util/config.h> /** - * @defgroup PJLIB_UTIL PJLIB-UTIL Library + * @defgroup PJLIB_UTIL_BASE Base * @{ */ @@ -50,6 +50,17 @@ PJ_END_DECL * @} */ +/** + * @defgroup PJLIB_TEXT Text and String Manipulation + */ + +/** + * @defgroup PJ_PROTOCOLS Protocols + */ + +/** + * @defgroup PJ_FILE_FMT File Formats + */ /** * @mainpage PJLIB-UTIL @@ -60,8 +71,8 @@ PJ_END_DECL * This is the documentation of PJLIB-UTIL, an auxiliary library providing * adjunct functions to PJLIB. * - * Please go to the <A HREF="modules.htm"><B>Modules</B></A> page for list - * of modules. + * Please go to the <A HREF="modules.htm"><B>Table of Contents</B></A> page + * for list of modules. * * * \n diff --git a/pjlib-util/include/pjlib-util/xml.h b/pjlib-util/include/pjlib-util/xml.h index d00960dc..10b9c0af 100644 --- a/pjlib-util/include/pjlib-util/xml.h +++ b/pjlib-util/include/pjlib-util/xml.h @@ -31,7 +31,7 @@ PJ_BEGIN_DECL /** * @defgroup PJ_TINY_XML Mini/Tiny XML Parser/Helper - * @ingroup PJLIB_UTIL + * @ingroup PJ_FILE_FMT * @{ */ diff --git a/pjlib/build/Makefile b/pjlib/build/Makefile index 68a0c0e6..4d747e10 100644 --- a/pjlib/build/Makefile +++ b/pjlib/build/Makefile @@ -55,7 +55,11 @@ export CC_OUT CC AR RANLIB HOST_MV HOST_RM HOST_RMDIR HOST_MKDIR OBJEXT LD LDOUT all: $(TARGETS) doc: - cd .. && doxygen docs/doxygen.cfg + cd .. && rm -rf docs/html docs/latex && doxygen docs/doxygen.cfg + @if test ! "$(WWWDIR)" == ""; then \ + echo "Copying to $(WWWDIR)/pjlib/docs/html.." ; \ + cp -a ../docs/html/* $(WWWDIR)/pjlib/docs/html/ ; \ + fi print: $(MAKE) -f $(RULES_MAK) APP=PJLIB app=pjlib print_lib diff --git a/pjlib/docs/doxygen.cfg b/pjlib/docs/doxygen.cfg index e6b0d754..6b6a8d3e 100644 --- a/pjlib/docs/doxygen.cfg +++ b/pjlib/docs/doxygen.cfg @@ -294,6 +294,7 @@ OPTIMIZE_OUTPUT_JAVA = NO # list will mention the files that were used to generate the documentation.
SHOW_USED_FILES = YES
+TYPEDEF_HIDES_STRUCT = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
@@ -878,7 +879,7 @@ TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = docs/pjlib.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
@@ -895,7 +896,8 @@ EXTERNAL_GROUPS = YES # The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
-PERL_PATH = /usr/bin/perl
+#PERL_PATH = /usr/bin/perl
+PERL_PATH = /c/Perl/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
diff --git a/pjlib/docs/footer.html b/pjlib/docs/footer.html index 7c7bc4a5..6eea5a91 100644 --- a/pjlib/docs/footer.html +++ b/pjlib/docs/footer.html @@ -1,7 +1,7 @@ <p> </p>
<hr><center>
PJLIB Open Source, high performance, small footprint, and very very portable framework<br>
-(C)2001-2007 Benny Prijono
+(C)2001-2008 Benny Prijono
</center>
diff --git a/pjlib/include/pj/config.h b/pjlib/include/pj/config.h index 22564420..fe182e38 100644 --- a/pjlib/include/pj/config.h +++ b/pjlib/include/pj/config.h @@ -303,7 +303,6 @@ /** * @defgroup pj_config Build Configuration - * @ingroup PJ * @{ * * This section contains macros that can set during PJLIB build process @@ -804,7 +803,6 @@ /** * @defgroup pj_config Build Configuration - * @ingroup PJ * @{ */ diff --git a/pjlib/include/pj/doxygen.h b/pjlib/include/pj/doxygen.h index 5a6ece2c..ee88ea17 100644 --- a/pjlib/include/pj/doxygen.h +++ b/pjlib/include/pj/doxygen.h @@ -53,10 +53,6 @@ * \a doxygen (http://www.doxygen.org). Doxygen is a great (and free!) * tools for generating such documentation. * - * @subsection doc_ver_subsec Version - * - * This document corresponds to PJLIB version 0.8.0. - * * * @subsection find_samples_subsec How to Read This Document * diff --git a/pjlib/include/pj/errno.h b/pjlib/include/pj/errno.h index 57d90afe..b72092df 100644 --- a/pjlib/include/pj/errno.h +++ b/pjlib/include/pj/errno.h @@ -30,7 +30,6 @@ PJ_BEGIN_DECL /** * @defgroup pj_errno Error Codes - * @ingroup PJ * @{ * * In PJLIB, error/status codes from operating system are translated diff --git a/pjlib/include/pj/guid.h b/pjlib/include/pj/guid.h index 5ce1adf0..0d89a934 100644 --- a/pjlib/include/pj/guid.h +++ b/pjlib/include/pj/guid.h @@ -32,7 +32,6 @@ PJ_BEGIN_DECL /** * @defgroup PJ_DS Data Structure. - * @ingroup PJ */ /** * @defgroup PJ_GUID Globally Unique Identifier diff --git a/pjlib/include/pj/list.h b/pjlib/include/pj/list.h index f6f2c167..6320f56f 100644 --- a/pjlib/include/pj/list.h +++ b/pjlib/include/pj/list.h @@ -30,7 +30,6 @@ PJ_BEGIN_DECL /* * @defgroup PJ_DS Data Structure. - * @ingroup PJ */ /** diff --git a/pjlib/include/pj/log.h b/pjlib/include/pj/log.h index 0870708e..763b5943 100644 --- a/pjlib/include/pj/log.h +++ b/pjlib/include/pj/log.h @@ -31,7 +31,6 @@ PJ_BEGIN_DECL /** * @defgroup PJ_MISC Miscelaneous - * @ingroup PJ */ /** diff --git a/pjlib/include/pj/os.h b/pjlib/include/pj/os.h index f5503c98..f99aa6bb 100644 --- a/pjlib/include/pj/os.h +++ b/pjlib/include/pj/os.h @@ -29,7 +29,6 @@ PJ_BEGIN_DECL /** * @defgroup PJ_OS Operating System Dependent Functionality. - * @ingroup PJ */ diff --git a/pjlib/include/pj/pool.h b/pjlib/include/pj/pool.h index 42886408..35d8b3f4 100644 --- a/pjlib/include/pj/pool.h +++ b/pjlib/include/pj/pool.h @@ -39,7 +39,6 @@ PJ_BEGIN_DECL /** * @defgroup PJ_POOL_GROUP Fast Memory Pool - * @ingroup PJ * @brief * Memory pools allow dynamic memory allocation comparable to malloc or the * new in operator C++. Those implementations are not desirable for very diff --git a/pjlib/include/pj/types.h b/pjlib/include/pj/types.h index 4ea5b79b..d792fdd5 100644 --- a/pjlib/include/pj/types.h +++ b/pjlib/include/pj/types.h @@ -21,9 +21,6 @@ /** - * @defgroup PJ PJ Library - */ -/** * @file types.h * @brief Declaration of basic types and utility. */ diff --git a/pjmedia/build/Makefile b/pjmedia/build/Makefile index b42b12ab..1af0e76f 100644 --- a/pjmedia/build/Makefile +++ b/pjmedia/build/Makefile @@ -107,7 +107,12 @@ TARGETS := pjmedia pjmedia-codec pjsdp all: $(TARGETS) doc: - cd .. && doxygen docs/doxygen.cfg + cd .. && rm -rf docs/html docs/latex && doxygen docs/doxygen.cfg + @if test ! "$(WWWDIR)" == ""; then \ + echo "Copying to $(WWWDIR)/pjmedia/docs/html.." ; \ + rm -rf $(WWWDIR)/pjmedia/docs/html/* ; \ + cp -a ../docs/html/* $(WWWDIR)/pjmedia/docs/html/ ; \ + fi dep: depend distclean: realclean diff --git a/pjmedia/docs/doxygen.cfg b/pjmedia/docs/doxygen.cfg index e2fa0889..28d4d5e8 100644 --- a/pjmedia/docs/doxygen.cfg +++ b/pjmedia/docs/doxygen.cfg @@ -213,7 +213,7 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in
# declaration order.
-SORT_MEMBER_DOCS = YES
+SORT_MEMBER_DOCS = NO
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES, then doxygen will reuse the documentation of the first
@@ -295,6 +295,8 @@ OPTIMIZE_OUTPUT_JAVA = NO SHOW_USED_FILES = YES
+TYPEDEF_HIDES_STRUCT = YES
+
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
@@ -314,7 +316,7 @@ WARNINGS = YES # for undocumented members. If EXTRACT_ALL is set to YES then this flag will
# automatically be disabled.
-WARN_IF_UNDOCUMENTED = YES
+WARN_IF_UNDOCUMENTED = NO
# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some
@@ -874,12 +876,12 @@ SKIP_FUNCTION_MACROS = YES # The TAGFILES tag can be used to specify one or more tagfiles.
-TAGFILES =
+TAGFILES = ../pjlib/docs/pjlib.tag=../../../pjlib/docs/html ../pjlib-util/docs/pjlib-util.tag=../../../pjlib-util/docs/html ../pjnath/docs/pjnath.tag=../../../pjnath/docs/html ../pjsip/docs/pjmedia.tag=../../../pjmedia/docs/html
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = docs/pjmedia.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
@@ -891,12 +893,13 @@ ALLEXTERNALS = NO # in the modules index. If set to NO, only the current project's groups will
# be listed.
-EXTERNAL_GROUPS = YES
+EXTERNAL_GROUPS = NO
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
-PERL_PATH = /usr/bin/perl
+#PERL_PATH = /usr/bin/perl
+PERL_PATH = /c/Perl/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
@@ -978,22 +981,6 @@ DOT_PATH = DOTFILE_DIRS =
-# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
-# (in pixels) of the graphs generated by dot. If a graph becomes larger than
-# this value, doxygen will try to truncate the graph, so that it fits within
-# the specified constraint. Beware that most browsers cannot cope with very
-# large images.
-
-MAX_DOT_GRAPH_WIDTH = 1024
-
-# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
-# (in pixels) of the graphs generated by dot. If a graph becomes larger than
-# this value, doxygen will try to truncate the graph, so that it fits within
-# the specified constraint. Beware that most browsers cannot cope with very
-# large images.
-
-MAX_DOT_GRAPH_HEIGHT = 1024
-
# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
# generate a legend page explaining the meaning of the various boxes and
# arrows in the dot generated graphs.
diff --git a/pjmedia/docs/footer.html b/pjmedia/docs/footer.html index ff3bec92..757333e7 100644 --- a/pjmedia/docs/footer.html +++ b/pjmedia/docs/footer.html @@ -1,7 +1,7 @@ <p> </p> <hr><center> PJMEDIA small footprint Open Source media stack<br> -(C)2003-2007 Benny Prijono +(C)2003-2008 Benny Prijono </center> <!--#include virtual="/footer.html" --> </BODY> diff --git a/pjmedia/include/pjmedia-codec/g722.h b/pjmedia/include/pjmedia-codec/g722.h index 0cd05471..081e79c2 100644 --- a/pjmedia/include/pjmedia-codec/g722.h +++ b/pjmedia/include/pjmedia-codec/g722.h @@ -31,6 +31,7 @@ * @ingroup PJMEDIA_CODEC * @brief Implementation of G.722 Codec * @{ + * * This section describes functions to register and register G.722 codec * factory to the codec manager. After the codec factory has been registered, * application can use @ref PJMEDIA_CODEC API to manipulate the codec. diff --git a/pjmedia/include/pjmedia-codec/gsm.h b/pjmedia/include/pjmedia-codec/gsm.h index 4045c443..7c7759f1 100644 --- a/pjmedia/include/pjmedia-codec/gsm.h +++ b/pjmedia/include/pjmedia-codec/gsm.h @@ -31,6 +31,7 @@ * @ingroup PJMEDIA_CODEC * @brief Implementation of GSM FR based on GSM 06.10 library * @{ + * * This section describes functions to register and register GSM codec * factory to the codec manager. After the codec factory has been registered, * application can use @ref PJMEDIA_CODEC API to manipulate the codec. diff --git a/pjmedia/include/pjmedia-codec/ilbc.h b/pjmedia/include/pjmedia-codec/ilbc.h index 4a8adf9b..bb4e8e60 100644 --- a/pjmedia/include/pjmedia-codec/ilbc.h +++ b/pjmedia/include/pjmedia-codec/ilbc.h @@ -31,6 +31,7 @@ * @ingroup PJMEDIA_CODEC * @brief Implementation of iLBC Codec * @{ + * * This section describes functions to register and register iLBC codec * factory to the codec manager. After the codec factory has been registered, * application can use @ref PJMEDIA_CODEC API to manipulate the codec. diff --git a/pjmedia/include/pjmedia-codec/l16.h b/pjmedia/include/pjmedia-codec/l16.h index c12320b9..03ecb5ed 100644 --- a/pjmedia/include/pjmedia-codec/l16.h +++ b/pjmedia/include/pjmedia-codec/l16.h @@ -25,8 +25,9 @@ /** * @defgroup PJMED_L16 L16 Codec Family * @ingroup PJMEDIA_CODEC - * @brief 16bit linear codecs (useful for debugging) + * @brief PCM/16bit/linear codecs * @{ + * * This section describes functions to register and register L16 codec * factory to the codec manager. After the codec factory has been registered, * application can use @ref PJMEDIA_CODEC API to manipulate the codec. diff --git a/pjmedia/include/pjmedia-codec/speex.h b/pjmedia/include/pjmedia-codec/speex.h index 550382df..eb919a13 100644 --- a/pjmedia/include/pjmedia-codec/speex.h +++ b/pjmedia/include/pjmedia-codec/speex.h @@ -31,6 +31,7 @@ * @ingroup PJMEDIA_CODEC * @brief Implementation of Speex codecs (narrow/wide/ultrawide-band). * @{ + * * This section describes functions to register and register speex codec * factory to the codec manager. After the codec factory has been registered, * application can use @ref PJMEDIA_CODEC API to manipulate the codec. diff --git a/pjmedia/include/pjmedia/bidirectional.h b/pjmedia/include/pjmedia/bidirectional.h index 97921ef1..5a73b20f 100644 --- a/pjmedia/include/pjmedia/bidirectional.h +++ b/pjmedia/include/pjmedia/bidirectional.h @@ -21,7 +21,7 @@ /** * @file bidirectional.h - * @brief Create bidirectional port from two unidirectional ports. + * @brief Bidirectional media port. */ #include <pjmedia/port.h> @@ -29,7 +29,8 @@ /** * @defgroup PJMEDIA_BIDIRECTIONAL_PORT Bidirectional Port * @ingroup PJMEDIA_PORT - * @brief Create bidirectional port from two unidirectional ports. + * @brief A bidirectional port combines two unidirectional ports into one + * bidirectional port * @{ */ diff --git a/pjmedia/include/pjmedia/clock.h b/pjmedia/include/pjmedia/clock.h index 12daa837..a85a7ba9 100644 --- a/pjmedia/include/pjmedia/clock.h +++ b/pjmedia/include/pjmedia/clock.h @@ -27,6 +27,39 @@ /** + * @defgroup PJMEDIA_PORT_CLOCK Clock/Timing + * @ingroup PJMEDIA_PORT + * @brief Various types of classes that provide timing. + * @{ + + The media clock/timing extends the media port concept that is explained + in @ref PJMEDIA_PORT. When clock is present in the ports + interconnection, media will flow automatically (and with correct timing too!) + from one media port to another. + + There are few objects in PJMEDIA that are able to provide clock/timing + to media ports interconnection: + + - @ref PJMED_SND_PORT\n + The sound device makes a good candidate as the clock source, and + PJMEDIA @ref PJMED_SND is designed so that it is able to invoke + operations according to timing driven by the sound hardware clock + (this may sound complicated, but actually it just means that + the sound device abstraction provides callbacks to be called when + it has/wants media frames).\n + See @ref PJMED_SND_PORT for more details. + + - @ref PJMEDIA_MASTER_PORT\n + The master port uses @ref PJMEDIA_CLOCK as the clock source. By using + @ref PJMEDIA_MASTER_PORT, it is possible to interconnect passive + media ports and let the frames flow automatically in timely manner.\n + Please see @ref PJMEDIA_MASTER_PORT for more details. + + @} + */ + + +/** * @addtogroup PJMEDIA_CLOCK Clock Generator * @ingroup PJMEDIA_PORT_CLOCK * @brief Interface for generating clock. diff --git a/pjmedia/include/pjmedia/codec.h b/pjmedia/include/pjmedia/codec.h index d3e08927..9d77a7f0 100644 --- a/pjmedia/include/pjmedia/codec.h +++ b/pjmedia/include/pjmedia/codec.h @@ -33,7 +33,6 @@ PJ_BEGIN_DECL /** * @defgroup PJMEDIA_CODEC Codec Framework - * @ingroup PJMEDIA * @brief Media codec framework and management * @{ * diff --git a/pjmedia/include/pjmedia/conference.h b/pjmedia/include/pjmedia/conference.h index b741681d..4d2e897f 100644 --- a/pjmedia/include/pjmedia/conference.h +++ b/pjmedia/include/pjmedia/conference.h @@ -29,7 +29,7 @@ /** * @defgroup PJMEDIA_CONF Conference Bridge * @ingroup PJMEDIA_PORT - * @brief The implementation of conference bridge + * @brief Audio conference bridge implementation * @{ * * This describes the conference bridge implementation in PJMEDIA. The diff --git a/pjmedia/include/pjmedia/config.h b/pjmedia/include/pjmedia/config.h index 340d4584..7c67e85d 100644 --- a/pjmedia/include/pjmedia/config.h +++ b/pjmedia/include/pjmedia/config.h @@ -27,7 +27,6 @@ /** * @defgroup PJMEDIA_BASE Base Types and Configurations - * @ingroup PJMEDIA */ /** diff --git a/pjmedia/include/pjmedia/delaybuf.h b/pjmedia/include/pjmedia/delaybuf.h index 1108ee23..8542ad88 100644 --- a/pjmedia/include/pjmedia/delaybuf.h +++ b/pjmedia/include/pjmedia/delaybuf.h @@ -29,9 +29,12 @@ #include <pjmedia/types.h> /** - * @defgroup PJMED_DELAYBUF Delay Buffer + * @defgroup PJMED_DELAYBUF Adaptive Delay Buffer * @ingroup PJMEDIA_FRAME_OP + * @brief Adaptive delay buffer with high-quality time-scale + * modification * @{ + * * This section describes PJMEDIA's implementation of delay buffer. * Delay buffer works quite similarly like a fixed jitter buffer, that * is it will delay the frame retrieval by some interval so that caller @@ -43,13 +46,15 @@ * will always get a frame from the buffer (assuming that the number of * get() and put() are matched). * - * The delay buffer is mostly used by the sound port, to accommodate - * for the burst frames returned by the sound device. + * The buffer is adaptive, that is it continuously learns the optimal delay + * to be applied to the audio flow at run-time. Once the optimal delay has + * been learned, the delay buffer will apply this delay to the audio flow, + * expanding or shrinking the audio samples as necessary when the actual + * audio samples in the buffer are too low or too high. It does this without + * distorting the audio quality of the audio, by using \a PJMED_WSOLA. * - * To determine the level of delay to be applied, the delay buffer - * has a learning period on which it calculates the level of burst of - * both the put() and get(), and use the maximum value of both as the - * delay level. + * The delay buffer is used in \ref PJMED_SND_PORT, \ref PJMEDIA_SPLITCOMB, + * and \ref PJMEDIA_CONF. */ PJ_BEGIN_DECL diff --git a/pjmedia/include/pjmedia/doxygen.h b/pjmedia/include/pjmedia/doxygen.h index 8d93175c..5921871b 100644 --- a/pjmedia/include/pjmedia/doxygen.h +++ b/pjmedia/include/pjmedia/doxygen.h @@ -24,9 +24,6 @@ * @brief Doxygen's mainpage. */ -/** - * @defgroup PJMEDIA PJMEDIA Library - */ /*////////////////////////////////////////////////////////////////////////// */ /* @@ -42,10 +39,10 @@ * PJMEDIA is a rather complete media stack, distributed under Open Source/GPL * terms, and featuring small footprint and good extensibility and portability. * - * Please click the <A HREF="modules.htm"><b>Modules</b></A> link on top + * Please click the <A HREF="modules.htm"><b>Table of Contents</b></A> link on top * of this page to get the complete features currently present in PJMEDIA. * - * Also please read the documentation about @ref PJMEDIA_PORT_CONCEPT, + * Also please read the documentation about @ref PJMEDIA_PORT * which is a major concept that is used for implementing many objects in * the library. * @@ -79,358 +76,6 @@ * */ -/** - * @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", - * @ref PJMED_GSM "GSM codec", - * @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" - */ - - -/** - * @page pjmedia_codec_page Using PJMEDIA-CODEC - * - * Before application can use a codec, it needs to initialize and register - * the codec to the codec manager. This is accomplished with using - * constructs like the following: - * - \code - #include <pjmedia.h> - #include <pjmedia-codec.h> - - init_codecs( pjmedia_endpt *med_ept ) - { - // Register G.711 codecs - pjmedia_codec_g711_init(med_ept); - - // Register GSM codec. - pjmedia_codec_gsm_init(med_ept); - - // Register Speex codecs. - // With the default flag, this will register three codecs: - // speex/8000, speex/16000, and speex/32000 - pjmedia_codec_speex_init(med_ept, 0, 0, 0); - } - \endcode - * - * After the codec is registered, application may create the encoder/decoder - * instance, by using the API as documented in @ref PJMEDIA_CODEC. - */ - - - -/** - * @page lic_stuffs Copying and Acknowledgements - * @section lic_stuff Copying and Acknowledgements - * @subsection pjmedia_about_subsec About PJMEDIA - * - * PJMEDIA is distributed under GPL terms (other licensing schemes may be - * arranged): - \verbatim - Copyright (C) 2003-2007 Benny Prijono <benny@prijono.org> - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - \endverbatim - * - * - * @section other_acks Acknowlegments - * @subsection portaudio_subsec PortAudio - * - * PortAudio is supported as one of the sound device backend, and - * is used by default on Linux/Unix and MacOS X target. - * - * Please visit <A HREF="http://www.portaudio.com">http://www.portaudio.com</A> - * for more info. - * - * PortAudio is distributed with the following condition. - \verbatim - Based on the Open Source API proposed by Ross Bencina - Copyright (c) 1999-2000 Phil Burk - - Permission is hereby granted, free of charge, to any person obtaining - a copy of this software and associated documentation files - (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of the Software, - and to permit persons to whom the Software is furnished to do so, - subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - \endverbatim - * - * - * @subsection resample_ack Resample - * - * PJMEDIA uses <tt>resample-1.8.tar.gz</tt> from - * <A HREF="http://www-ccrma.stanford.edu/~jos/resample/"> - * Digital Audio Resampling Home Page</A>. This library is distibuted - * on LGPL terms. - * - * Some excerpts from the original source codes: - \verbatim - HISTORY - - The first version of this software was written by Julius O. Smith III - <jos@ccrma.stanford.edu> at CCRMA <http://www-ccrma.stanford.edu> in - 1981. It was called SRCONV and was written in SAIL for PDP-10 - compatible machines. The algorithm was first published in - - Smith, Julius O. and Phil Gossett. ``A Flexible Sampling-Rate - Conversion Method,'' Proceedings (2): 19.4.1-19.4.4, IEEE Conference - on Acoustics, Speech, and Signal Processing, San Diego, March 1984. - - An expanded tutorial based on this paper is available at the Digital - Audio Resampling Home Page given above. - - Circa 1988, the SRCONV program was translated from SAIL to C by - Christopher Lee Fraley working with Roger Dannenberg at CMU. - - Since then, the C version has been maintained by jos. - - Sndlib support was added 6/99 by John Gibson <jgg9c@virginia.edu>. - - The resample program is free software distributed in accordance - with the Lesser GNU Public License (LGPL). There is NO warranty; not - even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - \endverbatim - * - * @subsection jb_ack Adaptive Jitter Buffer - * - * The PJMEDIA jitter buffer is based on implementation kindly donated - * by <A HREF="http://www.switchlab.com">Switchlab, Ltd.</A>, and is - * distributed under PJMEDIA licensing terms. - * - * - * @subsection silence_det_ack Adaptive Silence Detector - * - * The adaptive silence detector was based on silence detector - * implementation in <A HREF="http://www.openh323.org">Open H323</A> - * project. I couldn't find the source code anymore, but generally - * Open H323 files are distributed under MPL terms and has the - * following excerpts: - \verbatim - Open H323 Library - - Copyright (c) 1998-2000 Equivalence Pty. Ltd. - - The contents of this file are subject to the Mozilla Public License - Version 1.0 (the "License"); you may not use this file except in - compliance with the License. You may obtain a copy of the License at - http://www.mozilla.org/MPL/ - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. - - The Original Code is Open H323 Library. - - The Initial Developer of the Original Code is Equivalence Pty. Ltd. - - Portions of this code were written with the assisance of funding from - Vovida Networks, Inc. http://www.vovida.com. - \endverbatim - - * @subsection gsm_ack GSM Codec - * - * PJMEDIA uses GSM - * <A HREF="http://kbs.cs.tu-berlin.de/~jutta/toast.html">GSM 06.10</A> - * version 1.0 at patchlevel 12. It has the following Copyright notice: - * - \verbatim - Copyright 1992, 1993, 1994 by Jutta Degener and Carsten Bormann, - Technische Universitaet Berlin - - Any use of this software is permitted provided that this notice is not - removed and that neither the authors nor the Technische Universitaet Berlin - are deemed to have made any representations as to the suitability of this - software for any purpose nor are held responsible for any defects of - this software. THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE. - - As a matter of courtesy, the authors request to be informed about uses - this software has found, about bugs in this software, and about any - improvements that may be of general interest. - - Berlin, 28.11.1994 - Jutta Degener - Carsten Bormann - \endverbatim - * - * - * @subsection speex_codec_ack Speex Codec - * - * PJMEDIA uses Speex codec uses version 1.1.12 from <A HREF="http://www.speex.org"> - * www.speex.org</A>. The Speex library comes with the following Copying - * notice: - \verbatim - Copyright 2002-2005 - Xiph.org Foundation - Jean-Marc Valin - David Rowe - EpicGames - Analog Devices - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - - Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - - Neither the name of the Xiph.org Foundation nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR - CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - \endverbatim - * - * - * @subsection g711_codec_ack G.711 Codec - * - * The G.711 codec algorithm came from Sun Microsystems, Inc, and it's - * got the following excerpts: - * - \verbatim - This source code is a product of Sun Microsystems, Inc. and is provided - for unrestricted use. Users may copy or modify this source code without - charge. - - SUN SOURCE CODE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING - THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR - PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. - - Sun source code is provided with no support and without any obligation on - the part of Sun Microsystems, Inc. to assist in its use, correction, - modification or enhancement. - - SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE - INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS SOFTWARE - OR ANY PART THEREOF. - - In no event will Sun Microsystems, Inc. be liable for any lost revenue - or profits or other special, indirect and consequential damages, even if - Sun has been advised of the possibility of such damages. - - Sun Microsystems, Inc. - 2550 Garcia Avenue - Mountain View, California 94043 - \endverbatim - * - */ - - -/** - @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 @@ -441,8 +86,8 @@ 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 + This is a good place to start learning about @ref PJMEDIA_PORT, + as it shows that @ref PJMEDIA_PORT 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. @@ -455,7 +100,7 @@ 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 + Demonstrates how to create a custom @ref PJMEDIA_PORT (in this case a sine wave generator) and integrate it to PJMEDIA. - @ref page_pjmedia_samples_confsample_c\n diff --git a/pjmedia/include/pjmedia/echo_port.h b/pjmedia/include/pjmedia/echo_port.h index b3945535..5b9259fd 100644 --- a/pjmedia/include/pjmedia/echo_port.h +++ b/pjmedia/include/pjmedia/echo_port.h @@ -30,10 +30,10 @@ /** * @defgroup PJMEDIA_ECHO_PORT Echo Cancellation Port * @ingroup PJMEDIA_PORT - * @brief Echo Cancellation Port - * - * Echo canceller media port, using @ref PJMEDIA_Echo_Cancel backend. + * @brief Echo Cancellation * @{ + * + * Wrapper to \ref PJMEDIA_Echo_Cancel into media port interface. */ diff --git a/pjmedia/include/pjmedia/endpoint.h b/pjmedia/include/pjmedia/endpoint.h index e4521efd..87ec9645 100644 --- a/pjmedia/include/pjmedia/endpoint.h +++ b/pjmedia/include/pjmedia/endpoint.h @@ -26,7 +26,6 @@ */ /** * @defgroup PJMED_ENDPT The Endpoint - * @ingroup PJMEDIA * @{ * * The media endpoint acts as placeholder for endpoint capabilities. Each diff --git a/pjmedia/include/pjmedia/jbuf.h b/pjmedia/include/pjmedia/jbuf.h index bef94490..9303aeab 100644 --- a/pjmedia/include/pjmedia/jbuf.h +++ b/pjmedia/include/pjmedia/jbuf.h @@ -32,14 +32,12 @@ /** * @defgroup PJMED_JBUF Adaptive jitter buffer * @ingroup PJMEDIA_FRAME_OP + * @brief Adaptive de-jitter buffering implementation * @{ + * * This section describes PJMEDIA's implementation of de-jitter buffer. * The de-jitter buffer may be set to operate in adaptive mode or fixed * delay mode. - * - * The jitter buffer is also able to report the status of the current - * frame (#pjmedia_jb_frame_type). This status is used for examply by - * @ref PJMED_STRM to invoke the codec's @ref PJMED_PLC algorithm. */ diff --git a/pjmedia/include/pjmedia/master_port.h b/pjmedia/include/pjmedia/master_port.h index 242949d9..024f2e3c 100644 --- a/pjmedia/include/pjmedia/master_port.h +++ b/pjmedia/include/pjmedia/master_port.h @@ -29,8 +29,9 @@ /** * @defgroup PJMEDIA_MASTER_PORT Master Port * @ingroup PJMEDIA_PORT_CLOCK - * @brief Provides media clock for media ports. + * @brief Thread based media clock provider * @{ + * * A master port has two media ports connected to it, and by convention * thay are called downstream and upstream ports. The media stream flowing to * the downstream port is called encoding or send direction, and media stream diff --git a/pjmedia/include/pjmedia/mem_port.h b/pjmedia/include/pjmedia/mem_port.h index 47b911f2..87780ad0 100644 --- a/pjmedia/include/pjmedia/mem_port.h +++ b/pjmedia/include/pjmedia/mem_port.h @@ -31,8 +31,9 @@ PJ_BEGIN_DECL /** * @defgroup PJMEDIA_MEM_PLAYER Memory/Buffer-based Playback Port * @ingroup PJMEDIA_PORT - * @brief Media playback from a fixed buffer + * @brief Media playback from a fixed size memory buffer * @{ + * * A memory/buffer based playback port is used to play media from a fixed * size buffer. This is useful over @ref PJMEDIA_FILE_PLAY for * situation where filesystems are not available in the target system. @@ -113,8 +114,9 @@ pjmedia_mem_player_set_eof_cb( pjmedia_port *port, /** * @defgroup PJMEDIA_MEM_CAPTURE Memory/Buffer-based Capture Port * @ingroup PJMEDIA_PORT - * @brief Capture to fixed size buffer + * @brief Media capture to fixed size memory buffer * @{ + * * A memory based capture is used to save media streams to a fixed size * buffer. This is useful over @ref PJMEDIA_FILE_REC for * situation where filesystems are not available in the target system. diff --git a/pjmedia/include/pjmedia/null_port.h b/pjmedia/include/pjmedia/null_port.h index ae1fb69b..ad8c8325 100644 --- a/pjmedia/include/pjmedia/null_port.h +++ b/pjmedia/include/pjmedia/null_port.h @@ -30,7 +30,7 @@ /** * @defgroup PJMEDIA_NULL_PORT Null Port * @ingroup PJMEDIA_PORT - * @brief Null port is the simplest type of port. + * @brief The simplest type of media port which does nothing. * @{ */ diff --git a/pjmedia/include/pjmedia/plc.h b/pjmedia/include/pjmedia/plc.h index 01d77b29..2a79f39b 100644 --- a/pjmedia/include/pjmedia/plc.h +++ b/pjmedia/include/pjmedia/plc.h @@ -29,10 +29,13 @@ /** * @defgroup PJMED_PLC Packet Lost Concealment (PLC) * @ingroup PJMEDIA_FRAME_OP + * @brief Packet lost compensation algorithm * @{ + * * This section describes PJMEDIA's implementation of Packet Lost * Concealment algorithm. This algorithm is used to implement PLC for - * codecs that do not have built-in support for one (e.g. G.711 or GSM codecs). + * codecs that do not have built-in support for one (e.g. G.711 or GSM + * codecs). * * The PLC algorithm (either built-in or external) is embedded in * PJMEDIA codec instance, and application can conceal lost frames diff --git a/pjmedia/include/pjmedia/port.h b/pjmedia/include/pjmedia/port.h index 3edea1dc..07c86664 100644 --- a/pjmedia/include/pjmedia/port.h +++ b/pjmedia/include/pjmedia/port.h @@ -28,10 +28,9 @@ /** - @defgroup PJMEDIA_PORT_CONCEPT Media Ports Framework - @ingroup PJMEDIA - @brief Extensible framework for media terminations - + @addtogroup PJMEDIA_PORT Media Ports Framework + @{ + @section media_port_intro Media Port Concepts @subsection The Media Port @@ -165,64 +164,7 @@ PJMEDIA provides few mechanisms to make media flows automatically among media ports. This concept is described in @ref PJMEDIA_PORT_CLOCK section. - - */ - - -/** - * @defgroup PJMEDIA_PORT_INTERFACE Media Port Interface - * @ingroup PJMEDIA_PORT_CONCEPT - * @brief Declares the media port interface. - */ - -/** - * @defgroup PJMEDIA_PORT Ports - * @ingroup PJMEDIA_PORT_CONCEPT - * @brief Contains various types of media ports/terminations. - * @{ - * This page lists all types of media ports currently implemented - * in PJMEDIA. The media port concept is explained in @ref PJMEDIA_PORT_CONCEPT. - * @} - */ - -/** - @defgroup PJMEDIA_PORT_CLOCK Clock/Timing - @ingroup PJMEDIA_PORT_CONCEPT - @brief Various types of classes that provide timing. - @{ - - The media clock/timing extends the media port concept that is explained - in @ref PJMEDIA_PORT_CONCEPT. When clock is present in the ports - interconnection, media will flow automatically (and with correct timing too!) - from one media port to another. - - There are few objects in PJMEDIA that are able to provide clock/timing - to media ports interconnection: - - - @ref PJMED_SND_PORT\n - The sound device makes a good candidate as the clock source, and - PJMEDIA @ref PJMED_SND is designed so that it is able to invoke - operations according to timing driven by the sound hardware clock - (this may sound complicated, but actually it just means that - the sound device abstraction provides callbacks to be called when - it has/wants media frames).\n - See @ref PJMED_SND_PORT for more details. - - - @ref PJMEDIA_MASTER_PORT\n - The master port uses @ref PJMEDIA_CLOCK as the clock source. By using - @ref PJMEDIA_MASTER_PORT, it is possible to interconnect passive - media ports and let the frames flow automatically in timely manner.\n - Please see @ref PJMEDIA_MASTER_PORT for more details. - - @} - */ - -/** - * @addtogroup PJMEDIA_PORT_INTERFACE - * @{ - * This page contains the media port interface declarations. The media port - * concept is explained in @ref PJMEDIA_PORT_CONCEPT. - */ +*/ PJ_BEGIN_DECL @@ -230,7 +172,7 @@ PJ_BEGIN_DECL /** * Port operation setting. */ -enum pjmedia_port_op +typedef enum pjmedia_port_op { /** * No change to the port TX or RX settings. @@ -253,13 +195,8 @@ enum pjmedia_port_op * Enable TX and RX to/from this port. */ PJMEDIA_PORT_ENABLE -}; - -/** - * @see pjmedia_port_op - */ -typedef enum pjmedia_port_op pjmedia_port_op; +} pjmedia_port_op; /** @@ -296,7 +233,7 @@ typedef enum pjmedia_frame_type /** * This structure describes a media frame. */ -struct pjmedia_frame +typedef struct pjmedia_frame { pjmedia_frame_type type; /**< Frame type. */ void *buf; /**< Pointer to buffer. */ @@ -307,30 +244,13 @@ struct pjmedia_frame at the octet boundary, so this field may be used for specifying start & end bit offset. */ -}; - - -/** - * @see pjmedia_frame - */ -typedef struct pjmedia_frame pjmedia_frame; +} pjmedia_frame; /** - * For future graph. - */ -typedef struct pjmedia_graph pjmedia_graph; - - -/** - * @see pjmedia_port - */ -typedef struct pjmedia_port pjmedia_port; - -/** * Port interface. */ -struct pjmedia_port +typedef struct pjmedia_port { pjmedia_port_info info; /**< Port information. */ @@ -346,21 +266,22 @@ struct pjmedia_port * Sink interface. * This should only be called by #pjmedia_port_put_frame(). */ - pj_status_t (*put_frame)(pjmedia_port *this_port, + pj_status_t (*put_frame)(struct pjmedia_port *this_port, const pjmedia_frame *frame); /** * Source interface. * This should only be called by #pjmedia_port_get_frame(). */ - pj_status_t (*get_frame)(pjmedia_port *this_port, + pj_status_t (*get_frame)(struct pjmedia_port *this_port, pjmedia_frame *frame); /** * Called to destroy this port. */ - pj_status_t (*on_destroy)(pjmedia_port *this_port); -}; + pj_status_t (*on_destroy)(struct pjmedia_port *this_port); + +} pjmedia_port; /** diff --git a/pjmedia/include/pjmedia/resample.h b/pjmedia/include/pjmedia/resample.h index 8aad5087..4ed4caf3 100644 --- a/pjmedia/include/pjmedia/resample.h +++ b/pjmedia/include/pjmedia/resample.h @@ -31,8 +31,9 @@ /** * @defgroup PJMEDIA_RESAMPLE Resampling Algorithm * @ingroup PJMEDIA_FRAME_OP - * @brief Functions to alter frame's clock rate. + * @brief Sample rate conversion algorithm * @{ + * * This section describes the base resampling functions. In addition to this, * application can use the @ref PJMEDIA_RESAMPLE_PORT which provides * media port abstraction for the base resampling algorithm. @@ -122,9 +123,10 @@ PJ_DECL(void) pjmedia_resample_destroy(pjmedia_resample *resample); /** * @defgroup PJMEDIA_RESAMPLE_PORT Resample Port * @ingroup PJMEDIA_PORT - * @brief Media port interface to change media stream's sampling rate. + * @brief Audio sample rate conversion * @{ - * This section describes media port abstractoin for @ref PJMEDIA_RESAMPLE. + * + * This section describes media port abstraction for @ref PJMEDIA_RESAMPLE. */ diff --git a/pjmedia/include/pjmedia/rtcp.h b/pjmedia/include/pjmedia/rtcp.h index 5328a423..f6bf625b 100644 --- a/pjmedia/include/pjmedia/rtcp.h +++ b/pjmedia/include/pjmedia/rtcp.h @@ -33,8 +33,10 @@ PJ_BEGIN_DECL /** * @defgroup PJMED_RTCP RTCP Session and Encapsulation (RFC 3550) - * @ingroup PJMEDIA_TRANSPORT + * @ingroup PJMEDIA_SESSION + * @brief RTCP format and session management * @{ + * * PJMEDIA implements subsets of RTCP specification (RFC 3550) to monitor * the quality of the real-time media (audio/video) transmission. In * addition to the standard quality monitoring and reporting with RTCP diff --git a/pjmedia/include/pjmedia/rtcp_xr.h b/pjmedia/include/pjmedia/rtcp_xr.h index c1eafa97..6943ac41 100644 --- a/pjmedia/include/pjmedia/rtcp_xr.h +++ b/pjmedia/include/pjmedia/rtcp_xr.h @@ -33,8 +33,10 @@ PJ_BEGIN_DECL /** * @defgroup PJMED_RTCP_XR RTCP Extended Report (XR) - RFC 3611 - * @ingroup PJMEDIA_TRANSPORT + * @ingroup PJMEDIA_SESSION + * @brief RTCP XR extension to RTCP session * @{ + * * PJMEDIA implements subsets of RTCP XR specification (RFC 3611) to monitor * the quality of the real-time media (audio/video) transmission. */ diff --git a/pjmedia/include/pjmedia/rtp.h b/pjmedia/include/pjmedia/rtp.h index a21b1f16..6505d796 100644 --- a/pjmedia/include/pjmedia/rtp.h +++ b/pjmedia/include/pjmedia/rtp.h @@ -32,7 +32,8 @@ PJ_BEGIN_DECL /** * @defgroup PJMED_RTP RTP Session and Encapsulation (RFC 3550) - * @ingroup PJMEDIA_TRANSPORT + * @ingroup PJMEDIA_SESSION + * @brief RTP format and session management * @{ * * The RTP module is designed to be dependent only to PJLIB, it does not depend diff --git a/pjmedia/include/pjmedia/sdp.h b/pjmedia/include/pjmedia/sdp.h index 73c4393d..06f11509 100644 --- a/pjmedia/include/pjmedia/sdp.h +++ b/pjmedia/include/pjmedia/sdp.h @@ -29,6 +29,7 @@ /** * @defgroup PJMEDIA_SDP SDP Parsing and Data Structure * @ingroup PJMEDIA_SESSION + * @brief SDP data structure representation and parsing * @{ * * The basic SDP session descriptor and elements are described in header diff --git a/pjmedia/include/pjmedia/session.h b/pjmedia/include/pjmedia/session.h index 225044c7..2b768b80 100644 --- a/pjmedia/include/pjmedia/session.h +++ b/pjmedia/include/pjmedia/session.h @@ -32,13 +32,8 @@ PJ_BEGIN_DECL /** - * @defgroup PJMEDIA_SESSION Sessions - * @ingroup PJMEDIA - */ - -/** - * @defgroup PJMED_SES Media session - * @ingroup PJMEDIA_SESSION + * @defgroup PJMEDIA_SESSION Media Sessions + * @brief Management of media sessions * @{ * * A media session represents multimedia communication between two diff --git a/pjmedia/include/pjmedia/sound.h b/pjmedia/include/pjmedia/sound.h index ca9ccee4..8bac9a69 100644 --- a/pjmedia/include/pjmedia/sound.h +++ b/pjmedia/include/pjmedia/sound.h @@ -38,7 +38,7 @@ PJ_BEGIN_DECL * This section describes lower level abstraction for sound device * hardware. Application normally uses the higher layer @ref * PJMED_SND_PORT abstraction since it works seamlessly with - * @ref PJMEDIA_PORT_CONCEPT. + * @ref PJMEDIA_PORT. * * The sound hardware abstraction basically runs <b>asychronously</b>, * and application must register callbacks to be called to receive/ diff --git a/pjmedia/include/pjmedia/splitcomb.h b/pjmedia/include/pjmedia/splitcomb.h index 1771cd14..0ae87fa9 100644 --- a/pjmedia/include/pjmedia/splitcomb.h +++ b/pjmedia/include/pjmedia/splitcomb.h @@ -30,8 +30,10 @@ /** * @addtogroup PJMEDIA_SPLITCOMB Media channel splitter/combiner * @ingroup PJMEDIA_PORT - * @brief Split and combine media channels in media streams + * @brief Split and combine multiple mono-channel media ports into + * a single multiple-channels media port * @{ + * * This section describes media port to split and combine media * channels in the stream. * diff --git a/pjmedia/include/pjmedia/stereo.h b/pjmedia/include/pjmedia/stereo.h index 96eb3699..fa18a89b 100644 --- a/pjmedia/include/pjmedia/stereo.h +++ b/pjmedia/include/pjmedia/stereo.h @@ -32,9 +32,8 @@ /** * @defgroup PJMEDIA_STEREO Monochannel and multichannel audio frame converter - * @ingroup PJMEDIA_MISC - * @brief Interface for converting monochannel audio frame to multichannel - * audio frame and vice versa. + * @ingroup PJMEDIA_FRAME_OP + * @brief Mono - multi-channels audio conversion * @{ * */ diff --git a/pjmedia/include/pjmedia/stream.h b/pjmedia/include/pjmedia/stream.h index 551b90a9..daf3a0e5 100644 --- a/pjmedia/include/pjmedia/stream.h +++ b/pjmedia/include/pjmedia/stream.h @@ -39,7 +39,7 @@ PJ_BEGIN_DECL /** * @defgroup PJMED_STRM Streams * @ingroup PJMEDIA_PORT - * @brief Media port for communicating with remote peer via the network. + * @brief Communicating with remote peer via the network * @{ * * A media stream is a bidirectional multimedia communication between two @@ -50,7 +50,7 @@ PJ_BEGIN_DECL * - encoding channel, which transmits unidirectional media to remote, and * - decoding channel, which receives unidirectional media from remote. * - * A media stream exports media port interface (see @ref PJMEDIA_PORT_CONCEPT) + * A media stream exports media port interface (see @ref PJMEDIA_PORT) * and application normally uses this interface to interconnect the stream * to other PJMEDIA components. * @@ -61,7 +61,7 @@ PJ_BEGIN_DECL * direction), * - one instance of RTCP session (#pjmedia_rtcp_session), * - and a reference to media transport to send and receive packets - * to/from the network (see @ref PJMEDIA_TRANSPORT_H). + * to/from the network (see @ref PJMEDIA_TRANSPORT). * * Streams are created by calling #pjmedia_stream_create(), specifying * #pjmedia_stream_info structure in the parameter. Application can construct diff --git a/pjmedia/include/pjmedia/tonegen.h b/pjmedia/include/pjmedia/tonegen.h index ab591732..b98e97be 100644 --- a/pjmedia/include/pjmedia/tonegen.h +++ b/pjmedia/include/pjmedia/tonegen.h @@ -27,10 +27,11 @@ /** - * @defgroup PJMEDIA_MF_DTMF_TONE_GENERATOR Tone (sine, MF, DTMF) Generator + * @defgroup PJMEDIA_MF_DTMF_TONE_GENERATOR Multi-frequency tone generator * @ingroup PJMEDIA_PORT - * @brief Tone (sine, MF, DTMF) Generator + * @brief Multi-frequency tone generator * @{ + * * This page describes tone generator media port. A tone generator can be * used to generate a single frequency sine wave or dual frequency tones * such as DTMF. diff --git a/pjmedia/include/pjmedia/transport.h b/pjmedia/include/pjmedia/transport.h index 99043492..dc42e295 100644 --- a/pjmedia/include/pjmedia/transport.h +++ b/pjmedia/include/pjmedia/transport.h @@ -29,24 +29,13 @@ #include <pjmedia/errno.h> /** - * @defgroup PJMEDIA_TRANSPORT Media Transports - * @ingroup PJMEDIA + * @defgroup PJMEDIA_TRANSPORT Media Transport * @brief Transports. - * Transport related components. - */ - -/** - * @defgroup PJMEDIA_TRANSPORT_H Media Network Transport Interface - * @ingroup PJMEDIA_TRANSPORT - * @brief PJMEDIA object for sending/receiving media packets over the network * @{ * The media transport (#pjmedia_transport) is the object to send and * receive media packets over the network. The media transport interface * allows the library to be extended to support different types of - * transports to send and receive packets. Currently only the standard - * UDP transport implementation is provided (see \ref PJMEDIA_TRANSPORT_UDP), - * but application designer may extend the library to support other types - * of custom transports such as RTP/RTCP over TCP, RTP/RTCP over HTTP, etc. + * transports to send and receive packets. * * The media transport is declared as #pjmedia_transport "class", which * declares "interfaces" to use the class in #pjmedia_transport_op @@ -62,7 +51,7 @@ \image html media-transport.PNG - * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport + * \section PJMEDIA_TRANSPORT_H_USING Basic Media Transport Usage * * The media transport's life-cycle normally follows the following stages. * @@ -141,38 +130,71 @@ * all resources used by the transport, such as sockets and memory. * * - * \section PJMEDIA_TRANSPORT_H_EXT Media Transport Extended API + * \section offer_answer Interaction with SDP Offer/Answer - Apart from the basic interface above, the media transport provides some - more APIs: - - - pjmedia_transport_media_create() - \n - This API is provided to allow the media transport to add more information - in the SDP offer, before the offer is sent to remote. Additionally, for - answerer side, this callback allows the media transport to reject the - offer before this offer is processed by the SDP negotiator. - - - pjmedia_transport_media_start() - \n - This API should be called after offer and answer are negotiated, and - both SDPs are available, and before the media is started. For answerer - side, this callback will be called before the answer is sent to remote, - to allow media transport to put additional info in the SDP. For - offerer side, this callback will be called after SDP answer is - received. In this callback, the media transport has the final chance - to negotiate/validate the offer and answer before media is really - started (and answer is sent, for answerer side). - - - pjmedia_transport_media_stop() - \n - This API should be called when the media is stopped, to allow the media - transport to release its resources. - - - pjmedia_transport_simulate_lost() - \n - This API can be used to instruct media transport to simulate packet lost - on a particular direction. + For basic UDP transport, the \ref PJMEDIA_TRANSPORT_H_USING above is + sufficient to use the media transport. However, more complex media + transports such as \ref PJMEDIA_TRANSPORT_SRTP and \ref + PJMEDIA_TRANSPORT_ICE requires closer interactions with SDP offer and + answer negotiation. + + The media transports can interact with the SDP offer/answer via + these APIs: + - #pjmedia_transport_media_create(), to initialize the media transport + for new media session, + - #pjmedia_transport_encode_sdp(), to encode SDP offer or answer, + - #pjmedia_transport_media_start(), to activate the settings that + have been negotiated by SDP offer answer, and + - #pjmedia_transport_media_stop(), to deinitialize the media transport + and reset the transport to its idle state. + + The usage of these API in the context of SDP offer answer will be + described below. + + \subsection media_create Initializing Transport for New Session + + Application must call #pjmedia_transport_media_create() before using + the transport for a new session. + + \subsection creat_oa Creating SDP Offer and Answer + + The #pjmedia_transport_encode_sdp() is used to put additional information + from the transport to the local SDP, before the SDP is sent and negotiated + with remote SDP. + + When creating an offer, call #pjmedia_transport_encode_sdp() with + local SDP (and NULL as \a rem_sdp). The media transport will add the + relevant attributes in the local SDP. Application then gives the local + SDP to the invite session to be sent to remote agent. + + When creating an answer, also call #pjmedia_transport_encode_sdp(), + but this time specify both local and remote SDP to the function. The + media transport will once again modify the local SDP and add relevant + attributes to the local SDP, if the appropriate attributes related to + the transport functionality are present in remote offer. The remote + SDP does not contain the relevant attributes, then the specific transport + functionality will not be activated for the session. + + The #pjmedia_transport_encode_sdp() should also be called when application + sends subsequent SDP offer or answer. The media transport will encode + the appropriate attributes based on the state of the session. + + \subsection media_start Offer/Answer Completion + + Once both local and remote SDP have been negotiated by the + \ref PJMEDIA_SDP_NEG (normally this is part of PJSIP invite session), + application should give both local and remote SDP to + #pjmedia_transport_media_start() so that the settings are activated + for the session. This function should be called for both initial and + subsequent SDP negotiation. + + \subsection media_stop Stopping Transport + + Once session is stop application must call #pjmedia_transport_media_stop() + to deactivate the transport feature. Application may reuse the transport + for subsequent media session by repeating the #pjmedia_transport_media_create(), + #pjmedia_transport_encode_sdp(), #pjmedia_transport_media_start(), and + #pjmedia_transport_media_stop() above. * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport * @@ -198,15 +220,13 @@ * mutex protection, since it may be called by application's thread (for * example, to send RTP/RTCP packets). * - * For an example of media transport implementation, please refer to - * <tt>transport_udp.h</tt> and <tt>transport_udp.c</tt> in PJMEDIA source - * distribution. */ -PJ_BEGIN_DECL #include <pjmedia/sdp.h> +PJ_BEGIN_DECL + /** * Forward declaration for media transport. @@ -346,7 +366,7 @@ struct pjmedia_transport_op /** * This function is called by application to start the transport - * based on SDP negotiation result. + * based on local and remote SDP. * * Application should call #pjmedia_transport_media_start() instead of * calling this function directly. @@ -413,7 +433,7 @@ typedef enum pjmedia_transport_type /** - * This structure declares stream transport. A stream transport is called + * This structure declares media transport. A media transport is called * by the stream to transmit a packet, and will notify stream when * incoming packet is arrived. */ @@ -637,8 +657,7 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp2(pjmedia_transport *tp, /** - * Prepare the media transport for a new media session, and optionally - * encode the relevant information in the \a sdp_local. Application must + * Prepare the media transport for a new media session, Application must * call this function before starting a new media session using this * transport. * @@ -648,8 +667,9 @@ PJ_INLINE(pj_status_t) pjmedia_transport_send_rtcp2(pjmedia_transport *tp, * @param tp The media transport. * @param sdp_pool Pool object to allocate memory related to SDP * messaging components. - * @param option Option flags, from #pjmedia_tranport_media_option - * @param rem_sdp Remote SDP if it's available. + * @param options Option flags, from #pjmedia_tranport_media_option + * @param rem_sdp Remote SDP if local SDP is an answer, otherwise + * specify NULL if SDP is an offer. * @param media_index Media index in SDP. * * @return PJ_SUCCESS on success, or the appropriate error code. @@ -667,8 +687,8 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp, /** * Put transport specific information into the SDP. This function can be - * called to create SDP offer or answer, depending whether \a rem_sdp - * parameter is present. + * called to put transport specific information in the initial or + * subsequent SDP offer or answer. * * This is just a simple wrapper which calls <tt>encode_sdp()</tt> member * of the transport. @@ -678,7 +698,8 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_create(pjmedia_transport *tp, * messaging components. * @param sdp The local SDP to be filled in information from the * media transport. - * @param rem_sdp Remote SDP if it's available. + * @param rem_sdp Remote SDP if local SDP is an answer, otherwise + * specify NULL if SDP is an offer. * @param media_index Media index in SDP. * * @return PJ_SUCCESS on success, or the appropriate error code. @@ -694,25 +715,20 @@ PJ_INLINE(pj_status_t) pjmedia_transport_encode_sdp(pjmedia_transport *tp, /** - * Start the transport with regards to SDP negotiation result. - * This API should be called after offer and answer are negotiated, and - * both SDPs are available, and before the media is started. For answerer - * side, this callback will be called before the answer is sent to remote, - * to allow media transport to put additional info in the SDP. For - * offerer side, this callback will be called after SDP answer is - * received. In this callback, the media transport has the final chance - * to negotiate/validate the offer and answer before media is really - * started (and answer is sent, for answerer side). + * Start the transport session with the settings in both local and remote + * SDP. The actual work that is done by this function depends on the + * underlying transport type. For SRTP, this will activate the encryption + * and decryption based on the keys found the SDPs. For ICE, this will + * start ICE negotiation according to the information found in the SDPs. * * This is just a simple wrapper which calls <tt>media_start()</tt> member * of the transport. * * @param tp The media transport. * @param tmp_pool The memory pool for allocating temporary objects. - * @param option The media transport option. * @param sdp_local Local SDP. * @param sdp_remote Remote SDP. - * @param media_index Media index to start. + * @param media_index Media index in the SDP. * * @return PJ_SUCCESS on success, or the appropriate error code. */ @@ -728,9 +744,8 @@ PJ_INLINE(pj_status_t) pjmedia_transport_media_start(pjmedia_transport *tp, /** - * Stop the transport. - * This API should be called when the media is stopped, to allow the media - * transport to release its resources. + * This API should be called when the session is stopped, to allow the media + * transport to release its resources used for the session. * * This is just a simple wrapper which calls <tt>media_stop()</tt> member * of the transport. diff --git a/pjmedia/include/pjmedia/transport_ice.h b/pjmedia/include/pjmedia/transport_ice.h index f3fc9a04..b5385659 100644 --- a/pjmedia/include/pjmedia/transport_ice.h +++ b/pjmedia/include/pjmedia/transport_ice.h @@ -30,10 +30,13 @@ /** - * @defgroup PJMEDIA_TRANSPORT_ICE ICE Capable media transport + * @defgroup PJMEDIA_TRANSPORT_ICE ICE Media Transport * @ingroup PJMEDIA_TRANSPORT - * @brief Implementation of media transport with ICE. + * @brief Interactive Connectivity Establishment (ICE) transport * @{ + * + * This describes the implementation of media transport using + * Interactive Connectivity Establishment (ICE) protocol. */ PJ_BEGIN_DECL @@ -57,15 +60,29 @@ typedef struct pjmedia_ice_cb } pjmedia_ice_cb; + /** - * Create the media transport. + * Create the Interactive Connectivity Establishment (ICE) media transport + * using the specified configuration. When STUN or TURN (or both) is used, + * the creation operation will complete asynchronously, when STUN resolution + * and TURN allocation completes. When the initialization completes, the + * \a on_ice_complete() complete will be called with \a op parameter equal + * to PJ_ICE_STRANS_OP_INIT. + * + * In addition, this transport will also notify the application about the + * result of ICE negotiation, also in \a on_ice_complete() callback. In this + * case the callback will be called with \a op parameter equal to + * PJ_ICE_STRANS_OP_NEGOTIATION. + * + * Other than this, application should use the \ref PJMEDIA_TRANSPORT API + * to manipulate this media transport. * * @param endpt The media endpoint. * @param name Optional name to identify this ICE media transport * for logging purposes. * @param comp_cnt Number of components to be created. * @param cfg Pointer to configuration settings. - * @param cb Optional callbacks. + * @param cb Optional structure containing ICE specific callbacks. * @param p_tp Pointer to receive the media transport instance. * * @return PJ_SUCCESS on success, or the appropriate error code. diff --git a/pjmedia/include/pjmedia/transport_srtp.h b/pjmedia/include/pjmedia/transport_srtp.h index d2b6a015..6c87f1e2 100644 --- a/pjmedia/include/pjmedia/transport_srtp.h +++ b/pjmedia/include/pjmedia/transport_srtp.h @@ -20,7 +20,7 @@ #define __PJMEDIA_TRANSPORT_SRTP_H__ /** - * @file srtp.h + * @file transport_srtp.h * @brief Secure RTP (SRTP) transport. */ @@ -28,13 +28,13 @@ /** - * @defgroup PJMEDIA_TRANSPORT_SRTP Secure RTP (SRTP) Transport Adapter + * @defgroup PJMEDIA_TRANSPORT_SRTP Secure RTP (SRTP) Media Transport * @ingroup PJMEDIA_TRANSPORT * @brief Media transport adapter to add SRTP feature to existing transports * @{ * * This module implements SRTP as described by RFC 3711, using RFC 4568 as - * key exchange method. It implements \ref PJMEDIA_TRANSPORT_H to integrate + * key exchange method. It implements \ref PJMEDIA_TRANSPORT to integrate * with the rest of PJMEDIA framework. * * As we know, media transport is separated from the stream object (which diff --git a/pjmedia/include/pjmedia/transport_udp.h b/pjmedia/include/pjmedia/transport_udp.h index 5bf5b19d..720d01a2 100644 --- a/pjmedia/include/pjmedia/transport_udp.h +++ b/pjmedia/include/pjmedia/transport_udp.h @@ -29,10 +29,14 @@ /** - * @defgroup PJMEDIA_TRANSPORT_UDP UDP Socket Transport + * @defgroup PJMEDIA_TRANSPORT_UDP UDP Media Transport * @ingroup PJMEDIA_TRANSPORT * @brief Implementation of media transport with UDP sockets. * @{ + * + * The UDP media transport is the standard based media transport + * as described by RFC 3550/3551. It can be used to facilitate RTP/RTCP + * unicast or multicast communication. */ PJ_BEGIN_DECL diff --git a/pjmedia/include/pjmedia/types.h b/pjmedia/include/pjmedia/types.h index fe3b2349..2c3140c5 100644 --- a/pjmedia/include/pjmedia/types.h +++ b/pjmedia/include/pjmedia/types.h @@ -28,15 +28,15 @@ #include <pj/sock.h> /* pjmedia_sock_info */ #include <pj/string.h> /* pj_memcpy(), pj_memset() */ - /** - * @defgroup PJMEDIA_FRAME_OP Frame Operations - * @ingroup PJMEDIA + * @defgroup PJMEDIA_PORT Media Ports Framework + * @brief Extensible framework for media terminations */ + /** - * @defgroup PJMEDIA_MISC Misc - * @ingroup PJMEDIA + * @defgroup PJMEDIA_FRAME_OP Audio Manipulation Algorithms + * @brief Algorithms to manipulate audio frames */ /** diff --git a/pjmedia/include/pjmedia/wav_playlist.h b/pjmedia/include/pjmedia/wav_playlist.h index 42653d4f..9370d049 100644 --- a/pjmedia/include/pjmedia/wav_playlist.h +++ b/pjmedia/include/pjmedia/wav_playlist.h @@ -33,8 +33,9 @@ PJ_BEGIN_DECL /** * @defgroup PJMEDIA_WAV_PLAYLIST WAV File Play List * @ingroup PJMEDIA_PORT - * @brief WAV File Playlist + * @brief Audio playback of multiple WAV files * @{ + * * The WAV play list port enables application to play back multiple * WAV files in a playlist. */ diff --git a/pjmedia/include/pjmedia/wav_port.h b/pjmedia/include/pjmedia/wav_port.h index 889eea7b..f11cec94 100644 --- a/pjmedia/include/pjmedia/wav_port.h +++ b/pjmedia/include/pjmedia/wav_port.h @@ -33,7 +33,7 @@ PJ_BEGIN_DECL /** * @defgroup PJMEDIA_FILE_PLAY WAV File Player * @ingroup PJMEDIA_PORT - * @brief WAV File Player + * @brief Audio playback from WAV file * @{ */ @@ -137,7 +137,7 @@ pjmedia_wav_player_set_eof_cb( pjmedia_port *port, /** * @defgroup PJMEDIA_FILE_REC File Writer (Recorder) * @ingroup PJMEDIA_PORT - * @brief WAV File Writer (Recorder) + * @brief Audio capture/recording to WAV file * @{ */ diff --git a/pjmedia/include/pjmedia/wave.h b/pjmedia/include/pjmedia/wave.h index 0581b76a..369599fc 100644 --- a/pjmedia/include/pjmedia/wave.h +++ b/pjmedia/include/pjmedia/wave.h @@ -26,13 +26,21 @@ */ #include <pjmedia/types.h> +/** + * @defgroup PJMEDIA_FILE_FORMAT File Formats + * @brief Supported file formats + */ + /** * @defgroup PJMEDIA_WAVE WAVE Header - * @ingroup PJMEDIA_MISC + * @ingroup PJMEDIA_FILE_FORMAT + * @brief Representation of RIFF/WAVE file format * @{ * - * Supports for simple/canonical Microsoft RIFF WAVE format. + * This the the low level representation of RIFF/WAVE file format. For + * higher abstraction, please see \ref PJMEDIA_FILE_PLAY and + * \ref PJMEDIA_FILE_REC. */ diff --git a/pjmedia/include/pjmedia/wsola.h b/pjmedia/include/pjmedia/wsola.h index 891753a9..d209dab4 100644 --- a/pjmedia/include/pjmedia/wsola.h +++ b/pjmedia/include/pjmedia/wsola.h @@ -28,12 +28,16 @@ /** * @defgroup PJMED_WSOLA Waveform Similarity Based Overlap-Add (WSOLA) * @ingroup PJMEDIA_FRAME_OP + * @brief Time-scale modification to audio without affecting the pitch * @{ + * * This section describes Waveform Similarity Based Overlap-Add (WSOLA) * implementation in PJMEDIA. The WSOLA API here can be used both to * compress (speed-up) and stretch (expand, slow down) audio playback * without altering the pitch, or as a mean for performing packet loss * concealment (WSOLA). + * + * The WSOLA implementation is used by \ref PJMED_DELAYBUF and \ref PJMED_PLC. */ PJ_BEGIN_DECL diff --git a/pjnath/build/Makefile b/pjnath/build/Makefile index 9292ba59..3322d73b 100644 --- a/pjnath/build/Makefile +++ b/pjnath/build/Makefile @@ -78,7 +78,11 @@ TARGETS := pjnath pjnath-test pjturn-client pjturn-srv all: $(TARGETS) doc: - cd .. && doxygen docs/doxygen.cfg + cd .. && rm -rf docs/html docs/latex && doxygen docs/doxygen.cfg + @if test ! "$(WWWDIR)" == ""; then \ + echo "Copying to $(WWWDIR)/pjnath/docs/html.." ; \ + cp -a ../docs/html/* $(WWWDIR)/pjnath/docs/html/ ; \ + fi dep: depend distclean: realclean diff --git a/pjnath/docs/UML-class-diagram.dia b/pjnath/docs/UML-class-diagram.dia Binary files differindex ac9ffd3e..4e54231a 100644 --- a/pjnath/docs/UML-class-diagram.dia +++ b/pjnath/docs/UML-class-diagram.dia diff --git a/pjnath/docs/UML-class-diagram.png b/pjnath/docs/UML-class-diagram.png Binary files differindex 49c68519..d3c08e9c 100644 --- a/pjnath/docs/UML-class-diagram.png +++ b/pjnath/docs/UML-class-diagram.png diff --git a/pjnath/docs/doxygen.cfg b/pjnath/docs/doxygen.cfg index e769deb1..f7da72b2 100644 --- a/pjnath/docs/doxygen.cfg +++ b/pjnath/docs/doxygen.cfg @@ -294,6 +294,7 @@ OPTIMIZE_OUTPUT_JAVA = NO # list will mention the files that were used to generate the documentation.
SHOW_USED_FILES = YES
+TYPEDEF_HIDES_STRUCT = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
@@ -870,12 +871,12 @@ SKIP_FUNCTION_MACROS = YES # The TAGFILES tag can be used to specify one or more tagfiles.
-TAGFILES =
+TAGFILES = ../pjlib/docs/pjlib.tag=../../../pjlib/docs/html ../pjlib-util/docs/pjlib-util.tag=../../../pjlib-util/docs/html ../pjsip/docs/pjsip.tag=../../../pjsip/docs/html ../pjmedia/docs/pjmedia.tag=../../../pjmedia/docs/html
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = ../pjnath/docs/pjnath.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
@@ -887,12 +888,13 @@ ALLEXTERNALS = NO # in the modules index. If set to NO, only the current project's groups will
# be listed.
-EXTERNAL_GROUPS = YES
+EXTERNAL_GROUPS = NO
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
-PERL_PATH = /usr/bin/perl
+#PERL_PATH = /usr/bin/perl
+PERL_PATH = /c/Perl/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
diff --git a/pjnath/docs/footer.html b/pjnath/docs/footer.html index b2b7f567..a91856b4 100644 --- a/pjnath/docs/footer.html +++ b/pjnath/docs/footer.html @@ -1,7 +1,7 @@ <p> </p>
<hr><center>
PJNATH - Open Source NAT traversal helper library supporting STUN, TURN, and ICE<br>
-(C)2001-2007 Benny Prijono
+(C)2001-2008 Benny Prijono
</center>
diff --git a/pjnath/include/pjnath/stun_sock.h b/pjnath/include/pjnath/stun_sock.h index a5ac7f69..248b5dcd 100644 --- a/pjnath/include/pjnath/stun_sock.h +++ b/pjnath/include/pjnath/stun_sock.h @@ -37,6 +37,7 @@ PJ_BEGIN_DECL * @brief STUN aware socket transport * @ingroup PJNATH_STUN * @{ + * * The STUN transport provides asynchronous UDP like socket transport * with the additional capability to query the publicly mapped transport * address (using STUN resolution), to refresh the NAT binding, and to @@ -128,13 +129,13 @@ typedef struct pj_stun_sock_cb * the STUN server, this callback will be called with \a op argument * set to PJ_STUN_SOCK_BINDING_OP \a status argument set to * PJ_SUCCESS. - * - anytime when the transport has detected that the publicly mapped + * - anytime when the transport has detected that the publicly mapped * address has changed, this callback will be called with \a op * argument set to PJ_STUN_SOCK_KEEP_ALIVE_OP and \a status * argument set to PJ_SUCCESS. On this case and the case above, * application will get the resolved public address in the * #pj_stun_sock_info structure. - * - for any terminal error (such as STUN time-out, DNS resolution + * - for any terminal error (such as STUN time-out, DNS resolution * failure, or keep-alive failure), this callback will be called * with the \a status argument set to non-PJ_SUCCESS. * diff --git a/pjsip-apps/build/Makefile b/pjsip-apps/build/Makefile index 134850b0..0704abb1 100644 --- a/pjsip-apps/build/Makefile +++ b/pjsip-apps/build/Makefile @@ -50,7 +50,6 @@ TARGETS := pjsua samples all: $(TARGETS) doc: - cd .. && doxygen docs/doxygen.cfg dep: depend distclean: realclean diff --git a/pjsip/build/Makefile b/pjsip/build/Makefile index 8d746f01..ef78f420 100644 --- a/pjsip/build/Makefile +++ b/pjsip/build/Makefile @@ -109,7 +109,11 @@ TARGETS := pjsip pjsip-ua pjsip-simple pjsua-lib pjsip-test all: $(TARGETS) doc: - cd .. && doxygen docs/doxygen.cfg + cd .. && rm -rf docs/html docs/latex && doxygen docs/doxygen.cfg + @if test ! "$(WWWDIR)" == ""; then \ + echo "Copying to $(WWWDIR)/pjsip/docs/html.." ; \ + cp -a ../docs/html/* $(WWWDIR)/pjsip/docs/html/ ; \ + fi dep: depend distclean: realclean diff --git a/pjsip/docs/doxygen.cfg b/pjsip/docs/doxygen.cfg index 1c5aad49..fc87325d 100644 --- a/pjsip/docs/doxygen.cfg +++ b/pjsip/docs/doxygen.cfg @@ -295,6 +295,7 @@ OPTIMIZE_OUTPUT_JAVA = NO # list will mention the files that were used to generate the documentation.
SHOW_USED_FILES = YES
+TYPEDEF_HIDES_STRUCT = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
@@ -869,12 +870,12 @@ SKIP_FUNCTION_MACROS = YES # The TAGFILES tag can be used to specify one or more tagfiles.
-TAGFILES =
+TAGFILES = ../pjlib/docs/pjlib.tag=../../../pjlib/docs/html ../pjlib-util/docs/pjlib-util.tag=../../../pjlib-util/docs/html ../pjnath/docs/pjnath.tag=../../../pjnath/docs/html ../pjmedia/docs/pjmedia.tag=../../../pjmedia/docs/html
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = docs/pjsip.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
@@ -886,12 +887,13 @@ ALLEXTERNALS = NO # in the modules index. If set to NO, only the current project's groups will
# be listed.
-EXTERNAL_GROUPS = YES
+EXTERNAL_GROUPS = NO
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
-PERL_PATH = /usr/bin/perl
+#PERL_PATH = /usr/bin/perl
+PERL_PATH = /c/Perl/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
diff --git a/pjsip/docs/footer.html b/pjsip/docs/footer.html index 9ee1ac28..0b6d806a 100644 --- a/pjsip/docs/footer.html +++ b/pjsip/docs/footer.html @@ -1,7 +1,7 @@ <p> </p>
<hr><center>
PJSIP Open Source, high performance, small footprint, and very very portable SIP stack<br>
-(C)2003-2007 Benny Prijono
+(C)2003-2008 Benny Prijono
</center>
<!--#include virtual="/footer.html" -->
diff --git a/pjsip/include/pjsip-ua/sip_inv.h b/pjsip/include/pjsip-ua/sip_inv.h index 448718dd..96c6824c 100644 --- a/pjsip/include/pjsip-ua/sip_inv.h +++ b/pjsip/include/pjsip-ua/sip_inv.h @@ -31,7 +31,6 @@ /** * @defgroup PJSIP_HIGH_UA User Agent Library - * @ingroup PJSIP * @brief Mid-level User Agent Library. * * This is the high level user agent library, which consists of: diff --git a/pjsip/include/pjsip/sip_config.h b/pjsip/include/pjsip/sip_config.h index a63e2250..4ef2ce61 100644 --- a/pjsip/include/pjsip/sip_config.h +++ b/pjsip/include/pjsip/sip_config.h @@ -26,12 +26,7 @@ #include <pj/types.h> /** - * @defgroup PJSIP PJSIP Library Collection - */ - -/** * @defgroup PJSIP_CORE Core SIP Library - * @ingroup PJSIP * @brief The core framework from which all other SIP components depends on. * * The PJSIP Core library only provides transport framework, event diff --git a/pjsip/include/pjsip/sip_transaction.h b/pjsip/include/pjsip/sip_transaction.h index 2865b6e1..a5863da3 100644 --- a/pjsip/include/pjsip/sip_transaction.h +++ b/pjsip/include/pjsip/sip_transaction.h @@ -33,7 +33,6 @@ PJ_BEGIN_DECL /** * @defgroup PJSIP_TRANSACT Transaction Layer - * @ingroup PJSIP * @brief Provides statefull message processing. * * This module provides stateful processing to incoming or outgoing SIP diff --git a/pjsip/include/pjsip/sip_ua_layer.h b/pjsip/include/pjsip/sip_ua_layer.h index 19852777..56029bda 100644 --- a/pjsip/include/pjsip/sip_ua_layer.h +++ b/pjsip/include/pjsip/sip_ua_layer.h @@ -30,7 +30,6 @@ PJ_BEGIN_DECL /** * @defgroup PJSIP_UA Base User Agent Layer/Common Dialog Layer - * @ingroup PJSIP * @brief Dialog management. * * This module provides basic dialog management, which is used by higher diff --git a/pjsip/include/pjsip/sip_util.h b/pjsip/include/pjsip/sip_util.h index 92264be6..32b6860d 100644 --- a/pjsip/include/pjsip/sip_util.h +++ b/pjsip/include/pjsip/sip_util.h @@ -582,7 +582,6 @@ PJ_DECL(pj_status_t) pjsip_endpt_send_request( pjsip_endpoint *endpt, /** * @defgroup PJSIP_PROXY_CORE Core Proxy Layer - * @ingroup PJSIP * @brief Core proxy operations * @{ */ diff --git a/pjsip/include/pjsip_simple.h b/pjsip/include/pjsip_simple.h index d81f0515..8dd4e6b3 100644 --- a/pjsip/include/pjsip_simple.h +++ b/pjsip/include/pjsip_simple.h @@ -19,7 +19,6 @@ /** * @defgroup PJSIP_SIMPLE Event and Presence Framework - * @ingroup PJSIP */ /** diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index 0ee97f9c..65ccf307 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -55,7 +55,6 @@ PJ_BEGIN_DECL /** * @defgroup PJSUA_LIB PJSUA API - High Level Softphone API for C/C++ and Python - * @ingroup PJSIP * @brief Very high level API for constructing SIP UA applications. * @{ * diff --git a/third_party/build/Makefile b/third_party/build/Makefile index 73d6ab2d..36d80612 100644 --- a/third_party/build/Makefile +++ b/third_party/build/Makefile @@ -12,3 +12,5 @@ all clean dep depend distclean realclean: fi; \ done +doc: + |
