Changeset 518


Ignore:
Timestamp:
Jun 18, 2006 2:02:36 AM (18 years ago)
Author:
bennylp
Message:

Updated doxygen documentation to all headers in PJMEDIA

Location:
pjproject/trunk
Files:
3 added
41 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjmedia/build/Makefile

    r477 r518  
    9393                speex/exc_10_32_table.o speex/exc_20_32_table.o \ 
    9494                speex/exc_5_256_table.o speex/exc_5_64_table.o \ 
    95                 speex/exc_8_128_table.o speex/filters.o \ 
     95                speex/exc_8_128_table.o speex/fftwrap.c speex/filters.o \ 
    9696                speex/gain_table.o speex/gain_table_lbr.o \ 
    9797                speex/hexc_10_32_table.o speex/hexc_table.o \ 
    98                 speex/high_lsp_tables.o speex/lpc_spx.o \ 
     98                speex/high_lsp_tables.o speex/jitter.c \ 
     99                speex/kiss_fft.c speex/kiss_fftr.c speex/lpc_spx.o \ 
    99100                speex/lsp.o speex/lsp_tables_nb.o speex/ltp.o \ 
    100                 speex/math_approx.o speex/misc.o speex/modes.o \ 
     101                speex/math_approx.o speex/misc.o speex/mdf.c speex/modes.o \ 
    101102                speex/nb_celp.o speex/preprocess_spx.o \ 
    102103                speex/quant_lsp.o speex/sb_celp.o speex/smallft.o \ 
  • pjproject/trunk/pjmedia/build/pjmedia.dsp

    r492 r518  
    312312# Begin Source File 
    313313 
     314SOURCE=..\include\pjmedia\transport.h 
     315# End Source File 
     316# Begin Source File 
     317 
    314318SOURCE=..\include\pjmedia\transport_udp.h 
    315319# End Source File 
  • pjproject/trunk/pjmedia/build/pjmedia_codec.dsp

    r411 r518  
    227227# Begin Source File 
    228228 
     229SOURCE="..\src\pjmedia-codec\speex\_kiss_fft_guts.h" 
     230# End Source File 
     231# Begin Source File 
     232 
    229233SOURCE="..\src\pjmedia-codec\speex\arch.h" 
    230234# End Source File 
     
    251255# Begin Source File 
    252256 
     257SOURCE="..\src\pjmedia-codec\speex\fftwrap.h" 
     258# End Source File 
     259# Begin Source File 
     260 
    253261SOURCE="..\src\pjmedia-codec\speex\filters.h" 
    254262# End Source File 
     
    284292 
    285293SOURCE="..\src\pjmedia-codec\speex\fixed_generic.h" 
     294# End Source File 
     295# Begin Source File 
     296 
     297SOURCE="..\src\pjmedia-codec\speex\kiss_fft.h" 
     298# End Source File 
     299# Begin Source File 
     300 
     301SOURCE="..\src\pjmedia-codec\speex\kiss_fftr.h" 
    286302# End Source File 
    287303# Begin Source File 
     
    455471# Begin Source File 
    456472 
     473SOURCE="..\src\pjmedia-codec\speex\fftwrap.c" 
     474# End Source File 
     475# Begin Source File 
     476 
    457477SOURCE="..\src\pjmedia-codec\speex\filters.c" 
    458478# ADD CPP /W4 
     
    485505# Begin Source File 
    486506 
     507SOURCE="..\src\pjmedia-codec\speex\jitter.c" 
     508# End Source File 
     509# Begin Source File 
     510 
     511SOURCE="..\src\pjmedia-codec\speex\kiss_fft.c" 
     512# End Source File 
     513# Begin Source File 
     514 
     515SOURCE="..\src\pjmedia-codec\speex\kiss_fftr.c" 
     516# End Source File 
     517# Begin Source File 
     518 
    487519SOURCE="..\src\pjmedia-codec\speex\lpc_spx.c" 
    488520# ADD CPP /W4 
     
    507539SOURCE="..\src\pjmedia-codec\speex\math_approx.c" 
    508540# ADD CPP /W4 
     541# End Source File 
     542# Begin Source File 
     543 
     544SOURCE="..\src\pjmedia-codec\speex\mdf.c" 
    509545# End Source File 
    510546# Begin Source File 
  • pjproject/trunk/pjmedia/docs/doxygen.cfg

    r189 r518  
    1818# by quotes) that should identify the project. 
    1919 
    20 PROJECT_NAME           =  PJMEDIA 
     20PROJECT_NAME           =  "PJMEDIA and PJMEDIA-CODEC" 
    2121 
    2222# The PROJECT_NUMBER tag can be used to enter a project or revision number.  
     
    108108# brief descriptions will be completely suppressed. 
    109109 
    110 REPEAT_BRIEF           = YES 
     110REPEAT_BRIEF           = NO 
    111111 
    112112# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then  
     
    134134# the path. It is allowed to use relative paths in the argument list. 
    135135 
    136 STRIP_FROM_PATH        = "c:\project\pjproject" 
     136STRIP_FROM_PATH        = "/c/project/pjproject/pjmedia" 
    137137 
    138138# The INTERNAL_DOCS tag determines if documentation  
     
    155155# doesn't support long names like on DOS, Mac, or CD-ROM. 
    156156 
    157 SHORT_NAMES            = YES 
     157SHORT_NAMES            = NO 
    158158 
    159159# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen  
     
    167167# which an include is specified. Set to NO to disable this. 
    168168 
    169 VERBATIM_HEADERS       = YES 
     169VERBATIM_HEADERS       = NO 
    170170 
    171171# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen  
     
    346346# with spaces. 
    347347 
    348 INPUT                  =  include/pjmedia 
     348INPUT                  =  include 
    349349 
    350350# If the value of the INPUT tag contains directories, you can use the  
     
    404404# the \image command). 
    405405 
    406 IMAGE_PATH             =  
     406IMAGE_PATH             = docs 
    407407 
    408408# The INPUT_FILTER tag can be used to specify a program that doxygen should  
     
    495495# doxygen will generate files with .html extension. 
    496496 
    497 HTML_FILE_EXTENSION    = .html 
     497HTML_FILE_EXTENSION    = .htm 
    498498 
    499499# The HTML_HEADER tag can be used to specify a personal HTML header for  
     
    569569# that doxygen will group on one line in the generated HTML documentation. 
    570570 
    571 ENUM_VALUES_PER_LINE   = 4 
     571ENUM_VALUES_PER_LINE   = 1 
    572572 
    573573# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be 
     
    843843 
    844844PREDEFINED             = PJ_DECL(x)=x PJ_DEF(x)=x PJ_IDECL(x)=x \ 
    845                          PJ_IDEF(x)=x PJ_INLINE(x)=x 
     845                         PJ_IDEF(x)=x PJ_INLINE(x)=x \ 
     846                         PJ_BEGIN_DECL= PJ_END_DECL= 
    846847 
    847848# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then  
  • pjproject/trunk/pjmedia/docs/footer.html

    r190 r518  
    1 </TD></TR> 
    2 </TABLE> 
    3  
    4 </td> 
    5 </tr> 
    6 </table> 
    7  
     1        <!--#include virtual="/footer.html" --> 
    82</BODY> 
    93</HTML> 
  • pjproject/trunk/pjmedia/docs/header.html

    r190 r518  
    11<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
    22<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> 
    3 <title>PJMEDIA Documentation</title> 
    4 <link href="doxygen.css" rel="stylesheet" type="text/css"> 
     3<title>PJMEDIA - Open Source media stack with RTP, RTCP, SDP, conference bridge, PLC, VAD, etc.</title> 
     4<link href="/style/style.css" rel="stylesheet" type="text/css"> 
    55</head><body> 
     6        <!--#include virtual="/header.html" --> 
    67 
    7 <TABLE id="MainTable" cellSpacing="0" cellPadding="0" width="100%" border="0"> 
    8 <!-- First Row, PJPROJECT logo. --> 
    9 <TR> 
    10     <TD> 
    11         <TABLE id="LogoTable" cellSpacing="0" cellPadding="0" width="100%" border="0"> 
    12             <TR> 
    13                 <TD><a href="/" target="_top"><IMG src="/images/pjlogo.jpg" border="0"></a></TD> 
    14                 <TD>&nbsp;</TD> 
    15                 <TD>&nbsp;</TD> 
    16             </TR> 
    17         </TABLE> 
    18     </TD> 
    19 </TR> 
    20 <!-- Second Row, a HR. --> 
    21 <TR> 
    22     <td colspan="3"><hr noshade size="1"> 
    23     </td> 
    24 </TR> 
    25 <!-- Third row, main contents. --> 
    26 <TR> 
    27     <TD> 
    28  
    29 <!-- Main doxygen content --> 
    30 <TABLE border="0"> 
    31   <TR><TD width="800" align="left"> 
    32  
  • pjproject/trunk/pjmedia/include/pjmedia-codec/gsm.h

    r176 r518  
    2020#define __PJMEDIA_CODEC_GSM_H__ 
    2121 
     22/** 
     23 * @file pjmedia-codec/gsm.h 
     24 * @brief GSM 06.10 codec. 
     25 */ 
     26 
    2227#include <pjmedia-codec/types.h> 
    2328 
     29/** 
     30 * @defgroup PJMED_GSM GSM 06.10 
     31 * @ingroup PJMEDIA_CODEC 
     32 * @brief Implementation of GSM FR based on GSM 06.10 library 
     33 * @{ 
     34 * This section describes functions to register and register GSM codec 
     35 * factory to the codec manager. After the codec factory has been registered, 
     36 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
     37 */ 
    2438 
    2539PJ_BEGIN_DECL 
     
    4963 
    5064 
     65/** 
     66 * @} 
     67 */ 
     68 
    5169#endif  /* __PJMEDIA_CODEC_GSM_H__ */ 
    5270 
  • pjproject/trunk/pjmedia/include/pjmedia-codec/l16.h

    r411 r518  
    2222#include <pjmedia-codec/types.h> 
    2323 
     24 
     25/** 
     26 * @defgroup PJMED_L16 L16 Family 
     27 * @ingroup PJMEDIA_CODEC 
     28 * @brief 16bit linear codecs (useful for debugging) 
     29 * @{ 
     30 * This section describes functions to register and register L16 codec 
     31 * factory to the codec manager. After the codec factory has been registered, 
     32 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
     33 * 
     34 * Note that the L16 codec factory registers several (about fourteen!)  
     35 * L16 codec types to codec manager (different combinations of clock 
     36 * rate and number of channels). 
     37 */ 
    2438 
    2539PJ_BEGIN_DECL 
  • pjproject/trunk/pjmedia/include/pjmedia-codec/speex.h

    r278 r518  
    2020#define __PJMEDIA_CODEC_SPEEX_H__ 
    2121 
     22/** 
     23 * @file speex.h 
     24 * @brief Speex codec header. 
     25 */ 
     26 
    2227#include <pjmedia-codec/types.h> 
    2328 
     29/** 
     30 * @defgroup PJMED_SPEEX Speex 
     31 * @ingroup PJMEDIA_CODEC 
     32 * @brief Implementation of Speex codecs (narrow/wide/ultrawide-band). 
     33 * @{ 
     34 * This section describes functions to register and register speex codec 
     35 * factory to the codec manager. After the codec factory has been registered, 
     36 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
     37 * 
     38 * By default, the speex codec factory registers three Speex codecs: 
     39 * "speex/8000" narrowband codec, "speex/16000" wideband codec, and  
     40 * "speex/32000" ultra-wideband codec. This behavior can be changed by 
     41 * specifying #pjmedia_speex_options flags during initialization. 
     42 */ 
    2443 
    2544PJ_BEGIN_DECL 
     
    6079 * 
    6180 * @param endpt         The pjmedia endpoint. 
    62  * @param options       Bitmask of pjmedia_speex_options (default=0). 
    63  * @param quality       Specify encoding quality, or use -1 for default  
    64  *                      (default=8). 
    65  * @param complexity    Specify encoding complexity , or use -1 for default  
    66  *                      (default=8). 
    6781 * 
    6882 * @return              PJ_SUCCESS on success. 
     
    8397PJ_END_DECL 
    8498 
     99/** 
     100 * @} 
     101 */ 
    85102 
    86103#endif  /* __PJMEDIA_CODEC_SPEEX_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia.h

    r452 r518  
    4444#include <pjmedia/silencedet.h> 
    4545#include <pjmedia/session.h> 
     46#include <pjmedia/transport.h> 
    4647#include <pjmedia/transport_udp.h> 
    4748#include <pjmedia/sound.h> 
  • pjproject/trunk/pjmedia/include/pjmedia/clock.h

    r404 r518  
    2727 
    2828 
     29/** 
     30 * @addtogroup PJMEDIA_CLOCK Clock Generator 
     31 * @ingroup PJMEDIA_PORT_CLOCK 
     32 * @brief Interface for generating clock. 
     33 * @{ 
     34 *  
     35 * The clock generator provides the application with media timing, 
     36 * and it is used by the @ref PJMEDIA_MASTER_PORT for its sound clock. 
     37 * 
     38 * The clock generator may be configured to run <b>asynchronously</b>  
     39 * (the default behavior) or <b>synchronously</b>. When it is run  
     40 * asynchronously, it will call the application's callback every time 
     41 * the clock <b>tick</b> expires. When it is run synchronously,  
     42 * application must continuously polls the clock generator to synchronize 
     43 * the timing. 
     44 */ 
     45 
    2946PJ_BEGIN_DECL 
    3047 
     
    3653 
    3754 
     55/** 
     56 * Options when creating the clock. 
     57 */ 
    3858enum pjmedia_clock_options 
    3959{ 
     60    /** 
     61     * Prevents the clock from running asynchronously. In this case, 
     62     * application must poll the clock continuously by calling 
     63     * #pjmedia_clock_wait() in order to synchronize timing. 
     64     */ 
    4065    PJMEDIA_CLOCK_NO_ASYNC  = 1, 
    4166}; 
     67 
    4268 
    4369/** 
     
    138164PJ_END_DECL 
    139165 
     166/** 
     167 * @} 
     168 */ 
    140169 
    141170 
  • pjproject/trunk/pjmedia/include/pjmedia/codec.h

    r497 r518  
    3333 
    3434/** 
    35  * @defgroup PJMED_CODEC Codec framework. 
     35 * @defgroup PJMEDIA_CODEC Codec Framework 
    3636 * @ingroup PJMEDIA 
     37 * @brief Media codec framework and management 
    3738 * @{ 
    3839 * 
     40 * @section codec_mgmt_sec Codec Management 
     41 * @subsection codec_fact_sec Codec Manager 
     42 * 
    3943 * The codec manager is used to manage all codec capabilities in the endpoint. 
    40  * Library implementors can extend PJMEDIA codec capabilities by creating  
    41  * a codec factory for a new codec, and register the codec factory to 
    42  * codec manager so that the codec can be used by the rest of application. 
    43  * 
    4444 * When used with media endpoint (pjmedia_endpt), application can retrieve 
    4545 * the codec manager instance by calling #pjmedia_endpt_get_codec_mgr(). 
     46 * 
     47 * @subsection reg_new_codec Registering New Codec 
     48 * 
     49 * New codec types can be registered to PJMEDIA (or to be precise, to the  
     50 * codec manager) during run-time.  
     51 * To do this, application needs to initialize an instance of 
     52 * codec factory (#pjmedia_codec_factory) and registers this codec factory 
     53 * by calling #pjmedia_codec_mgr_register_factory(). 
     54 * 
     55 * For codecs implemented/supported by PJMEDIA, this process is normally 
     56 * concealed in an easy to use function such as #pjmedia_codec_g711_init(). 
     57 * 
     58 * @subsection codec_factory Codec Factory 
     59 * 
     60 * A codec factory (#pjmedia_codec_factory) is registered to codec manager,  
     61 * and it is used to create and release codec instance. 
     62 * 
     63 * The most important member of the codec factory is the "virtual" function 
     64 * table #pjmedia_codec_factory_op, where it contains, among other thing,  
     65 * pointer to functions to allocate and deallocate codec instance. 
     66 * 
     67 * @subsection codec_inst Codec Instance 
     68 * 
     69 * Application allocates codec instance by calling #pjmedia_codec_mgr_alloc_codec(). 
     70 * One codec instance (#pjmedia_codec) can be used for simultaneous encoding 
     71 * and decoding. 
     72 * 
     73 * The most important member of the codec instance is the "virtual" function 
     74 * table #pjmedia_codec_op, where it holds pointer to functions to 
     75 * encode/decode media frames. 
     76 * 
     77 * @subsection codec_ident Codec Identification 
     78 * 
     79 * A particular codec type in PJMEDIA can be uniquely identified by two 
     80 * keys: by #pjmedia_codec_info, or by #pjmedia_codec_id string. A fully 
     81 * qualified codec ID string consists of codec name, sampling rate, and 
     82 * number of channels. However, application may use only first parts of 
     83 * the tokens as long as it will make to codec ID unique. For example, "gsm" 
     84 * is a fully qualified codec name, since it will always have 8000 clock 
     85 * rate and 1 channel. Other examples of fully qualified codec ID strings 
     86 * are "pcma", "speex/8000", "speex/16000", and "L16/16000/1". A codec 
     87 * id "speex" (without clock rate) is not fully qualified, since it will 
     88 * match the narrowband, wideband, and ultrawideband Speex codec. 
     89 * 
     90 * The two keys can be converted to one another, with 
     91 * #pjmedia_codec_info_to_id() and #pjmedia_codec_mgr_find_codecs_by_id() 
     92 * functions. 
     93 * 
     94 * Codec ID string is not case sensitive. 
     95 * 
     96 * 
     97 * @section using_codec Using the Codec Framework 
     98 * @subsection init_alloc_codec Allocating Codec 
     99 * 
     100 * Application needs to allocate one codec instance for encoding and decoding 
     101 * media frames. One codec instance can be used to perform both encoding 
     102 * and decoding. 
     103 * 
     104 * Application allocates codec by calling #pjmedia_codec_mgr_alloc_codec(). 
     105 * This function takes #pjmedia_codec_info argument, which is used to locate 
     106 * the particular codec factory to be used to allocate the codec. 
     107 * 
     108 * Application can build #pjmedia_codec_info structure manually for 
     109 * the specific codec, or alternatively it may get the #pjmedia_codec_info 
     110 * from the codec ID string, by using #pjmedia_codec_mgr_find_codecs_by_id() 
     111 * function. 
     112 * 
     113 * The following snippet shows an example to allocate a codec: 
     114 * 
     115 \code 
     116    pj_str_t codec_id; 
     117    pjmedia_codec_info *codec_info; 
     118    unsigned count = 1; 
     119    pjmedia_codec *codec; 
     120 
     121    codec_id = pj_str("pcma"); 
     122 
     123    // Find codec info for the specified coded ID (i.e. "pcma"). 
     124    status = pjmedia_codec_mgr_find_codecs_by_id( codec_mgr, &codec_id, 
     125                                                  &count, &codec_info, NULL); 
     126 
     127    // Allocate the codec. 
     128    status = pjmedia_codec_mgr_alloc_codec( codec_mgr, codec_info, &codec ); 
     129 
     130 \endcode 
     131 * 
     132 * 
     133 * @subsection opening_codec Initializing Codec 
     134 * 
     135 * Once codec is allocated, application needs to initialize the codec 
     136 * by calling <b><tt>open</tt></b> member of the codec. This function 
     137 * takes #pjmedia_codec_param as the argument, which contains the 
     138 * settings for the codec. 
     139 * 
     140 * Application shoud use #pjmedia_codec_mgr_get_default_param() function 
     141 * to initiaize #pjmedia_codec_param. The <tt>setting</tt> part of 
     142 * #pjmedia_codec_param then can be tuned to suit the application's 
     143 * requirements. 
     144 * 
     145 * The following snippet shows an example to initialize codec: 
     146 * 
     147 \code 
     148    pjmedia_codec_param param; 
     149 
     150    // Retrieve default codec param for the specified codec. 
     151    pjmedia_codec_mgr_get_default_param(codec_mgr, codec_info 
     152                                        &param); 
     153 
     154    // Application may change the "settings" part of codec param, 
     155    // for example, to disable VAD 
     156    param.setting.vad = 0; 
     157 
     158    // Open the codec using the specified settings. 
     159    codec->op->open( codec, &param ); 
     160 
     161 \endcode 
     162 * 
     163 * 
     164 * @subsection enc_dec_codec Encoding and Decoding Media Frames 
     165 * 
     166 * Application encodes and decodes media frames by calling 
     167 * <tt>encode</tt> and <tt>decode</tt> member of the codec's "virtual" 
     168 * function table (#pjmedia_codec_op). 
     169 * 
     170 * @subsection plc_codec Concealing Lost Frames 
     171 * 
     172 * All codecs has Packet Lost Concealment (PLC) feature, and application 
     173 * can activate the PLC to conceal lost frames by calling <tt>recover</tt> 
     174 * member of the codec's "virtual" function table (#pjmedia_codec_op). 
     175 * 
     176 * If the codec's algorithm supports PLC, the <tt>recover</tt> function 
     177 * will use the codec's PLC. Otherwise for codecs that don't have 
     178 * intrinsic PLC, PJMEDIA will suply the PLC implementation from the 
     179 * @ref PJMED_PLC implementation. 
     180 * 
     181 * @subsection close_codec Closing and Releasing the Codec 
     182 * 
     183 * The codec must be closed by calling <tt>close</tt> member of the codec's 
     184 * operation. Then it must be released by calling  
     185 * #pjmedia_codec_mgr_dealloc_codec(). 
    46186 */ 
    47187 
     
    50190 * Standard RTP static payload types, as defined by RFC 3551.  
    51191 * The header file <pjmedia-codec/types.h> also declares dynamic payload 
    52  * types that are supported by pjmedia-codec library. 
     192 * type numbers that are used by PJMEDIA when advertising the capability 
     193 * for example in SDP message. 
    53194 */ 
    54195enum pjmedia_rtp_pt 
     
    89230 * codec specification.  
    90231 */ 
    91 struct pjmedia_codec_info 
     232typedef struct pjmedia_codec_info 
    92233{ 
    93234    pjmedia_type    type;           /**< Media type.                    */ 
     
    96237    unsigned        clock_rate;     /**< Sampling rate.                 */ 
    97238    unsigned        channel_cnt;    /**< Channel count.                 */ 
    98 }; 
    99  
    100  
    101 /** 
    102  * @see pjmedia_codec_info 
    103  */ 
    104 typedef struct pjmedia_codec_info pjmedia_codec_info; 
     239} pjmedia_codec_info; 
    105240 
    106241 
     
    109244 * the capability of codec factories. 
    110245 */ 
    111 struct pjmedia_codec_param 
     246typedef struct pjmedia_codec_param 
    112247{ 
    113248    /** 
     
    143278        unsigned    reserved:1;     /**< Reserved, must be zero.        */ 
    144279    } setting; 
    145 }; 
    146  
    147 /** 
    148  * @see pjmedia_codec_param 
    149  */ 
    150 typedef struct pjmedia_codec_param pjmedia_codec_param; 
    151  
    152  
    153 /** 
    154  * @see pjmedia_codec 
     280} pjmedia_codec_param; 
     281 
     282 
     283 
     284/* 
     285 * Forward declaration for pjmedia_codec. 
    155286 */ 
    156287typedef struct pjmedia_codec pjmedia_codec; 
     
    161292 * all of these functions. 
    162293 */ 
    163 struct pjmedia_codec_op 
     294typedef struct pjmedia_codec_op 
    164295{ 
    165296    /**  
     
    259390 
    260391    /** 
    261      * Instruct the codec to recover a missing frame. Not all codec has 
    262      * this capability, so this function may be NULL. 
     392     * Instruct the codec to recover a missing frame. 
    263393     * 
    264394     * @param codec     The codec instance. 
    265395     * @param out_size  The length of buffer in the output frame. 
    266      * @param output    The output frame. 
     396     * @param output    The output frame where generated signal 
     397     *                  will be placed. 
    267398     * 
    268399     * @return          PJ_SUCCESS on success; 
     
    271402                           unsigned out_size, 
    272403                           struct pjmedia_frame *output); 
    273 }; 
    274  
    275  
    276 /** 
    277  * Codec operation. 
    278  */ 
    279 typedef struct pjmedia_codec_op pjmedia_codec_op; 
    280  
    281  
    282 /** 
    283  * @see pjmedia_codec_factory 
     404} pjmedia_codec_op; 
     405 
     406 
     407 
     408/* 
     409 * Forward declaration for pjmedia_codec_factory. 
    284410 */ 
    285411typedef struct pjmedia_codec_factory pjmedia_codec_factory; 
     
    310436 * factories. 
    311437 */ 
    312 struct pjmedia_codec_factory_op 
     438typedef struct pjmedia_codec_factory_op 
    313439{ 
    314440    /**  
     
    381507                                 pjmedia_codec *codec ); 
    382508 
    383 }; 
    384  
    385  
    386 /** 
    387  * @see pjmedia_codec_factory_op 
    388  */ 
    389 typedef struct pjmedia_codec_factory_op pjmedia_codec_factory_op; 
     509} pjmedia_codec_factory_op; 
     510 
    390511 
    391512 
     
    419540 * #pjmedia_codec_mgr_set_codec_priority(). 
    420541 */ 
    421 enum pjmedia_codec_priority 
     542typedef enum pjmedia_codec_priority 
    422543{ 
    423544    /** 
     
    456577     */ 
    457578    PJMEDIA_CODEC_PRIO_DISABLED = 0, 
    458 }; 
    459  
    460  
    461 /** 
    462  * @see pjmedia_codec_priority 
    463  */ 
    464 typedef enum pjmedia_codec_priority pjmedia_codec_priority; 
    465  
    466  
    467 /** Fully qualified codec name  (e.g. "pcmu/8000/1") */ 
     579 
     580} pjmedia_codec_priority; 
     581 
     582 
     583/**  
     584 * Codec identification (e.g. "pcmu/8000/1"). 
     585 * See @ref codec_ident for more info. 
     586 */ 
    468587typedef char pjmedia_codec_id[32]; 
    469588 
     
    487606 * by media endpoint to instantiate the codec manager. 
    488607 */ 
    489 struct pjmedia_codec_mgr 
     608typedef struct pjmedia_codec_mgr 
    490609{ 
    491610    /** List of codec factories registered to codec manager. */ 
     
    497616    /** Array of codec descriptor. */ 
    498617    struct pjmedia_codec_desc   codec_desc[PJMEDIA_CODEC_MGR_MAX_CODECS]; 
    499 }; 
    500  
    501  
    502 /** 
    503  * @see pjmedia_codec_mgr 
    504  */ 
    505 typedef struct pjmedia_codec_mgr pjmedia_codec_mgr; 
     618 
     619} pjmedia_codec_mgr; 
    506620 
    507621 
  • pjproject/trunk/pjmedia/include/pjmedia/conference.h

    r513 r518  
    2727#include <pjmedia/port.h> 
    2828 
     29/** 
     30 * @defgroup PJMEDIA_CONF Conference Bridge 
     31 * @ingroup PJMEDIA_PORT 
     32 * @brief The implementation of conference bridge 
     33 * @{ 
     34 */ 
    2935 
    3036PJ_BEGIN_DECL 
     
    237243 * @param sink_slot     Sink slot. 
    238244 * 
    239  * @reutrn              PJ_SUCCESS on success. 
     245 * @return              PJ_SUCCESS on success. 
    240246 */ 
    241247PJ_DECL(pj_status_t) pjmedia_conf_disconnect_port( pjmedia_conf *conf, 
     
    374380 
    375381 
     382/** 
     383 * @} 
     384 */ 
     385 
     386 
    376387#endif  /* __PJMEDIA_CONF_H__ */ 
    377388 
  • pjproject/trunk/pjmedia/include/pjmedia/config.h

    r445 r518  
    2020#define __PJMEDIA_CONFIG_H__ 
    2121 
     22/** 
     23 * @file pjmedia/config.h Compile time config 
     24 * @brief Contains some compile time constants. 
     25 */ 
    2226#include <pj/config.h> 
     27 
     28/** 
     29 * @defgroup PJMEDIA_BASE Base Types and Configurations 
     30 * @ingroup PJMEDIA 
     31 */ 
     32 
     33/** 
     34 * @defgroup PJMEDIA_CONFIG Compile time configuration 
     35 * @ingroup PJMEDIA_BASE 
     36 * @brief Some compile time configuration settings. 
     37 * @{ 
     38 */ 
    2339 
    2440/* 
    2541 * Types of sound stream backends. 
    2642 */ 
     43 
     44/** Constant for NULL sound backend. */ 
    2745#define PJMEDIA_SOUND_NULL_SOUND            0 
     46 
     47/** Constant for PortAudio sound backend. */ 
    2848#define PJMEDIA_SOUND_PORTAUDIO_SOUND       1 
     49 
     50/** Constant for Win32 DirectSound sound backend. */ 
    2951#define PJMEDIA_SOUND_WIN32_DIRECT_SOUND    2 
    3052 
     
    133155 
    134156 
     157/** 
     158 * @} 
     159 */ 
     160 
    135161 
    136162#endif  /* __PJMEDIA_CONFIG_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia/doxygen.h

    r188 r518  
    3535 
    3636/** 
    37  * @mainpage Welcome to PJMEDIA! 
    38  * 
    39  * @section intro_sec What is PJMEDIA 
    40  * 
    41  * PJMEDIA open source (GPL) library contains objects that implements multimedia  
    42  * capabilities. It can be used with signaling libraries such as PJSIP to create  
    43  * a complete multimedia communication endpoint. 
    44  * 
    45  * 
     37 * @mainpage PJMEDIA and PJMEDIA-CODEC 
     38 * 
     39 * \n 
     40 * @section intro_sec PJMEDIA 
     41 * 
     42 * PJMEDIA is a rather complete media stack, distributed under Open Source/GPL 
     43 * terms, and featuring small footprint and good extensibility and portability. 
     44 * 
     45 * Please click the <A HREF="modules.htm"><b>Modules</b></A> link on top 
     46 * of this page to get the complete features currently present in PJMEDIA. 
     47 * 
     48 * Also please read the documentation about @ref PJMEDIA_PORT_CONCEPT, 
     49 * which is a major concept that is used for implementing many objects in  
     50 * the library. 
     51 * 
     52 * \n 
     53 * @section pjmedia_codec_sec PJMEDIA-CODEC 
     54 * 
     55 * PJMEDIA-CODEC is a static library containing various codec implementations, 
     56 * wrapped into PJMEDIA codec framework. The static library is designed as 
     57 * such so that only codecs that are explicitly initialized are linked with  
     58 * the application, therefore keeping the application size in control. 
     59 * 
     60 * Please see @ref pjmedia_codec_page on how to use the codec in  
     61 * PJMEDIA-CODEC. 
     62 * 
     63 * \n 
     64 * @section pjmedia_lic Copying and Acknowledgements 
     65 * 
     66 * Please see @ref lic_stuffs page for the details. 
     67 */ 
     68 
     69 
     70/** 
     71 * @page pjmedia_codec_page Using PJMEDIA-CODEC 
     72 * 
     73 * Before application can use a codec, it needs to initialize and register 
     74 * the codec to the codec manager. This is accomplished with using 
     75 * constructs like the following: 
     76 * 
     77 \code 
     78    #include <pjmedia.h> 
     79    #include <pjmedia-codec.h> 
     80 
     81    init_codecs( pjmedia_endpt *med_ept ) 
     82    { 
     83        // Register G.711 codecs 
     84        pjmedia_codec_g711_init(med_ept); 
     85 
     86        // Register GSM codec. 
     87        pjmedia_codec_gsm_init(med_ept); 
     88 
     89        // Register Speex codecs. 
     90        // With the default flag, this will register three codecs: 
     91        // speex/8000, speex/16000, and speex/32000 
     92        pjmedia_codec_speex_init(med_ept, 0, 0, 0); 
     93    } 
     94 \endcode 
     95 * 
     96 * After the codec is registered, application may create the encoder/decoder 
     97 * instance, by using the API as documented in @ref PJMEDIA_CODEC. 
     98 */ 
     99 
     100 
     101 
     102/** 
     103 * @page lic_stuffs Copying and Acknowledgements 
     104 * @section lic_stuff Copying and Acknowledgements 
    46105 * @subsection pjmedia_about_subsec About PJMEDIA 
    47106 * 
    48  * <pre> 
    49  * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> 
    50  * 
    51  * This program is free software; you can redistribute it and/or modify 
    52  * it under the terms of the GNU General Public License as published by 
    53  * the Free Software Foundation; either version 2 of the License, or 
    54  * (at your option) any later version. 
    55  * 
    56  * This program is distributed in the hope that it will be useful, 
    57  * but WITHOUT ANY WARRANTY; without even the implied warranty of 
    58  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
    59  * GNU General Public License for more details. 
    60  * 
    61  * You should have received a copy of the GNU General Public License 
    62  * along with this program; if not, write to the Free Software 
    63  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  
    64  * </pre> 
    65  * 
    66  * 
    67  * @subsection portaudio_subsec About PortAudio 
    68  * 
    69  * PortAudio is an excellent sound device library that is chosen as sound  
    70  * device abstraction in PJMEDIA. It has the following characteristics that 
    71  * makes it perfect for our use: 
    72  * 
    73  *  - It is portable and complete 
    74  *\n 
    75  *    It supports multiple back-ends on Windows, Windows CE (WinCE)/PocketPC,  
    76  *    Linux, Unix, and MacOS. More platforms may be supported. 
    77  *  - It is callback based 
    78  *\n 
    79  *    The callback based for supplying/retrieving frames from the audio 
    80  *    device is perfect for our use. 
    81  *  - No nonsense, C based library. 
    82  *  - Actively maintained. 
     107 * PJMEDIA is distributed under GPL terms (other licensing schemes may be  
     108 * arranged): 
     109 \verbatim 
     110    Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> 
     111 
     112    This program is free software; you can redistribute it and/or modify 
     113    it under the terms of the GNU General Public License as published by 
     114    the Free Software Foundation; either version 2 of the License, or 
     115    (at your option) any later version. 
     116 
     117    This program is distributed in the hope that it will be useful, 
     118    but WITHOUT ANY WARRANTY; without even the implied warranty of 
     119    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
     120    GNU General Public License for more details. 
     121 
     122    You should have received a copy of the GNU General Public License 
     123    along with this program; if not, write to the Free Software 
     124    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  
     125 \endverbatim 
     126 * 
     127 * 
     128 * @section other_acks Acknowlegments 
     129 * @subsection portaudio_subsec PortAudio 
     130 * 
     131 * PortAudio is supported as one of the sound device backend, and 
     132 * is used by default on Linux/Unix and MacOS X target. 
    83133 *  
    84  * Please visit http://www.portaudio.com for more info. 
     134 * Please visit <A HREF="http://www.portaudio.com">http://www.portaudio.com</A> 
     135 * for more info. 
    85136 * 
    86137 * PortAudio is distributed with the following condition. 
    87  * <pre> 
    88  * Based on the Open Source API proposed by Ross Bencina 
    89  * Copyright (c) 1999-2000 Phil Burk 
    90  * 
    91  * Permission is hereby granted, free of charge, to any person obtaining 
    92  * a copy of this software and associated documentation files 
    93  * (the "Software"), to deal in the Software without restriction, 
    94  * including without limitation the rights to use, copy, modify, merge, 
    95  * publish, distribute, sublicense, and/or sell copies of the Software, 
    96  * and to permit persons to whom the Software is furnished to do so, 
    97  * subject to the following conditions: 
    98  * 
    99  * The above copyright notice and this permission notice shall be 
    100  * included in all copies or substantial portions of the Software. 
    101  * </pre> 
     138 \verbatim 
     139    Based on the Open Source API proposed by Ross Bencina 
     140    Copyright (c) 1999-2000 Phil Burk 
     141 
     142    Permission is hereby granted, free of charge, to any person obtaining 
     143    a copy of this software and associated documentation files 
     144    (the "Software"), to deal in the Software without restriction, 
     145    including without limitation the rights to use, copy, modify, merge, 
     146    publish, distribute, sublicense, and/or sell copies of the Software, 
     147    and to permit persons to whom the Software is furnished to do so, 
     148    subject to the following conditions: 
     149 
     150    The above copyright notice and this permission notice shall be 
     151    included in all copies or substantial portions of the Software. 
     152 \endverbatim 
     153 * 
     154 * 
     155 * @subsection resample_ack Resample 
     156 * 
     157 * PJMEDIA uses <tt>resample-1.8.tar.gz</tt> from  
     158 * <A HREF="http://www-ccrma.stanford.edu/~jos/resample/"> 
     159 * Digital Audio Resampling Home Page</A>. This library is distibuted 
     160 * on LGPL terms. 
     161 * 
     162 * Some excerpts from the original source codes: 
     163 \verbatim 
     164    HISTORY 
     165 
     166    The first version of this software was written by Julius O. Smith III 
     167    <jos@ccrma.stanford.edu> at CCRMA <http://www-ccrma.stanford.edu> in 
     168    1981.  It was called SRCONV and was written in SAIL for PDP-10 
     169    compatible machines.  The algorithm was first published in 
     170 
     171    Smith, Julius O. and Phil Gossett. ``A Flexible Sampling-Rate 
     172    Conversion Method,'' Proceedings (2): 19.4.1-19.4.4, IEEE Conference 
     173    on Acoustics, Speech, and Signal Processing, San Diego, March 1984. 
     174 
     175    An expanded tutorial based on this paper is available at the Digital 
     176    Audio Resampling Home Page given above. 
     177 
     178    Circa 1988, the SRCONV program was translated from SAIL to C by 
     179    Christopher Lee Fraley working with Roger Dannenberg at CMU. 
     180 
     181    Since then, the C version has been maintained by jos. 
     182 
     183    Sndlib support was added 6/99 by John Gibson <jgg9c@virginia.edu>. 
     184 
     185    The resample program is free software distributed in accordance 
     186    with the Lesser GNU Public License (LGPL).  There is NO warranty; not 
     187    even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
     188 \endverbatim 
     189 * 
     190 * @subsection jb_ack Adaptive Jitter Buffer 
     191 * 
     192 * The PJMEDIA jitter buffer is based on implementation kindly donated 
     193 * by <A HREF="http://www.switchlab.com">Switchlab, Ltd.</A>, and is 
     194 * distributed under PJMEDIA licensing terms. 
     195 * 
     196 * 
     197 * @subsection silence_det_ack Adaptive Silence Detector 
     198 * 
     199 * The adaptive silence detector was based on silence detector  
     200 * implementation in <A HREF="http://www.openh323.org">Open H323</A>  
     201 * project. I couldn't find the source code anymore, but generally 
     202 * Open H323 files are distributed under MPL terms and has the 
     203 * following excerpts: 
     204 \verbatim 
     205    Open H323 Library 
     206 
     207    Copyright (c) 1998-2000 Equivalence Pty. Ltd. 
     208 
     209    The contents of this file are subject to the Mozilla Public License 
     210    Version 1.0 (the "License"); you may not use this file except in 
     211    compliance with the License. You may obtain a copy of the License at 
     212    http://www.mozilla.org/MPL/ 
     213 
     214    Software distributed under the License is distributed on an "AS IS" 
     215    basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 
     216    the License for the specific language governing rights and limitations 
     217    under the License. 
     218 
     219    The Original Code is Open H323 Library. 
     220 
     221    The Initial Developer of the Original Code is Equivalence Pty. Ltd. 
     222 
     223    Portions of this code were written with the assisance of funding from 
     224    Vovida Networks, Inc. http://www.vovida.com. 
     225 \endverbatim 
     226 
     227 * @subsection gsm_ack GSM Codec 
     228 * 
     229 * PJMEDIA uses GSM  
     230 * <A HREF="http://kbs.cs.tu-berlin.de/~jutta/toast.html">GSM 06.10</A> 
     231 * version 1.0 at patchlevel 12. It has the following Copyright notice: 
     232 * 
     233 \verbatim 
     234    Copyright 1992, 1993, 1994 by Jutta Degener and Carsten Bormann, 
     235    Technische Universitaet Berlin 
     236 
     237    Any use of this software is permitted provided that this notice is not 
     238    removed and that neither the authors nor the Technische Universitaet Berlin 
     239    are deemed to have made any representations as to the suitability of this 
     240    software for any purpose nor are held responsible for any defects of 
     241    this software.  THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE. 
     242 
     243    As a matter of courtesy, the authors request to be informed about uses 
     244    this software has found, about bugs in this software, and about any 
     245    improvements that may be of general interest. 
     246 
     247    Berlin, 28.11.1994 
     248    Jutta Degener 
     249    Carsten Bormann 
     250 \endverbatim 
     251 * 
     252 * 
     253 * @subsection speex_codec_ack Speex Codec 
     254 * 
     255 * PJMEDIA uses Speex codec uses version 1.1.12 from <A HREF="http://www.speex.org"> 
     256 * www.speex.org</A>. The Speex library comes with the following Copying 
     257 * notice: 
     258 \verbatim 
     259    Copyright 2002-2005  
     260            Xiph.org Foundation 
     261            Jean-Marc Valin 
     262            David Rowe 
     263            EpicGames 
     264            Analog Devices 
     265 
     266    Redistribution and use in source and binary forms, with or without 
     267    modification, are permitted provided that the following conditions 
     268    are met: 
     269 
     270    - Redistributions of source code must retain the above copyright 
     271    notice, this list of conditions and the following disclaimer. 
     272 
     273    - Redistributions in binary form must reproduce the above copyright 
     274    notice, this list of conditions and the following disclaimer in the 
     275    documentation and/or other materials provided with the distribution. 
     276 
     277    - Neither the name of the Xiph.org Foundation nor the names of its 
     278    contributors may be used to endorse or promote products derived from 
     279    this software without specific prior written permission. 
     280 
     281    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
     282    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
     283    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
     284    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR 
     285    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
     286    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
     287    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
     288    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
     289    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
     290    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
     291    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
     292 \endverbatim 
     293 * 
     294 * 
     295 * @subsection g711_codec_ack G.711 Codec 
     296 * 
     297 * The G.711 codec algorithm came from Sun Microsystems, Inc, and it's 
     298 * got the following excerpts: 
     299 * 
     300 \verbatim 
     301    This source code is a product of Sun Microsystems, Inc. and is provided 
     302    for unrestricted use.  Users may copy or modify this source code without 
     303    charge. 
     304 
     305    SUN SOURCE CODE IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING 
     306    THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR 
     307    PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. 
     308 
     309    Sun source code is provided with no support and without any obligation on 
     310    the part of Sun Microsystems, Inc. to assist in its use, correction, 
     311    modification or enhancement. 
     312 
     313    SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE 
     314    INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS SOFTWARE 
     315    OR ANY PART THEREOF. 
     316 
     317    In no event will Sun Microsystems, Inc. be liable for any lost revenue 
     318    or profits or other special, indirect and consequential damages, even if 
     319    Sun has been advised of the possibility of such damages. 
     320 
     321    Sun Microsystems, Inc. 
     322    2550 Garcia Avenue 
     323    Mountain View, California  94043 
     324 \endverbatim 
     325 * 
    102326 */ 
    103327 
  • pjproject/trunk/pjmedia/include/pjmedia/endpoint.h

    r411 r518  
    2626 */ 
    2727/** 
    28  * @defgroup PJMED_ENDPT Multimedia Endpoint 
     28 * @defgroup PJMED_ENDPT The Endpoint 
    2929 * @ingroup PJMEDIA 
    3030 * @{ 
  • pjproject/trunk/pjmedia/include/pjmedia/errno.h

    r438 r518  
    2020#define __PJMEDIA_ERRNO_H__ 
    2121 
     22/** 
     23 * @file errno.h Error Codes 
     24 * @brief PJMEDIA specific error codes. 
     25 */ 
     26 
    2227#include <pjmedia/types.h> 
    2328#include <pj/errno.h> 
    2429 
     30/** 
     31 * @defgroup PJMEDIA_ERRNO Error Codes 
     32 * @ingroup PJMEDIA_BASE 
     33 * @brief PJMEDIA specific error codes. 
     34 * @{ 
     35 */ 
     36 
     37 
    2538PJ_BEGIN_DECL 
    2639 
     
    3245 
    3346 
    34 /* 
     47/** 
    3548 * Mapping from PortAudio error codes to pjmedia error space. 
    3649 */ 
    3750#define PJMEDIA_PORTAUDIO_ERRNO_START (PJMEDIA_ERRNO_START+PJ_ERRNO_SPACE_SIZE-1000) 
    3851 
    39 /* 
     52/** 
    4053 * Convert PortAudio error code to PJMEDIA error code. 
    4154 */ 
     
    390403 
    391404/************************************************************ 
    392  * JITTER BUFFER ERRORS 
    393  ***********************************************************/ 
    394  
    395  
    396 /************************************************************ 
    397405 * PORT ERRORS 
    398406 ***********************************************************/ 
     
    487495PJ_END_DECL 
    488496 
     497/** 
     498 * @} 
     499 */ 
     500 
     501 
    489502#endif  /* __PJMEDIA_ERRNO_H__ */ 
    490503 
  • pjproject/trunk/pjmedia/include/pjmedia/g711.h

    r278 r518  
    2020#define __PJMEDIA_G711_H__ 
    2121 
     22/** 
     23 * @file g711.h 
     24 * @brief G711 Codec 
     25 */ 
     26 
    2227#include <pjmedia-codec/types.h> 
    2328 
     29/** 
     30 * @defgroup PJMED_G711 G711 
     31 * @ingroup PJMEDIA_CODEC 
     32 * @brief Standard G.711/PCMA and PCMU codec. 
     33 * @{ 
     34 * This section describes functions to register and register G.711 codec 
     35 * factory to the codec manager. After the codec factory has been registered, 
     36 * application can use @ref PJMEDIA_CODEC API to manipulate the codec. 
     37 */ 
    2438 
    2539PJ_BEGIN_DECL 
     
    4862PJ_END_DECL 
    4963 
     64/** 
     65 * @} 
     66 */ 
    5067 
    5168#endif  /* __PJMEDIA_G711_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia/jbuf.h

    r442 r518  
    3232/** 
    3333 * @defgroup PJMED_JBUF Adaptive jitter buffer 
    34  * @ingroup PJMEDIA 
     34 * @ingroup PJMEDIA_FRAME_OP 
    3535 * @{ 
    36  * 
     36 * This section describes PJMEDIA's implementation of de-jitter buffer. 
     37 * The de-jitter buffer may be set to operate in adaptive mode or fixed 
     38 * delay mode. 
     39 * 
     40 * The jitter buffer is also able to report the status of the current 
     41 * frame (#pjmedia_jb_frame_type). This status is used for examply by 
     42 * @ref PJMED_STRM to invoke the codec's @ref PJMED_PLC algorithm. 
    3743 */ 
    3844 
  • pjproject/trunk/pjmedia/include/pjmedia/master_port.h

    r498 r518  
    2727#include <pjmedia/port.h> 
    2828 
     29/** 
     30 * @defgroup PJMEDIA_MASTER_PORT Master Port 
     31 * @ingroup PJMEDIA_PORT_CLOCK 
     32 * @brief Provides media clock for media ports. 
     33 * @{ 
     34 * A master port has two media ports connected to it, and by convention 
     35 * thay are called downstream and upstream ports. The media stream flowing to 
     36 * the downstream port is called encoding or send direction, and media stream  
     37 * flowing to the upstream port is called decoding or receive direction 
     38 * (imagine the downstream as stream to remote endpoint, and upstream as 
     39 * local media port; media flowing to remote endpoint (downstream) will need 
     40 * to be encoded before it is transmitted to remote endpoint). 
     41 * 
     42 * A master port internally has an instance of @ref PJMEDIA_CLOCK, which 
     43 * provides the essensial timing for the master port. The @ref PJMEDIA_CLOCK 
     44 * runs asynchronously, and whenever a clock <b>tick</b> expires, a callback 
     45 * will be called, and the master port performs the following tasks: 
     46 *  - it calls <b><tt>get_frame()</tt></b> from the downstream port, 
     47 *    when give the frame to the upstream port by calling <b><tt>put_frame 
     48 *    </tt></b> to the upstream port, and 
     49 *  - performs the same task, but on the reverse direction (i.e. get the stream 
     50 *    from upstream port and give it to the downstream port). 
     51 * 
     52 * Because master port enables media stream to flow automatically, it is 
     53 * said that the master port supplies @ref PJMEDIA_PORT_CLOCK to the  
     54 * media ports interconnection. 
     55 * 
     56 */ 
    2957 
    3058PJ_BEGIN_DECL 
     
    3361/** 
    3462 * Opaque declaration for master port. 
    35  * A master port has two media ports connected to it, i.e. downstream and 
    36  * upstream ports. The media stream flowing to the downstream port is called 
    37  * encoding or send direction, and media stream flowing to the upstream port 
    38  * is called decoding or receive direction. 
    39  * 
    40  * A master port has a "clock" that periodically passes the media frame from  
    41  * downstream to upstream ports, and vice versa. In each run, it retrieves  
    42  * media frame from one side with #pjmedia_port_get_frame(), and passes the  
    43  * media frame to the other side with #pjmedia_port_put_frame(). In each run, 
    44  * this process is done for twice, i.e. one for each direction. 
    4563 */ 
    4664typedef struct pjmedia_master_port pjmedia_master_port; 
     
    150168PJ_END_DECL 
    151169 
     170/** 
     171 * @} 
     172 */ 
     173 
    152174 
    153175#endif  /* __PJMEDIA_MASTER_PORT_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia/null_port.h

    r322 r518  
    2727 
    2828 
     29 
     30/** 
     31 * @defgroup PJMEDIA_NULL_PORT Null Port 
     32 * @ingroup PJMEDIA_PORT 
     33 * @brief Null port is the simplest type of port. 
     34 * @{ 
     35 */ 
     36 
     37 
    2938PJ_BEGIN_DECL 
    3039 
     
    3342 * Create Null port.  
    3443 * 
     44 * @param pool                  Pool to allocate memory. 
    3545 * @param sampling_rate         Sampling rate of the port. 
    3646 * @param channel_count         Number of channels. 
     
    5262PJ_END_DECL 
    5363 
     64/** 
     65 * @} 
     66 */ 
     67 
    5468 
    5569#endif  /* __PJMEDIA_NULL_PORT_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia/plc.h

    r417 r518  
    2929/** 
    3030 * @defgroup PJMED_PLC Packet Lost Concealment 
    31  * @ingroup PJMEDIA 
     31 * @ingroup PJMEDIA_FRAME_OP 
    3232 * @{ 
     33 * This section describes PJMEDIA's implementation of Packet Lost 
     34 * Concealment algorithm. This algorithm is used to implement PLC for 
     35 * codecs that do not have built-in support for one (e.g. G.711 or GSM codecs). 
    3336 * 
     37 * The PLC algorithm (either built-in or external) is embedded in 
     38 * PJMEDIA codec instance, and application can conceal lost frames 
     39 * by calling <b><tt>recover()</tt></b> member of the codec's member 
     40 * operation (#pjmedia_codec_op). 
     41 * 
     42 * See also @ref plc_codec for more info. 
    3443 */ 
    3544 
  • pjproject/trunk/pjmedia/include/pjmedia/port.h

    r411 r518  
    2828 
    2929 
     30/** 
     31  @defgroup PJMEDIA_PORT_CONCEPT Media Ports 
     32  @ingroup PJMEDIA 
     33  @brief Extensible framework for media terminations 
     34   
     35  @section media_port_intro Concepts 
     36   
     37  @subsection The Media Port 
     38  A media port (represented with pjmedia_port "class") provides a generic 
     39  and extensible framework for implementing media terminations. A media 
     40  port interface basically has the following properties: 
     41  - media port information (pjmedia_port_info) to describe the 
     42  media port properties (sampling rate, number of channels, etc.), 
     43  - pointer to function to acquire frames from the port (<tt>get_frame() 
     44  </tt> interface), which will be called by #pjmedia_port_get_frame() 
     45  public API, and 
     46  - pointer to function to store frames to the port (<tt>put_frame()</tt> 
     47  interface) which will be called by #pjmedia_port_put_frame() public 
     48  API. 
     49   
     50  Media ports are passive "objects". Applications (or other PJMEDIA  
     51  components) must actively calls #pjmedia_port_get_frame() or  
     52  #pjmedia_port_put_frame() from/to the media port in order to retrieve/ 
     53  store media frames. 
     54   
     55  Some media ports (such as @ref PJMEDIA_CONF and @ref PJMEDIA_RESAMPLE_PORT) 
     56  may be interconnected with each other, while some 
     57  others represent the ultimate source/sink termination for the media.  
     58  The  #pjmedia_port_connect() and #pjmedia_port_disconnect() are used to 
     59  connect and disconnect media ports respectively. But even when ports 
     60  are connected with each other ports, they still remain passive. 
     61 
     62 
     63  @subsection port_clock_ex1 Example: Manual Resampling 
     64 
     65  For example, suppose application wants to convert the sampling rate 
     66  of one WAV file to another. In this case, application would create and 
     67  arrange media ports connection as follows: 
     68 
     69    \image html sample-manual-resampling.jpg 
     70 
     71  Application would setup the media ports using the following pseudo- 
     72  code: 
     73 
     74  \code 
     75   
     76      pjmedia_port *player, *resample, *writer; 
     77      pj_status_t status; 
     78   
     79      // Create the file player port. 
     80      status = pjmedia_wav_player_port_create(pool,  
     81                                              "Input.WAV",          // file name 
     82                                              20,                   // ptime. 
     83                                              PJMEDIA_FILE_NO_LOOP, // flags 
     84                                              0,                    // buffer size 
     85                                              NULL,                 // user data. 
     86                                              &player ); 
     87      PJ_ASSERT_RETURN(status==PJ_SUCCESS, PJ_SUCCESS); 
     88   
     89      // Create the resample port with specifying the target sampling rate,  
     90      // and with the file port as the source. This will effectively 
     91      // connect the resample port with the player port. 
     92      status = pjmedia_resample_port_create( pool, player, 8000,  
     93                                             0, &resample); 
     94      PJ_ASSERT_RETURN(status==PJ_SUCCESS, PJ_SUCCESS); 
     95   
     96      // Create the file writer, specifying the resample port's configuration 
     97      // as the WAV parameters. 
     98      status pjmedia_wav_writer_port_create(pool,  
     99                                            "Output.WAV",  // file name. 
     100                                            resample->info.clock_rate, 
     101                                            resample->info.channel_count, 
     102                                            resample->info.samples_per_frame, 
     103                                            resample->info.bits_per_sample, 
     104                                            0,          // flags 
     105                                            0,          // buffer size 
     106                                            NULL,       // user data. 
     107                                            &writer); 
     108   
     109  \endcode 
     110 
     111   
     112  After the ports have been set up, application can perform the conversion 
     113  process by running this loop: 
     114  
     115  \code 
     116   
     117        pj_int16_t samplebuf[MAX_FRAME]; 
     118         
     119        while (1) { 
     120            pjmedia_frame frame; 
     121            pj_status_t status; 
     122   
     123            frame.buf = samplebuf; 
     124            frame.size = sizeof(samplebuf); 
     125   
     126            // Get the frame from resample port. 
     127            status = pjmedia_port_get_frame(resample, &frame); 
     128            if (status != PJ_SUCCESS || frame.type == PJMEDIA_FRAME_TYPE_NONE) { 
     129                // End-of-file, end the conversion. 
     130                break; 
     131            } 
     132   
     133            // Put the frame to write port. 
     134            status = pjmedia_port_put_frame(writer, &frame); 
     135            if (status != PJ_SUCCESS) { 
     136                // Error in writing the file. 
     137                break; 
     138            } 
     139        } 
     140   
     141  \endcode 
     142  
     143  For the sake of completeness, after the resampling process is done,  
     144  application would need to destroy the ports: 
     145   
     146  \code 
     147        // Note: by default, destroying resample port will destroy the 
     148        //       the downstream port too. 
     149        pjmedia_port_destroy(resample); 
     150        pjmedia_port_destroy(writer); 
     151  \endcode 
     152  
     153  
     154  The above steps are okay for our simple purpose of changing file's sampling 
     155  rate. But for other purposes, the process of reading and writing frames 
     156  need to be done in timely manner (for example, sending RTP packets to 
     157  remote stream). And more over, as the application's scope goes bigger, 
     158  the same pattern of manually reading/writing frames comes up more and more often, 
     159  thus perhaps it would be better if PJMEDIA provides mechanism to  
     160  automate this process. 
     161   
     162  And indeed PJMEDIA does provide such mechanism, which is described in  
     163  @ref PJMEDIA_PORT_CLOCK section. 
     164 
     165 
     166  @subsection media_port_autom Automating Media Flow 
     167 
     168  PJMEDIA provides few mechanisms to make media flows automatically 
     169  among media ports. This concept is described in @ref PJMEDIA_PORT_CLOCK  
     170  section. 
     171 
     172 */ 
     173 
     174 
     175/** 
     176 * @defgroup PJMEDIA_PORT_INTERFACE Media Port Interface 
     177 * @ingroup PJMEDIA_PORT_CONCEPT 
     178 * @brief Declares the media port interface. 
     179 */ 
     180 
     181/** 
     182 * @defgroup PJMEDIA_PORT Ports 
     183 * @ingroup PJMEDIA_PORT_CONCEPT 
     184 * @brief Contains various types of media ports/terminations. 
     185 * @{ 
     186 * This page lists all types of media ports currently implemented 
     187 * in PJMEDIA. The media port concept is explained in @ref PJMEDIA_PORT_CONCEPT. 
     188 * @} 
     189 */ 
     190 
     191/** 
     192 @defgroup PJMEDIA_PORT_CLOCK Clock/Timing 
     193 @ingroup PJMEDIA_PORT_CONCEPT 
     194 @brief Various types of classes that provide timing. 
     195 @{ 
     196 
     197 The media clock/timing extends the media port concept that is explained  
     198 in @ref PJMEDIA_PORT_CONCEPT. When clock is present in the ports  
     199 interconnection, media will flow automatically (and with correct timing too!) 
     200 from one media port to another. 
     201  
     202 There are few objects in PJMEDIA that are able to provide clock/timing 
     203 to media ports interconnection: 
     204 
     205 - @ref PJMED_SND_PORT\n 
     206   The sound device makes a good candidate as the clock source, and 
     207   PJMEDIA @ref PJMED_SND is designed so that it is able to invoke 
     208   operations according to timing driven by the sound hardware clock 
     209   (this may sound complicated, but actually it just means that 
     210   the sound device abstraction provides callbacks to be called when 
     211   it has/wants media frames).\n 
     212   See @ref PJMED_SND_PORT for more details. 
     213 
     214 - @ref PJMEDIA_MASTER_PORT\n 
     215   The master port uses @ref PJMEDIA_CLOCK as the clock source. By using 
     216   @ref PJMEDIA_MASTER_PORT, it is possible to interconnect passive 
     217   media ports and let the frames flow automatically in timely manner.\n 
     218   Please see @ref PJMEDIA_MASTER_PORT for more details. 
     219 
     220 @} 
     221 */ 
     222 
     223/** 
     224 * @addtogroup PJMEDIA_PORT_INTERFACE 
     225 * @{ 
     226 * This page contains the media port interface declarations. The media port 
     227 * concept is explained in @ref PJMEDIA_PORT_CONCEPT. 
     228 */ 
     229 
    30230PJ_BEGIN_DECL 
    31231 
     
    69269 * Port info. 
    70270 */ 
    71 struct pjmedia_port_info 
     271typedef struct pjmedia_port_info 
    72272{ 
    73273    pj_str_t        name;               /**< Port name.                     */ 
     
    83283    unsigned        samples_per_frame;  /**< No of samples per frame.       */ 
    84284    unsigned        bytes_per_frame;    /**< No of samples per frame.       */ 
    85 }; 
    86  
    87 /** 
    88  * @see pjmedia_port_info 
    89  */ 
    90 typedef struct pjmedia_port_info pjmedia_port_info; 
     285} pjmedia_port_info; 
    91286 
    92287 
     
    94289 * Types of media frame.  
    95290 */ 
    96 enum pjmedia_frame_type 
     291typedef enum pjmedia_frame_type 
    97292{ 
    98293    PJMEDIA_FRAME_TYPE_NONE,        /**< No frame.              */ 
     
    100295    PJMEDIA_FRAME_TYPE_AUDIO,       /**< Normal audio frame.    */ 
    101296 
    102 }; 
    103  
    104  
    105 /**  
    106  * @see pjmedia_frame_type 
    107  */ 
    108 typedef enum pjmedia_frame_type pjmedia_frame_type; 
     297} pjmedia_frame_type; 
    109298 
    110299 
     
    143332struct pjmedia_port 
    144333{ 
    145     pjmedia_port_info    info; 
    146     pjmedia_graph       *graph; 
    147     pjmedia_port        *upstream_port; 
    148     pjmedia_port        *downstream_port; 
    149     void                *user_data; 
    150  
    151     /** 
    152      * Called when this port is connected to an upstream port. 
    153      */ 
    154     pj_status_t (*on_upstream_connect)(pj_pool_t *pool, 
    155                                        pjmedia_port *this_port, 
    156                                        pjmedia_port *upstream); 
    157  
    158     /** 
    159      * Called when this port is connected to a downstream port. 
    160      */ 
    161     pj_status_t (*on_downstream_connect)(pj_pool_t *pool, 
    162                                          pjmedia_port *this_port, 
    163                                          pjmedia_port *upstream); 
     334    pjmedia_port_info    info;              /**< Port information.  */ 
     335    void                *user_data;         /**< User data.         */ 
    164336 
    165337    /** 
     
    184356 
    185357 
    186  
    187 /** 
    188  * Connect two ports. 
    189  */ 
    190 PJ_DECL(pj_status_t) pjmedia_port_connect( pj_pool_t *pool, 
    191                                            pjmedia_port *upstream_port, 
    192                                            pjmedia_port *downstream_port); 
    193  
    194 /** 
    195  * Disconnect ports. 
    196  */ 
    197 PJ_DECL(pj_status_t) pjmedia_port_disconnect( pjmedia_port *upstream_port, 
    198                                               pjmedia_port *downstream_port); 
    199  
    200  
    201358/** 
    202359 * Get a frame from the port (and subsequent downstream ports). 
     
    221378PJ_END_DECL 
    222379 
     380/** 
     381 * @} 
     382 */ 
    223383 
    224384#endif  /* __PJMEDIA_PORT_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia/resample.h

    r358 r518  
    2323 
    2424/** 
    25  * @file reample.h 
     25 * @file resample.h 
    2626 * @brief Sample rate converter. 
    2727 */ 
     
    2929#include <pjmedia/port.h> 
    3030 
     31/** 
     32 * @defgroup PJMEDIA_RESAMPLE Resampling Algorithm 
     33 * @ingroup PJMEDIA_FRAME_OP 
     34 * @brief Functions to alter frame's clock rate. 
     35 * @{ 
     36 * This section describes the base resampling functions. In addition to this, 
     37 * application can use the @ref PJMEDIA_RESAMPLE_PORT which provides 
     38 * media port abstraction for the base resampling algorithm. 
     39 */ 
    3140 
    3241PJ_BEGIN_DECL 
     
    99108 
    100109/** 
     110 * @} 
     111 */ 
     112 
     113/** 
     114 * @defgroup PJMEDIA_RESAMPLE_PORT Resample Port 
     115 * @ingroup PJMEDIA_PORT 
     116 * @brief Media port interface to change media stream's sampling rate. 
     117 * @{ 
     118 * This section describes media port abstractoin for @ref PJMEDIA_RESAMPLE. 
     119 */ 
     120 
     121 
     122/** 
     123 * Option flags that can be specified when creating resample port. 
     124 */ 
     125enum pjmedia_resample_port_options 
     126{ 
     127    /** 
     128     * Do not use high quality resampling algorithm, but use linear 
     129     * algorithm instead. 
     130     */ 
     131    PJMEDIA_RESAMPLE_USE_LINEAR = 1, 
     132 
     133    /** 
     134     * Use small filter workspace when high quality resampling is 
     135     * used. 
     136     */ 
     137    PJMEDIA_RESAMPLE_USE_SMALL_FILTER = 2, 
     138 
     139    /** 
     140     * Do not destroy downstream port when resample port is destroyed. 
     141     */ 
     142    PJMEDIA_RESAMPLE_DONT_DESTROY_DN = 4, 
     143}; 
     144 
     145 
     146 
     147/** 
    101148 * Create a resample port. This creates a bidirectional resample session, 
    102149 * which will resample frames when the port's get_frame() and put_frame() 
     
    104151 * 
    105152 * When the resample port's get_frame() is called, this port will get 
    106  * a frame from the downstream port and resample the frame to the upstream 
    107  * port's clock rate before returning it to the caller. 
     153 * a frame from the downstream port and resample the frame to the target 
     154 * clock rate before returning it to the caller. 
    108155 * 
    109156 * When the resample port's put_frame() is called, this port will resample 
    110  * the frame to the downstream's port clock rate before giving the frame 
     157 * the frame to the downstream port's clock rate before giving the frame 
    111158 * to the downstream port. 
    112159 * 
    113160 * @param pool                  Pool to allocate the structure and buffers. 
    114  * @param high_quality          If true, then high quality conversion will be 
    115  *                              used, at the expense of more CPU and memory, 
    116  *                              because temporary buffer needs to be created. 
    117  * @param large_filter          If true, large filter size will be used. 
    118  * @param downstream_rate       The sampling rate of the downstream port. 
    119  * @param upstream_rate         The sampling rate of the upstream port. 
    120  * @param channel_count         The number of channels. This argument is only 
    121  *                              used for the port information. It does not 
    122  *                              change the behavior of the resample port. 
    123  * @param samples_per_frame     Number of samples per frame from the downstream 
    124  *                              port. 
     161 * @param dn_port               The downstream port, which clock rate is to 
     162 *                              be converted to the target clock rate. 
     163 * @param clock_rate            Target clock rate. 
     164 * @param options               Flags from #pjmedia_resample_port_options. 
     165 *                              When this flag is zero, the default behavior 
     166 *                              is to use high quality resampling with 
     167 *                              large filter, and to destroy downstream port 
     168 *                              when resample port is destroyed. 
    125169 * @param p_port                Pointer to receive the resample port instance. 
    126170 * 
     
    128172 */ 
    129173PJ_DECL(pj_status_t) pjmedia_resample_port_create( pj_pool_t *pool, 
    130                                                    pj_bool_t high_quality, 
    131                                                    pj_bool_t large_filter, 
    132                                                    unsigned downstream_rate, 
    133                                                    unsigned upstream_rate, 
    134                                                    unsigned channel_count, 
    135                                                    unsigned samples_per_frame, 
     174                                                   pjmedia_port *dn_port, 
     175                                                   unsigned clock_rate, 
     176                                                   unsigned options, 
    136177                                                   pjmedia_port **p_port ); 
    137178 
     
    139180PJ_END_DECL 
    140181 
     182/** 
     183 * @} 
     184 */ 
     185 
     186 
    141187#endif  /* __PJMEDIA_RESAMPLE_H__ */ 
    142188 
  • pjproject/trunk/pjmedia/include/pjmedia/rtcp.h

    r473 r518  
    3333 
    3434/** 
    35  * @defgroup PJMED_RTCP RTCP Management 
    36  * @ingroup PJMEDIA 
     35 * @defgroup PJMED_RTCP RTCP Session 
     36 * @ingroup PJMEDIA_TRANSPORT 
    3737 * @{ 
    3838 */ 
     
    219219 
    220220 
     221/** 
     222 * The types for keeping the average jitter value. Ideally a floating point 
     223 * number should be used, but this is not always available/desired. 
     224 */ 
    221225#if defined(PJ_HAS_FLOATING_POINT) && PJ_HAS_FLOATING_POINT!=0 
    222226  typedef double PJMEDIA_AVG_JITTER_TYPE; 
  • pjproject/trunk/pjmedia/include/pjmedia/rtp.h

    r408 r518  
    3232 
    3333/** 
    34  * @defgroup PJMED_RTP RTP Packet and RTP Session Management 
    35  * @ingroup PJMEDIA 
     34 * @defgroup PJMED_RTP RTP Session 
     35 * @ingroup PJMEDIA_TRANSPORT 
    3636 * @{ 
    3737 * 
     
    4040 * on any transports (sockets), to promote even more use. 
    4141 * 
    42  * An RTCP implementation is available, in separate module. 
     42 * An RTCP implementation is available, in separate module. Please see  
     43 * @ref PJMED_RTCP. 
    4344 * 
    4445 * The functions that are provided by this module: 
     
    130131struct pjmedia_rtp_dtmf_event 
    131132{ 
    132     pj_uint8_t  event; 
    133     pj_uint8_t  e_vol; 
    134     pj_uint16_t duration; 
     133    pj_uint8_t  event;      /**< Event type ID.     */ 
     134    pj_uint8_t  e_vol;      /**< Event volume.      */ 
     135    pj_uint16_t duration;   /**< Event duration.    */ 
    135136}; 
    136137 
  • pjproject/trunk/pjmedia/include/pjmedia/sdp.h

    r419 r518  
    2828 
    2929/** 
    30  * @defgroup PJ_SDP SDP Parsing and Data Structure 
    31  * @ingroup PJMEDIA 
     30 * @defgroup PJMEDIA_SDP SDP Parsing and Data Structure 
     31 * @ingroup PJMEDIA_SESSION 
    3232 * @{ 
    3333 * 
  • pjproject/trunk/pjmedia/include/pjmedia/sdp_neg.h

    r501 r518  
    2626 */ 
    2727/** 
    28  * @defgroup PJ_SDP_NEG SDP Negotiator. 
    29  * @ingroup PJMEDIA 
     28 * @defgroup PJMEDIA_SDP_NEG SDP Negotiator 
     29 * @ingroup PJMEDIA_SESSION 
    3030 * @{ 
    3131 * 
  • pjproject/trunk/pjmedia/include/pjmedia/session.h

    r452 r518  
    3333 
    3434/** 
     35 * @defgroup PJMEDIA_SESSION Sessions 
     36 * @ingroup PJMEDIA 
     37 */ 
     38 
     39/** 
    3540 * @defgroup PJMED_SES Media session 
    36  * @ingroup PJMEDIA 
     41 * @ingroup PJMEDIA_SESSION 
    3742 * @{ 
    3843 * 
     
    9196 * @param local         Local SDP session descriptor. 
    9297 * @param remote        Remote SDP session descriptor. 
    93  * @param stream_idx    Media stream index in the session descriptor. 
    9498 * 
    9599 * @return              PJ_SUCCESS if stream info is successfully initialized. 
     
    104108 
    105109 
    106 /* 
     110/** 
    107111 * This function will initialize the stream info based on information 
    108112 * in both SDP session descriptors for the specified stream index.  
     
    264268 * @param session       The media session. 
    265269 * @param index         Stream index. 
    266  * @param sta           Stream statistic. 
     270 * @param stat          Stream statistic. 
    267271 * 
    268272 * @return              PJ_SUCCESS on success. 
  • pjproject/trunk/pjmedia/include/pjmedia/silencedet.h

    r457 r518  
    2626 */ 
    2727#include <pjmedia/types.h> 
     28 
     29 
     30/** 
     31 * @defgroup PJMEDIA_SILENCEDET Adaptive Silence Detection 
     32 * @ingroup PJMEDIA_FRAME_OP 
     33 * @brief Adaptive Silence Detector 
     34 * @{ 
     35 */ 
     36 
    2837 
    2938PJ_BEGIN_DECL 
     
    180189 
    181190 
     191/** 
     192 * @} 
     193 */ 
     194 
     195 
    182196#endif  /* __PJMEDIA_SILENCE_DET_H__ */ 
    183197 
  • pjproject/trunk/pjmedia/include/pjmedia/sound.h

    r352 r518  
    3131 
    3232/** 
    33  * @defgroup PJMED_SND Sound device abstraction. 
    34  * @ingroup PJMEDIA 
     33 * @defgroup PJMED_SND Sound Hardware Abstraction 
     34 * @ingroup PJMED_SND_PORT 
     35 * @brief PJMEDIA abstraction for sound device hardware 
    3536 * @{ 
     37 * 
     38 * This section describes lower level abstraction for sound device 
     39 * hardware. Application normally uses the higher layer @ref 
     40 * PJMED_SND_PORT abstraction since it works seamlessly with  
     41 * @ref PJMEDIA_PORT_CONCEPT. 
     42 * 
     43 * The sound hardware abstraction basically runs <b>asychronously</b>, 
     44 * and application must register callbacks to be called to receive/ 
     45 * supply audio frames from/to the sound hardware. 
     46 * 
     47 * A full duplex sound stream (created with #pjmedia_snd_open())  
     48 * requires application to supply two callbacks: 
     49 *  - <b><tt>rec_cb</tt></b> callback to be called when it has finished 
     50 *    capturing one media frame, and  
     51 *  - <b><tt>play_cb</tt></b> callback to be called when it needs media  
     52 *    frame to be played to the sound playback hardware. 
     53 * 
     54 * Half duplex sound stream (created with #pjmedia_snd_open_rec() or 
     55 * #pjmedia_snd_open_player()) will only need one of the callback to 
     56 * be specified. 
     57 * 
     58 * After sound stream is created, application need to call 
     59 * #pjmedia_snd_stream_start() to start capturing/playing back media 
     60 * frames from/to the sound device. 
    3661 */ 
    3762 
     
    114139 * Create sound stream for both capturing audio and audio playback,  from the  
    115140 * same device. This is the recommended way to create simultaneous recorder  
    116  * and player streams, because it should work on backends that does not allow 
     141 * and player streams (instead of creating separate capture and playback 
     142 * streams), because it works on backends that does not allow 
    117143 * a device to be opened more than once. 
    118144 * 
  • pjproject/trunk/pjmedia/include/pjmedia/sound_port.h

    r352 r518  
    3030 
    3131/** 
    32  * @defgroup PJMED_SND_PORT Media Port Connection Abstraction to Sound Device 
    33  * @ingroup PJMEDIA 
    34  * @{ 
     32 * @defgroup PJMED_SND_PORT Sound Device Port 
     33 * @ingroup PJMEDIA_PORT_CLOCK 
     34 * @brief Media Port Connection Abstraction to the Sound Device 
     35 @{ 
     36 
     37 As explained in @ref PJMED_SND, the sound hardware abstraction provides 
     38 some callbacks for its user: 
     39 - it calls <b><tt>rec_cb</tt></b> callback when it has finished capturing 
     40   one media frame, and  
     41 - it calls <b><tt>play_cb</tt></b> when it needs media frame to be  
     42   played to the sound playback hardware. 
     43 
     44 The @ref PJMED_SND_PORT (the object being explained here) add a 
     45 thin wrapper to the hardware abstraction: 
     46 - it will call downstream port's <tt>put_frame()</tt> 
     47   when <b><tt>rec_cb()</tt></b> is called (i.e. when the sound hardware  
     48   has finished capturing frame), and  
     49 - it will call downstream port's <tt>get_frame()</tt> when  
     50   <b><tt>play_cb()</tt></b> is called (i.e. every time the  
     51   sound hardware needs more frames to be played to the playback hardware). 
     52 
     53 This simple abstraction enables media to flow automatically (and 
     54 in timely manner) from the downstream media port to the sound device. 
     55 In other words, the sound device port supplies media clock to 
     56 the ports. The media clock concept is explained in @ref PJMEDIA_PORT_CLOCK 
     57 section. 
     58 
     59 Application registers downstream port to the sound device port by 
     60 calling #pjmedia_snd_port_connect(); 
     61  
    3562 */ 
    3663 
     
    169196 * 
    170197 * @param snd_port          The sound device port. 
     198 * @param port              The media port to be connected. 
    171199 * 
    172200 * @return                  PJ_SUCCESS on success, or the appropriate error 
  • pjproject/trunk/pjmedia/include/pjmedia/stream.h

    r479 r518  
    3131#include <pjmedia/port.h> 
    3232#include <pjmedia/rtcp.h> 
     33#include <pjmedia/transport.h> 
    3334#include <pj/sock.h> 
    3435 
     
    3738 
    3839/** 
    39  * @defgroup PJMED_STRM Media Stream 
    40  * @ingroup PJMEDIA 
     40 * @defgroup PJMED_STRM Streams 
     41 * @ingroup PJMEDIA_PORT 
     42 * @brief Media port for communicating with remote peer via the network. 
    4143 * @{ 
    4244 * 
    4345 * A media stream is a bidirectional multimedia communication between two 
    44  * endpoints. It corresponds to a media description (m= line) in SDP. 
     46 * endpoints. It corresponds to a media description (m= line) in SDP 
     47 * session descriptor. 
    4548 * 
    4649 * A media stream consists of two unidirectional channels: 
     
    4851 *  - decoding channel, which receives unidirectional media from remote. 
    4952 * 
    50  * Application normally does not need to create the stream directly; it  
    51  * creates media session instead. The media session will create the media 
    52  * streams as necessary, according to the media descriptors that present 
    53  * in local and remote SDP. 
     53 * A media stream exports media port interface (see @ref PJMEDIA_PORT_CONCEPT) 
     54 * and application normally uses this interface to interconnect the stream 
     55 * to other PJMEDIA components. 
     56 * 
     57 * A media stream internally manages the following objects: 
     58 *  - an instance of media codec (see @ref PJMEDIA_CODEC), 
     59 *  - an @ref PJMED_JBUF, 
     60 *  - two instances of RTP sessions (#pjmedia_rtp_session, one for each 
     61 *    direction), 
     62 *  - one instance of RTCP session (#pjmedia_rtcp_session), 
     63 *  - and a reference to media transport to send and receive packets 
     64 *    to/from the network (see @ref PJMEDIA_TRANSPORT_H). 
     65 * 
     66 * Streams are created by calling #pjmedia_stream_create(), specifying 
     67 * #pjmedia_stream_info structure in the parameter. Application can construct 
     68 * the #pjmedia_stream_info structure manually, or use  
     69 * #pjmedia_stream_info_from_sdp() or #pjmedia_session_info_from_sdp()  
     70 * functions to construct the #pjmedia_stream_info from local and remote  
     71 * SDP session descriptors. 
     72 * 
     73 * Application can also use @ref PJMEDIA_SESSION to indirectly create the 
     74 * streams. 
    5475 */ 
    5576 
     
    93114 
    94115 
    95 /** 
    96  * Opaque declaration for media stream. 
    97  */ 
    98 typedef struct pjmedia_stream pjmedia_stream; 
    99  
    100  
    101 /** 
    102  * @see pjmedia_transport_op. 
    103  */ 
    104 typedef struct pjmedia_transport pjmedia_transport; 
    105  
    106  
    107 /** 
    108  * This structure describes the operations for the stream transport. 
    109  */ 
    110 struct pjmedia_transport_op 
    111 { 
    112     /** 
    113      * This function is called by the stream when the transport is about 
    114      * to be used by the stream for the first time, and it tells the transport 
    115      * about remote RTP address to send the packet and some callbacks to be  
    116      * called for incoming packets. 
    117      */ 
    118     pj_status_t (*attach)(pjmedia_transport *tp, 
    119                           pjmedia_stream *strm, 
    120                           const pj_sockaddr_t *rem_addr, 
    121                           unsigned addr_len, 
    122                           void (*rtp_cb)(pjmedia_stream*, 
    123                                          const void*, 
    124                                          pj_ssize_t), 
    125                           void (*rtcp_cb)(pjmedia_stream*, 
    126                                           const void*, 
    127                                           pj_ssize_t)); 
    128  
    129     /** 
    130      * This function is called by the stream when the stream is no longer 
    131      * need the transport (normally when the stream is about to be closed). 
    132      */ 
    133     void (*detach)(pjmedia_transport *tp, 
    134                    pjmedia_stream *strm); 
    135  
    136     /** 
    137      * This function is called by the stream to send RTP packet using the  
    138      * transport. 
    139      */ 
    140     pj_status_t (*send_rtp)(pjmedia_transport *tp, 
    141                             const void *pkt, 
    142                             pj_size_t size); 
    143  
    144     /** 
    145      * This function is called by the stream to send RTCP packet using the 
    146      * transport. 
    147      */ 
    148     pj_status_t (*send_rtcp)(pjmedia_transport *tp, 
    149                              const void *pkt, 
    150                              pj_size_t size); 
    151  
    152     /** 
    153      * This function can be called to destroy this transport. 
    154      */ 
    155     pj_status_t (*destroy)(pjmedia_transport *tp); 
    156 }; 
    157  
    158  
    159 /** 
    160  * @see pjmedia_transport_op. 
    161  */ 
    162 typedef struct pjmedia_transport_op pjmedia_transport_op; 
    163  
    164  
    165 /** 
    166  * This structure declares stream transport. A stream transport is called 
    167  * by the stream to transmit a packet, and will notify stream when 
    168  * incoming packet is arrived. 
    169  */ 
    170 struct pjmedia_transport 
    171 { 
    172     char                  name[PJ_MAX_OBJ_NAME]; 
    173  
    174     pjmedia_transport_op *op; 
    175 }; 
    176  
    177  
    178116 
    179117/** 
  • pjproject/trunk/pjmedia/include/pjmedia/transport_udp.h

    r483 r518  
    2222 
    2323/** 
    24  * @file stream_transport_udp.h 
     24 * @file transport_udp.h 
    2525 * @brief Stream transport with UDP. 
    2626 */ 
    2727 
    2828#include <pjmedia/stream.h> 
     29 
     30 
     31/** 
     32 * @defgroup PJMEDIA_TRANSPORT_UDP UDP Socket Transport 
     33 * @ingroup PJMEDIA_TRANSPORT_H 
     34 * @brief Implementation of media transport with UDP sockets. 
     35 * @{ 
     36 */ 
     37 
     38PJ_BEGIN_DECL 
    2939 
    3040 
     
    93103 
    94104 
     105PJ_END_DECL 
     106 
     107 
     108/** 
     109 * @} 
     110 */ 
     111 
    95112 
    96113#endif  /* __PJMEDIA_TRANSPORT_UDP_H__ */ 
  • pjproject/trunk/pjmedia/include/pjmedia/types.h

    r513 r518  
    2020#define __PJMEDIA_TYPES_H__ 
    2121 
     22/** 
     23 * @file pjmedia/types.h Basic Types 
     24 * @brief Basic PJMEDIA types. 
     25 */ 
     26 
    2227#include <pjmedia/config.h> 
    2328#include <pj/sock.h>        /* pjmedia_sock_info        */ 
     
    2530 
    2631 
     32/** 
     33 * @defgroup PJMEDIA_FRAME_OP Frame Operations 
     34 * @ingroup PJMEDIA 
     35 */ 
     36 
     37/** 
     38 * @defgroup PJMEDIA_MISC Misc 
     39 * @ingroup PJMEDIA 
     40 */ 
     41 
     42/** 
     43 * @defgroup PJMEDIA_TYPES Basic Types 
     44 * @ingroup PJMEDIA_BASE 
     45 * @brief Basic PJMEDIA types and operations. 
     46 * @{ 
     47 */ 
     48 
    2749/**  
    2850 * Top most media type.  
    2951 */ 
    30 enum pjmedia_type 
     52typedef enum pjmedia_type 
    3153{ 
    3254    /** No type. */ 
     
    4466    PJMEDIA_TYPE_UNKNOWN = 3, 
    4567 
    46 }; 
    47  
    48 /** 
    49  * @see pjmedia_type 
    50  */ 
    51 typedef enum pjmedia_type pjmedia_type; 
     68} pjmedia_type; 
    5269 
    5370 
     
    5673 * Media direction.  
    5774 */ 
    58 enum pjmedia_dir 
     75typedef enum pjmedia_dir 
    5976{ 
    6077    /** None */ 
     
    7087    PJMEDIA_DIR_ENCODING_DECODING = 3, 
    7188 
    72 }; 
    73  
    74 /** 
    75  * @see pjmedia_dir 
    76  */ 
    77 typedef enum pjmedia_dir pjmedia_dir; 
     89} pjmedia_dir; 
     90 
    7891 
    7992 
     
    96109 
    97110 
     111/** 
     112 * Create 32bit port signature from ASCII characters. 
     113 */ 
     114#define PJMEDIA_PORT_SIGNATURE(a,b,c,d)     \ 
     115            (a<<24 | b<<16 | c<<8 | d) 
     116 
     117 
    98118/**  
    99119 * Opague declaration of media endpoint.  
     
    102122 
    103123 
    104 /**  
    105  * Media socket info.  
     124/* 
     125 * Forward declaration for stream (needed by transport). 
     126 */ 
     127typedef struct pjmedia_stream pjmedia_stream; 
     128 
     129 
     130/**  
     131 * Media socket info is used to describe the underlying sockets 
     132 * to be used as media transport. 
    106133 */ 
    107134typedef struct pjmedia_sock_info 
    108135{ 
    109  
    110     pj_sock_t       rtp_sock;       /**< Socket for RTP.                    */ 
    111     pj_sockaddr_in  rtp_addr_name;  /**< Local RTP address to be advertised.*/ 
    112     pj_sock_t       rtcp_sock;      /**< Socket for RTCP.                   */ 
    113     pj_sockaddr_in  rtcp_addr_name; /**< Local RTCP addr to be advertised.  */ 
     136    /** The RTP socket handle */ 
     137    pj_sock_t       rtp_sock; 
     138 
     139    /** Address to be advertised as the local address for the RTP 
     140     *  socket, which does not need to be equal as the bound 
     141     *  address (for example, this address can be the address resolved 
     142     *  with STUN). 
     143     */ 
     144    pj_sockaddr_in  rtp_addr_name; 
     145 
     146    /** The RTCP socket handle. */ 
     147    pj_sock_t       rtcp_sock; 
     148 
     149    /** Address to be advertised as the local address for the RTCP 
     150     *  socket, which does not need to be equal as the bound 
     151     *  address (for example, this address can be the address resolved 
     152     *  with STUN). 
     153     */ 
     154    pj_sockaddr_in  rtcp_addr_name; 
    114155 
    115156} pjmedia_sock_info; 
     
    163204 
    164205 
     206/** 
     207 * @} 
     208 */ 
     209 
     210 
    165211#endif  /* __PJMEDIA_TYPES_H__ */ 
    166212 
  • pjproject/trunk/pjmedia/include/pjmedia/wav_port.h

    r480 r518  
    3232 
    3333/** 
     34 * @defgroup PJMEDIA_FILE_PLAY File Player 
     35 * @ingroup PJMEDIA_PORT 
     36 * @brief WAV File Player 
     37 * @{ 
     38 */ 
     39 
     40/** 
     41 * WAV file player options. 
     42 */ 
     43enum pjmedia_file_player_option 
     44{ 
     45    /** 
     46     * Tell the file player to return NULL frame when the whole 
     47     * file has been played. 
     48     */ 
     49    PJMEDIA_FILE_NO_LOOP = 1, 
     50}; 
     51 
     52 
     53/** 
    3454 * Create a media port to play streams from a WAV file. 
    3555 * 
     
    4060 *                      duration (20ms) will be used. 
    4161 * @param flags         Port creation flags. 
    42  * @param buf_size      Buffer size to be allocated. If the value is zero or 
     62 * @param buff_size     Buffer size to be allocated. If the value is zero or 
    4363 *                      negative, the port will use default buffer size (which 
    4464 *                      is about 4KB). 
     
    7090 
    7191/** 
     92 * @} 
     93 */ 
     94 
     95 
     96/** 
     97 * @defgroup PJMEDIA_FILE_REC File Writer (Recorder) 
     98 * @ingroup PJMEDIA_PORT 
     99 * @brief WAV File Writer (Recorder) 
     100 * @{ 
     101 */ 
     102 
     103 
     104 
     105/** 
    72106 * Create a media port to record streams to a WAV file. Note that the port 
    73107 * must be closed properly (with #pjmedia_port_destroy()) so that the WAV 
    74108 * header can be filled with correct values (such as the file length). 
    75109 * 
    76  * @param pool          Pool to create memory buffers for this port. 
    77  * @param filename      File name. 
    78  * @param clock_rate    The sampling rate. 
    79  * @param channel_count Number of channels. 
     110 * @param pool              Pool to create memory buffers for this port. 
     111 * @param filename          File name. 
     112 * @param clock_rate        The sampling rate. 
     113 * @param channel_count     Number of channels. 
    80114 * @param samples_per_frame Number of samples per frame. 
    81  * @param bits_per_sampe Number of bits per sample (eg 16). 
    82  * @param flags         Port creation flags (must be 0 at present). 
    83  * @param buf_size      Buffer size to be allocated. If the value is zero or 
     115 * @param bits_per_sample  Number of bits per sample (eg 16). 
     116 * @param flags             Port creation flags (must be 0 at present). 
     117 * @param buff_size     Buffer size to be allocated. If the value is zero or 
    84118 *                      negative, the port will use default buffer size (which 
    85119 *                      is about 4KB). 
     
    102136 
    103137 
     138/** 
     139 * @} 
     140 */ 
     141 
    104142 
    105143PJ_END_DECL 
  • pjproject/trunk/pjmedia/include/pjmedia/wave.h

    r358 r518  
    2828 
    2929 
     30/** 
     31 * @defgroup PJMEDIA_WAVE WAVE Header 
     32 * @ingroup PJMEDIA_MISC 
     33 * @{ 
     34 * 
     35 * Supports for simple/canonical Microsoft RIFF WAVE format. 
     36 */ 
     37 
     38 
    3039PJ_BEGIN_DECL 
    3140 
     41/** 
     42 * Standard RIFF tag to identify RIFF file format in the WAVE header. 
     43 */ 
    3244#define PJMEDIA_RIFF_TAG        ('F'<<24|'F'<<16|'I'<<8|'R') 
     45 
     46/** 
     47 * Standard WAVE tag to identify WAVE header. 
     48 */ 
    3349#define PJMEDIA_WAVE_TAG        ('E'<<24|'V'<<16|'A'<<8|'W') 
     50 
     51/** 
     52 * Standard FMT tag to identify format chunks. 
     53 */ 
    3454#define PJMEDIA_FMT_TAG         (' '<<24|'t'<<16|'m'<<8|'f') 
     55 
     56/** 
     57 * Standard DATA tag to identify data chunks. 
     58 */ 
    3559#define PJMEDIA_DATA_TAG        ('a'<<24|'t'<<16|'a'<<8|'d') 
    3660 
     
    4266struct pjmedia_wave_hdr 
    4367{ 
     68    /** This structure describes RIFF WAVE file header */ 
    4469    struct { 
    45         pj_uint32_t riff; 
    46         pj_uint32_t file_len; 
    47         pj_uint32_t wave; 
     70        pj_uint32_t riff;               /**< "RIFF" ASCII tag.          */ 
     71        pj_uint32_t file_len;           /**< File length minus 8 bytes  */ 
     72        pj_uint32_t wave;               /**< "WAVE" ASCII tag.          */ 
    4873    } riff_hdr; 
    4974 
     75    /** This structure describes format chunks/header  */ 
    5076    struct { 
    51         pj_uint32_t fmt; 
    52         pj_uint32_t len; 
    53         pj_uint16_t fmt_tag; 
    54         pj_uint16_t nchan; 
    55         pj_uint32_t sample_rate; 
    56         pj_uint32_t bytes_per_sec; 
    57         pj_uint16_t block_align; 
    58         pj_uint16_t bits_per_sample; 
     77        pj_uint32_t fmt;                /**< "fmt " ASCII tag.          */ 
     78        pj_uint32_t len;                /**< 16 for PCM.                */ 
     79        pj_uint16_t fmt_tag;            /**< 1 for PCM                  */ 
     80        pj_uint16_t nchan;              /**< Number of channels.        */ 
     81        pj_uint32_t sample_rate;        /**< Sampling rate.             */ 
     82        pj_uint32_t bytes_per_sec;      /**< Average bytes per second.  */ 
     83        pj_uint16_t block_align;        /**< nchannels * bits / 8       */ 
     84        pj_uint16_t bits_per_sample;    /**< Bits per sample.           */ 
    5985    } fmt_hdr; 
    6086 
     87    /** The data header preceeds the actual data in the file. */ 
    6188    struct { 
    62         pj_uint32_t data; 
    63         pj_uint32_t len; 
     89        pj_uint32_t data;               /**< "data" ASCII tag.          */ 
     90        pj_uint32_t len;                /**< Data length.               */ 
    6491    } data_hdr; 
    6592}; 
     
    99126PJ_END_DECL 
    100127 
     128/** 
     129 * @} 
     130 */ 
     131 
     132 
    101133#endif  /* __PJMEDIA_WAVE_H__ */ 
    102134 
  • pjproject/trunk/pjmedia/src/pjmedia/port.c

    r358 r518  
    2626 
    2727/** 
    28  * Connect two ports. 
    29  */ 
    30 PJ_DEF(pj_status_t) pjmedia_port_connect( pj_pool_t *pool, 
    31                                           pjmedia_port *upstream_port, 
    32                                           pjmedia_port *downstream_port) 
    33 { 
    34     pj_status_t status; 
    35  
    36     PJ_ASSERT_RETURN(pool && upstream_port && downstream_port, PJ_EINVAL); 
    37  
    38 #if 0 
    39     /* They both MUST have the same media type. */ 
    40     PJ_ASSERT_RETURN(upstream_port->info.type == 
    41                      downstream_port->info.type, PJMEDIA_ENCTYPE); 
    42  
    43     /* They both MUST have the same clock rate. */ 
    44     PJ_ASSERT_RETURN(upstream_port->info.sample_rate == 
    45                      downstream_port->info.sample_rate, PJMEDIA_ENCCLOCKRATE); 
    46  
    47     /* They both MUST have the same samples per frame */ 
    48     PJ_ASSERT_RETURN(upstream_port->info.samples_per_frame == 
    49                      downstream_port->info.samples_per_frame,  
    50                      PJMEDIA_ENCSAMPLESPFRAME); 
    51  
    52     /* They both MUST have the same bits per sample */ 
    53     PJ_ASSERT_RETURN(upstream_port->info.bits_per_sample == 
    54                      downstream_port->info.bits_per_sample,  
    55                      PJMEDIA_ENCBITS); 
    56  
    57     /* They both MUST have the same bytes per frame */ 
    58     PJ_ASSERT_RETURN(upstream_port->info.bytes_per_frame == 
    59                      downstream_port->info.bytes_per_frame,  
    60                      PJMEDIA_ENCBYTES); 
    61 #endif 
    62  
    63     /* Create mutual attachment. */ 
    64     if (upstream_port->on_downstream_connect) { 
    65         status = upstream_port->on_downstream_connect( pool, upstream_port, 
    66                                                        downstream_port ); 
    67         if (status != PJ_SUCCESS) 
    68             return status; 
    69     } 
    70  
    71     if (downstream_port->on_upstream_connect) { 
    72         status = downstream_port->on_upstream_connect( pool, downstream_port, 
    73                                                        upstream_port ); 
    74         if (status != PJ_SUCCESS) 
    75             return status; 
    76     } 
    77  
    78     /* Save the attachment. */ 
    79     upstream_port->downstream_port = downstream_port; 
    80     downstream_port->upstream_port = upstream_port; 
    81      
    82     /* Done. */ 
    83     return PJ_SUCCESS; 
    84 } 
    85  
    86  
    87 /** 
    88  * Disconnect ports. 
    89  */ 
    90 PJ_DEF(pj_status_t) pjmedia_port_disconnect( pjmedia_port *upstream_port, 
    91                                              pjmedia_port *downstream_port) 
    92 { 
    93     PJ_ASSERT_RETURN(upstream_port && downstream_port, PJ_EINVAL); 
    94  
    95     if (upstream_port->downstream_port == downstream_port) 
    96         upstream_port->downstream_port = NULL; 
    97  
    98     if (downstream_port->upstream_port == upstream_port) 
    99         downstream_port->upstream_port = NULL; 
    100  
    101     return PJ_SUCCESS; 
    102 } 
    103  
    104  
    105 /** 
    10628 * Get a frame from the port (and subsequent downstream ports). 
    10729 */ 
     
    11436    return port->get_frame(port, frame); 
    11537} 
    116  
    11738 
    11839 
     
    14061    PJ_ASSERT_RETURN(port, PJ_EINVAL); 
    14162 
    142     /* Recursively call this function again to destroy downstream 
    143      * port first. 
    144      */ 
    145     if (port->downstream_port) { 
    146         status = pjmedia_port_destroy(port->downstream_port); 
    147         if (status != PJ_SUCCESS) 
    148             return status; 
    149         pjmedia_port_disconnect(port, port->downstream_port); 
    150     } 
    151  
    15263    if (port->on_destroy) 
    15364        status = port->on_destroy(port); 
     
    16071 
    16172 
    162  
  • pjproject/trunk/pjmedia/src/pjmedia/resample_port.c

    r411 r518  
    2929{ 
    3030    pjmedia_port         base; 
     31    pjmedia_port        *dn_port; 
     32    unsigned             options; 
    3133    pjmedia_resample    *resample_get; 
    3234    pjmedia_resample    *resample_put; 
    3335    pj_int16_t          *get_buf; 
    3436    pj_int16_t          *put_buf; 
    35     unsigned             downstream_frame_size; 
    36     unsigned             upstream_frame_size; 
    3737}; 
    3838 
     
    4343static pj_status_t resample_get_frame(pjmedia_port *this_port,  
    4444                                      pjmedia_frame *frame); 
     45static pj_status_t resample_destroy(pjmedia_port *this_port); 
    4546 
    4647 
    4748 
    4849PJ_DEF(pj_status_t) pjmedia_resample_port_create( pj_pool_t *pool, 
    49                                                   pj_bool_t high_quality, 
    50                                                   pj_bool_t large_filter, 
    51                                                   unsigned downstream_rate, 
    52                                                   unsigned upstream_rate, 
    53                                                   unsigned channel_count, 
    54                                                   unsigned samples_per_frame, 
    55                                                   pjmedia_port **p_port ) 
     50                                                  pjmedia_port *dn_port, 
     51                                                  unsigned clock_rate, 
     52                                                  unsigned opt, 
     53                                                  pjmedia_port **p_port  ) 
    5654{ 
    5755    struct resample_port *rport; 
    58     unsigned upstream_samples_per_frame; 
     56    unsigned ptime; 
    5957    pj_status_t status; 
    6058 
    61     PJ_ASSERT_RETURN(pool && p_port, PJ_EINVAL); 
    62  
    63     upstream_samples_per_frame = (unsigned)(samples_per_frame * 1.0 * 
    64                                             upstream_rate / downstream_rate); 
    65  
     59    /* Validate arguments. */ 
     60    PJ_ASSERT_RETURN(pool && dn_port && clock_rate && p_port, PJ_EINVAL); 
     61 
     62    /* Only supports 16bit samples per frame */ 
     63    PJ_ASSERT_RETURN(dn_port->info.bits_per_sample == 16, PJMEDIA_ENCBITS); 
     64 
     65    ptime = dn_port->info.samples_per_frame * 1000 /  
     66            dn_port->info.clock_rate; 
     67     
    6668    /* Create and initialize port. */ 
    6769    rport = pj_pool_zalloc(pool, sizeof(struct resample_port)); 
    6870    PJ_ASSERT_RETURN(rport != NULL, PJ_ENOMEM); 
    6971 
    70     rport->base.info.bits_per_sample = 16; 
    71     rport->base.info.bytes_per_frame = samples_per_frame * BYTES_PER_SAMPLE; 
    72     rport->base.info.channel_count = channel_count; 
     72    rport->base.info.clock_rate = clock_rate; 
     73    rport->base.info.samples_per_frame = clock_rate * ptime / 1000; 
     74    rport->base.info.bytes_per_frame = rport->base.info.samples_per_frame * 
     75                                       BYTES_PER_SAMPLE; 
     76    rport->base.info.bits_per_sample = BYTES_PER_SAMPLE * 8; 
     77    rport->base.info.channel_count = dn_port->info.channel_count; 
    7378    rport->base.info.encoding_name = pj_str("pcm"); 
    7479    rport->base.info.has_info = 1; 
     
    7681    rport->base.info.need_info = 0; 
    7782    rport->base.info.pt = 0xFF; 
    78     rport->base.info.clock_rate = upstream_rate; 
    79     rport->base.info.samples_per_frame = upstream_samples_per_frame; 
    80     rport->base.info.signature = 0; 
     83    rport->base.info.signature = PJMEDIA_PORT_SIGNATURE('R','S','M','P'); 
    8184    rport->base.info.type = PJMEDIA_TYPE_AUDIO; 
    8285 
    83     rport->downstream_frame_size = samples_per_frame; 
    84     rport->upstream_frame_size = upstream_samples_per_frame; 
     86    rport->dn_port = dn_port; 
     87    rport->options = opt; 
     88 
    8589 
    8690    /* Create buffers.  
     
    8892     * both functions may run simultaneously. 
    8993     */ 
    90     rport->get_buf = pj_pool_alloc(pool, samples_per_frame * BYTES_PER_SAMPLE); 
    91     PJ_ASSERT_RETURN(rport->get_buf, PJ_ENOMEM); 
    92  
    93     rport->put_buf = pj_pool_alloc(pool, samples_per_frame * BYTES_PER_SAMPLE); 
    94     PJ_ASSERT_RETURN(rport->put_buf, PJ_ENOMEM); 
     94    rport->get_buf = pj_pool_alloc(pool, rport->base.info.bytes_per_frame); 
     95    PJ_ASSERT_RETURN(rport->get_buf != NULL, PJ_ENOMEM); 
     96 
     97    rport->put_buf = pj_pool_alloc(pool, rport->base.info.bytes_per_frame); 
     98    PJ_ASSERT_RETURN(rport->put_buf != NULL, PJ_ENOMEM); 
    9599 
    96100 
    97101    /* Create "get_frame" resample */ 
    98     status = pjmedia_resample_create( pool, high_quality, large_filter, 
    99                                       downstream_rate, upstream_rate, 
    100                                       samples_per_frame, &rport->resample_get); 
     102    status = pjmedia_resample_create(pool,  
     103                                     (opt&PJMEDIA_RESAMPLE_USE_LINEAR)==0, 
     104                                     (opt&PJMEDIA_RESAMPLE_USE_SMALL_FILTER)==0, 
     105                                     dn_port->info.clock_rate,  
     106                                     rport->base.info.clock_rate, 
     107                                     dn_port->info.samples_per_frame,  
     108                                     &rport->resample_get); 
    101109    if (status != PJ_SUCCESS) 
    102110        return status; 
    103111 
    104112    /* Create "put_frame" resample */ 
    105     status = pjmedia_resample_create( pool, high_quality, large_filter, 
    106                                       upstream_rate, downstream_rate, 
    107                                       upstream_samples_per_frame, 
    108                                       &rport->resample_put); 
    109  
    110     /* Set get_frame and put_frame interface */ 
     113    status = pjmedia_resample_create(pool,  
     114                                     (opt&PJMEDIA_RESAMPLE_USE_LINEAR)==0,  
     115                                     (opt&PJMEDIA_RESAMPLE_USE_SMALL_FILTER)==0, 
     116                                     rport->base.info.clock_rate,  
     117                                     dn_port->info.clock_rate, 
     118                                     rport->base.info.samples_per_frame, 
     119                                     &rport->resample_put); 
     120 
     121    /* Media port interface */ 
    111122    rport->base.get_frame = &resample_get_frame; 
    112123    rport->base.put_frame = &resample_put_frame; 
     124    rport->base.on_destroy = &resample_destroy; 
    113125 
    114126 
     
    128140 
    129141    /* Return if we don't have downstream port. */ 
    130     if (this_port->downstream_port == NULL) { 
     142    if (rport->dn_port == NULL) { 
    131143        return PJ_SUCCESS; 
    132144    } 
    133145 
    134146    if (frame->type == PJMEDIA_FRAME_TYPE_AUDIO) { 
    135         pjmedia_resample_run( rport->resample_put, frame->buf, rport->put_buf); 
     147        pjmedia_resample_run( rport->resample_put, frame->buf,  
     148                              rport->put_buf); 
    136149 
    137150        downstream_frame.buf = rport->put_buf; 
    138         downstream_frame.size = rport->downstream_frame_size *  
    139                                 BYTES_PER_SAMPLE; 
     151        downstream_frame.size = rport->dn_port->info.bytes_per_frame; 
    140152    } else { 
    141153        downstream_frame.buf = frame->buf; 
     
    146158    downstream_frame.timestamp.u64 = frame->timestamp.u64; 
    147159 
    148     return pjmedia_port_put_frame( this_port->downstream_port,  
    149                                    &downstream_frame ); 
     160    return pjmedia_port_put_frame( rport->dn_port, &downstream_frame ); 
    150161} 
    151162 
     
    156167{ 
    157168    struct resample_port *rport = (struct resample_port*) this_port; 
    158     pjmedia_frame downstream_frame; 
     169    pjmedia_frame tmp_frame; 
    159170    pj_status_t status; 
    160171 
    161172    /* Return silence if we don't have downstream port */ 
    162     if (this_port->downstream_port == NULL) { 
     173    if (rport->dn_port == NULL) { 
    163174        pj_memset(frame->buf, frame->size, 0); 
    164175        return PJ_SUCCESS; 
    165176    } 
    166177 
    167     downstream_frame.buf = rport->get_buf; 
    168     downstream_frame.size = rport->downstream_frame_size * BYTES_PER_SAMPLE; 
    169     downstream_frame.timestamp.u64 = frame->timestamp.u64; 
    170     downstream_frame.type = PJMEDIA_FRAME_TYPE_AUDIO; 
    171  
    172     status = pjmedia_port_get_frame( this_port->downstream_port, 
    173                                      &downstream_frame); 
     178    tmp_frame.buf = rport->get_buf; 
     179    tmp_frame.size = rport->dn_port->info.bytes_per_frame; 
     180    tmp_frame.timestamp.u64 = frame->timestamp.u64; 
     181    tmp_frame.type = PJMEDIA_FRAME_TYPE_AUDIO; 
     182 
     183    status = pjmedia_port_get_frame( rport->dn_port, &tmp_frame); 
    174184    if (status != PJ_SUCCESS) 
    175185        return status; 
    176186 
    177     pjmedia_resample_run( rport->resample_get, rport->get_buf, frame->buf); 
    178  
    179     frame->size = rport->upstream_frame_size * BYTES_PER_SAMPLE; 
     187    if (tmp_frame.type != PJMEDIA_FRAME_TYPE_AUDIO) { 
     188        frame->type = tmp_frame.type; 
     189        frame->timestamp = tmp_frame.timestamp; 
     190        frame->size = tmp_frame.size; 
     191        if (tmp_frame.size) 
     192            pj_memcpy(frame->buf, tmp_frame.buf, tmp_frame.size); 
     193        return PJ_SUCCESS; 
     194    } 
     195 
     196    pjmedia_resample_run( rport->resample_get, tmp_frame.buf, frame->buf); 
     197 
     198    frame->size = rport->base.info.bytes_per_frame; 
    180199    frame->type = PJMEDIA_FRAME_TYPE_AUDIO; 
    181200 
     
    184203 
    185204 
     205static pj_status_t resample_destroy(pjmedia_port *this_port) 
     206{ 
     207    struct resample_port *rport = (struct resample_port*) this_port; 
     208 
     209    if ((rport->options & PJMEDIA_RESAMPLE_DONT_DESTROY_DN)==0) { 
     210        pjmedia_port_destroy(rport->dn_port); 
     211        rport->dn_port = NULL; 
     212    } 
     213 
     214    /* Nothing else to do */ 
     215 
     216    return PJ_SUCCESS; 
     217} 
     218 
  • pjproject/trunk/pjmedia/src/pjmedia/wav_player.c

    r480 r518  
    5656{ 
    5757    pjmedia_port     base; 
     58    unsigned         options; 
     59    pj_bool_t        eof; 
    5860    pj_size_t        bufsize; 
    5961    char            *buf; 
     
    114116    pj_ssize_t size; 
    115117    pj_status_t status; 
     118 
     119    if (fport->eof) { 
     120        return PJ_EEOF; 
     121    } 
    116122 
    117123    while (size_left > 0) { 
     
    136142         */ 
    137143        if (size < (pj_ssize_t)size_to_read) { 
    138             PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, rewinding..", 
    139                       (int)fport->base.info.name.slen, 
    140                       fport->base.info.name.ptr)); 
    141             fport->fpos = sizeof(struct pjmedia_wave_hdr); 
    142             pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET); 
     144            if (fport->options & PJMEDIA_FILE_NO_LOOP) { 
     145                PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, stopping..", 
     146                          (int)fport->base.info.name.slen, 
     147                          fport->base.info.name.ptr)); 
     148                fport->eof = PJ_TRUE; 
     149                return PJ_EEOF; 
     150            } else { 
     151                PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, rewinding..", 
     152                          (int)fport->base.info.name.slen, 
     153                          fport->base.info.name.ptr)); 
     154                fport->fpos = sizeof(struct pjmedia_wave_hdr); 
     155                pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET); 
     156            } 
    143157        } 
    144158    } 
     
    157171                                                     const char *filename, 
    158172                                                     unsigned ptime, 
    159                                                      unsigned flags, 
     173                                                     unsigned options, 
    160174                                                     pj_ssize_t buff_size, 
    161175                                                     void *user_data, 
     
    167181    pj_status_t status; 
    168182 
    169  
    170     PJ_UNUSED_ARG(flags); 
    171183 
    172184    /* Check arguments. */ 
     
    261273    /* Initialize */ 
    262274    fport->base.user_data = user_data; 
     275    fport->options = options; 
    263276 
    264277    /* Update port info. */ 
     
    338351    pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET); 
    339352 
     353    fport->eof = PJ_FALSE; 
    340354    return fill_buffer(fport); 
    341355} 
     
    385399 
    386400            status = fill_buffer(fport); 
    387             if (status != PJ_SUCCESS) 
     401            if (status != PJ_SUCCESS) { 
     402                frame->type = PJMEDIA_FRAME_TYPE_NONE; 
     403                frame->size = 0; 
    388404                return status; 
     405            } 
    389406        } 
    390407    } else { 
  • pjproject/trunk/pjsip-apps/src/samples/resampleplay.c

    r412 r518  
    128128 
    129129    /* Create the resample port. */ 
    130     status = pjmedia_resample_port_create( pool, 1, 1, 
    131                                            file_port->info.clock_rate, 
    132                                            sampling_rate, 
    133                                            channel_count, 
    134                                            (unsigned)( 
    135                                            samples_per_frame * 1.0 * 
    136                                             file_port->info.clock_rate /  
    137                                             sampling_rate), 
     130    status = pjmedia_resample_port_create( pool, file_port, 
     131                                           sampling_rate, 0, 
    138132                                           &resample_port); 
    139133    if (status != PJ_SUCCESS) { 
    140134        app_perror(THIS_FILE, "Unable to create resample port", status); 
    141         return 1; 
    142     } 
    143  
    144     /* Connect resample port to file port */ 
    145     status = pjmedia_port_connect( pool, resample_port, file_port); 
    146     if (status != PJ_SUCCESS) { 
    147         app_perror(THIS_FILE, "Error connecting ports", status); 
    148135        return 1; 
    149136    } 
Note: See TracChangeset for help on using the changeset viewer.