← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/codec.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/codec.h
1
 
/* $Id: codec.h 3664 2011-07-19 03:42:28Z nanang $ */
2
 
/*
3
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19
 
 */
20
 
#ifndef __PJMEDIA_CODEC_H__
21
 
#define __PJMEDIA_CODEC_H__
22
 
 
23
 
 
24
 
/**
25
 
 * @file codec.h
26
 
 * @brief Codec framework.
27
 
 */
28
 
 
29
 
#include <pjmedia/port.h>
30
 
#include <pj/errno.h>
31
 
#include <pj/list.h>
32
 
#include <pj/pool.h>
33
 
 
34
 
PJ_BEGIN_DECL
35
 
 
36
 
 
37
 
/**
38
 
 * @defgroup PJMEDIA_CODEC Codec Framework
39
 
 * @brief Media codec framework and management
40
 
 * @{
41
 
 *
42
 
 * @section codec_mgmt_sec Codec Management
43
 
 * @subsection codec_fact_sec Codec Manager
44
 
 *
45
 
 * The codec manager is used to manage all codec capabilities in the endpoint.
46
 
 * When used with media endpoint (pjmedia_endpt), application can retrieve
47
 
 * the codec manager instance by calling #pjmedia_endpt_get_codec_mgr().
48
 
 *
49
 
 * @subsection reg_new_codec Registering New Codec
50
 
 *
51
 
 * New codec types can be registered to PJMEDIA (or to be precise, to the
52
 
 * codec manager) during run-time.
53
 
 * To do this, application needs to initialize an instance of
54
 
 * codec factory (#pjmedia_codec_factory) and registers this codec factory
55
 
 * by calling #pjmedia_codec_mgr_register_factory().
56
 
 *
57
 
 * For codecs implemented/supported by PJMEDIA, this process is normally
58
 
 * concealed in an easy to use function such as #pjmedia_codec_g711_init().
59
 
 *
60
 
 * @subsection codec_factory Codec Factory
61
 
 *
62
 
 * A codec factory (#pjmedia_codec_factory) is registered to codec manager,
63
 
 * and it is used to create and release codec instance.
64
 
 *
65
 
 * The most important member of the codec factory is the "virtual" function
66
 
 * table #pjmedia_codec_factory_op, where it contains, among other thing,
67
 
 * pointer to functions to allocate and deallocate codec instance.
68
 
 *
69
 
 * @subsection codec_inst Codec Instance
70
 
 *
71
 
 * Application allocates codec instance by calling #pjmedia_codec_mgr_alloc_codec().
72
 
 * One codec instance (#pjmedia_codec) can be used for simultaneous encoding
73
 
 * and decoding.
74
 
 *
75
 
 * The most important member of the codec instance is the "virtual" function
76
 
 * table #pjmedia_codec_op, where it holds pointer to functions to
77
 
 * encode/decode media frames.
78
 
 *
79
 
 * @subsection codec_ident Codec Identification
80
 
 *
81
 
 * A particular codec type in PJMEDIA can be uniquely identified by two
82
 
 * keys: by #pjmedia_codec_info, or by #pjmedia_codec_id string. A fully
83
 
 * qualified codec ID string consists of codec name, sampling rate, and
84
 
 * number of channels. However, application may use only first parts of
85
 
 * the tokens as long as it will make to codec ID unique. For example, "gsm"
86
 
 * is a fully qualified codec name, since it will always have 8000 clock
87
 
 * rate and 1 channel. Other examples of fully qualified codec ID strings
88
 
 * are "pcma", "speex/8000", "speex/16000", and "L16/16000/1". A codec
89
 
 * id "speex" (without clock rate) is not fully qualified, since it will
90
 
 * match the narrowband, wideband, and ultrawideband Speex codec.
91
 
 *
92
 
 * The two keys can be converted to one another, with
93
 
 * #pjmedia_codec_info_to_id() and #pjmedia_codec_mgr_find_codecs_by_id()
94
 
 * functions.
95
 
 *
96
 
 * Codec ID string is not case sensitive.
97
 
 *
98
 
 *
99
 
 * @section using_codec Using the Codec Framework
100
 
 * @subsection init_alloc_codec Allocating Codec
101
 
 *
102
 
 * Application needs to allocate one codec instance for encoding and decoding
103
 
 * media frames. One codec instance can be used to perform both encoding
104
 
 * and decoding.
105
 
 *
106
 
 * Application allocates codec by calling #pjmedia_codec_mgr_alloc_codec().
107
 
 * This function takes #pjmedia_codec_info argument, which is used to locate
108
 
 * the particular codec factory to be used to allocate the codec.
109
 
 *
110
 
 * Application can build #pjmedia_codec_info structure manually for
111
 
 * the specific codec, or alternatively it may get the #pjmedia_codec_info
112
 
 * from the codec ID string, by using #pjmedia_codec_mgr_find_codecs_by_id()
113
 
 * function.
114
 
 *
115
 
 * The following snippet shows an example to allocate a codec:
116
 
 *
117
 
 \code
118
 
    pj_str_t codec_id;
119
 
    pjmedia_codec_info *codec_info;
120
 
    unsigned count = 1;
121
 
    pjmedia_codec *codec;
122
 
 
123
 
    codec_id = pj_str("pcma");
124
 
 
125
 
    // Find codec info for the specified coded ID (i.e. "pcma").
126
 
    status = pjmedia_codec_mgr_find_codecs_by_id( codec_mgr, &codec_id,
127
 
                                                  &count, &codec_info, NULL);
128
 
 
129
 
    // Allocate the codec.
130
 
    status = pjmedia_codec_mgr_alloc_codec( codec_mgr, codec_info, &codec );
131
 
 
132
 
 \endcode
133
 
 *
134
 
 *
135
 
 * @subsection opening_codec Initializing Codec
136
 
 *
137
 
 * Once codec is allocated, application needs to initialize the codec
138
 
 * by calling <b><tt>open</tt></b> member of the codec. This function
139
 
 * takes #pjmedia_codec_param as the argument, which contains the
140
 
 * settings for the codec.
141
 
 *
142
 
 * Application shoud use #pjmedia_codec_mgr_get_default_param() function
143
 
 * to initiaize #pjmedia_codec_param. The <tt>setting</tt> part of
144
 
 * #pjmedia_codec_param then can be tuned to suit the application's
145
 
 * requirements.
146
 
 *
147
 
 * The following snippet shows an example to initialize codec:
148
 
 *
149
 
 \code
150
 
    pjmedia_codec_param param;
151
 
 
152
 
    // Retrieve default codec param for the specified codec.
153
 
    pjmedia_codec_mgr_get_default_param(codec_mgr, codec_info
154
 
                                        &param);
155
 
 
156
 
    // Application may change the "settings" part of codec param,
157
 
    // for example, to disable VAD
158
 
    param.setting.vad = 0;
159
 
 
160
 
    // Open the codec using the specified settings.
161
 
    codec->op->open( codec, &param );
162
 
 
163
 
 \endcode
164
 
 *
165
 
 *
166
 
 * @subsection enc_dec_codec Encoding and Decoding Media Frames
167
 
 *
168
 
 * Application encodes and decodes media frames by calling
169
 
 * <tt>encode</tt> and <tt>decode</tt> member of the codec's "virtual"
170
 
 * function table (#pjmedia_codec_op).
171
 
 *
172
 
 * @subsection plc_codec Concealing Lost Frames
173
 
 *
174
 
 * All codecs has Packet Lost Concealment (PLC) feature, and application
175
 
 * can activate the PLC to conceal lost frames by calling <tt>recover</tt>
176
 
 * member of the codec's "virtual" function table (#pjmedia_codec_op).
177
 
 *
178
 
 * If the codec's algorithm supports PLC, the <tt>recover</tt> function
179
 
 * will use the codec's PLC. Otherwise for codecs that don't have
180
 
 * intrinsic PLC, PJMEDIA will suply the PLC implementation from the
181
 
 * @ref PJMED_PLC implementation.
182
 
 *
183
 
 * @subsection close_codec Closing and Releasing the Codec
184
 
 *
185
 
 * The codec must be closed by calling <tt>close</tt> member of the codec's
186
 
 * operation. Then it must be released by calling
187
 
 * #pjmedia_codec_mgr_dealloc_codec().
188
 
 */
189
 
 
190
 
 
191
 
/**
192
 
 * Standard RTP static payload types, as defined by RFC 3551.
193
 
 * The header file <pjmedia-codec/types.h> also declares dynamic payload
194
 
 * type numbers that are used by PJMEDIA when advertising the capability
195
 
 * for example in SDP message.
196
 
 */
197
 
enum pjmedia_rtp_pt
198
 
{
199
 
    PJMEDIA_RTP_PT_PCMU = 0,        /**< audio PCMU                         */
200
 
    PJMEDIA_RTP_PT_G721 = 2,        /**< audio G721 (old def for G726-32)   */
201
 
    PJMEDIA_RTP_PT_GSM  = 3,        /**< audio GSM                          */
202
 
    PJMEDIA_RTP_PT_G723 = 4,        /**< audio G723                         */
203
 
    PJMEDIA_RTP_PT_DVI4_8K = 5,     /**< audio DVI4 8KHz                    */
204
 
    PJMEDIA_RTP_PT_DVI4_16K = 6,    /**< audio DVI4 16Khz                   */
205
 
    PJMEDIA_RTP_PT_LPC = 7,         /**< audio LPC                          */
206
 
    PJMEDIA_RTP_PT_PCMA = 8,        /**< audio PCMA                         */
207
 
    PJMEDIA_RTP_PT_G722 = 9,        /**< audio G722                         */
208
 
    PJMEDIA_RTP_PT_L16_2 = 10,      /**< audio 16bit linear 44.1KHz stereo  */
209
 
    PJMEDIA_RTP_PT_L16_1 = 11,      /**< audio 16bit linear 44.1KHz mono    */
210
 
    PJMEDIA_RTP_PT_QCELP = 12,      /**< audio QCELP                        */
211
 
    PJMEDIA_RTP_PT_CN = 13,         /**< audio Comfort Noise                */
212
 
    PJMEDIA_RTP_PT_MPA = 14,        /**< audio MPEG1/MPEG2 elemetr. streams */
213
 
    PJMEDIA_RTP_PT_G728 = 15,       /**< audio G728                         */
214
 
    PJMEDIA_RTP_PT_DVI4_11K = 16,   /**< audio DVI4 11.025KHz mono          */
215
 
    PJMEDIA_RTP_PT_DVI4_22K = 17,   /**< audio DVI4 22.050KHz mono          */
216
 
    PJMEDIA_RTP_PT_G729 = 18,       /**< audio G729                         */
217
 
 
218
 
    PJMEDIA_RTP_PT_CELB = 25,       /**< video/comb Cell-B by Sun (RFC2029) */
219
 
    PJMEDIA_RTP_PT_JPEG = 26,       /**< video JPEG                         */
220
 
    PJMEDIA_RTP_PT_NV = 28,         /**< video NV  by nv program by Xerox   */
221
 
    PJMEDIA_RTP_PT_H261 = 31,       /**< video H261                         */
222
 
    PJMEDIA_RTP_PT_MPV = 32,        /**< video MPEG1 or MPEG2 elementary    */
223
 
    PJMEDIA_RTP_PT_MP2T = 33,       /**< video MPEG2 transport              */
224
 
    PJMEDIA_RTP_PT_H263 = 34,       /**< video H263                         */
225
 
 
226
 
    PJMEDIA_RTP_PT_DYNAMIC = 96     /**< start of dynamic RTP payload       */
227
 
 
228
 
};
229
 
 
230
 
 
231
 
/**
232
 
 * Identification used to search for codec factory that supports specific
233
 
 * codec specification.
234
 
 */
235
 
typedef struct pjmedia_codec_info
236
 
{
237
 
    pjmedia_type    type;           /**< Media type.                    */
238
 
    unsigned        pt;             /**< Payload type (can be dynamic). */
239
 
    pj_str_t        encoding_name;  /**< Encoding name.                 */
240
 
    unsigned        clock_rate;     /**< Sampling rate.                 */
241
 
    unsigned        channel_cnt;    /**< Channel count.                 */
242
 
} pjmedia_codec_info;
243
 
 
244
 
/**
245
 
 * Structure of codec specific parameters which contains name=value pairs.
246
 
 * The codec specific parameters are to be used with SDP according to
247
 
 * the standards (e.g: RFC 3555) in SDP 'a=fmtp' attribute.
248
 
 */
249
 
typedef struct pjmedia_codec_fmtp
250
 
{
251
 
    pj_uint8_t      cnt;            /**< Number of parameters.          */
252
 
    struct param {
253
 
        pj_str_t    name;           /**< Parameter name.                */
254
 
        pj_str_t    val;            /**< Parameter value.               */
255
 
    } param [PJMEDIA_CODEC_MAX_FMTP_CNT]; /**< The parameters.          */
256
 
} pjmedia_codec_fmtp;
257
 
 
258
 
/**
259
 
 * Detailed codec attributes used in configuring a codec and in querying
260
 
 * the capability of codec factories. Default attributes of any codecs could
261
 
 * be queried using #pjmedia_codec_mgr_get_default_param() and modified
262
 
 * using #pjmedia_codec_mgr_set_default_param().
263
 
 *
264
 
 * Please note that codec parameter also contains SDP specific setting,
265
 
 * #dec_fmtp and #enc_fmtp, which may need to be set appropriately based on
266
 
 * the effective setting. See each codec documentation for more detail.
267
 
 */
268
 
typedef struct pjmedia_codec_param
269
 
{
270
 
    /**
271
 
     * The "info" part of codec param describes the capability of the codec,
272
 
     * and the value should NOT be changed by application.
273
 
     */
274
 
    struct {
275
 
       unsigned    clock_rate;          /**< Sampling rate in Hz            */
276
 
       unsigned    channel_cnt;         /**< Channel count.                 */
277
 
       pj_uint32_t avg_bps;             /**< Average bandwidth in bits/sec  */
278
 
       pj_uint32_t max_bps;             /**< Maximum bandwidth in bits/sec  */
279
 
       pj_uint16_t frm_ptime;           /**< Decoder frame ptime in msec.   */
280
 
       pj_uint16_t enc_ptime;           /**< Encoder ptime, or zero if it's
281
 
                                             equal to decoder ptime.        */
282
 
       pj_uint8_t  pcm_bits_per_sample; /**< Bits/sample in the PCM side    */
283
 
       pj_uint8_t  pt;                  /**< Payload type.                  */
284
 
       pjmedia_format_id fmt_id;        /**< Source format, it's format of
285
 
                                             encoder input and decoder
286
 
                                             output.                        */
287
 
    } info;
288
 
 
289
 
    /**
290
 
     * The "setting" part of codec param describes various settings to be
291
 
     * applied to the codec. When the codec param is retrieved from the codec
292
 
     * or codec factory, the values of these will be filled by the capability
293
 
     * of the codec. Any features that are supported by the codec (e.g. vad
294
 
     * or plc) will be turned on, so that application can query which
295
 
     * capabilities are supported by the codec. Application may change the
296
 
     * settings here before instantiating the codec/stream.
297
 
     */
298
 
    struct {
299
 
        pj_uint8_t  frm_per_pkt;    /**< Number of frames per packet.   */
300
 
        unsigned    vad:1;          /**< Voice Activity Detector.       */
301
 
        unsigned    cng:1;          /**< Comfort Noise Generator.       */
302
 
        unsigned    penh:1;         /**< Perceptual Enhancement         */
303
 
        unsigned    plc:1;          /**< Packet loss concealment        */
304
 
        unsigned    reserved:1;     /**< Reserved, must be zero.        */
305
 
        pjmedia_codec_fmtp enc_fmtp;/**< Encoder's fmtp params.         */
306
 
        pjmedia_codec_fmtp dec_fmtp;/**< Decoder's fmtp params.         */
307
 
    } setting;
308
 
} pjmedia_codec_param;
309
 
 
310
 
 
311
 
 
312
 
/*
313
 
 * Forward declaration for pjmedia_codec.
314
 
 */
315
 
typedef struct pjmedia_codec pjmedia_codec;
316
 
 
317
 
 
318
 
/**
319
 
 * This structure describes codec operations. Each codec MUST implement
320
 
 * all of these functions.
321
 
 */
322
 
typedef struct pjmedia_codec_op
323
 
{
324
 
    /**
325
 
     * Initialize codec using the specified attribute.
326
 
     *
327
 
     * Application should call #pjmedia_codec_init() instead of
328
 
     * calling this function directly.
329
 
     *
330
 
     * @param codec     The codec instance.
331
 
     * @param pool      Pool to use when the codec needs to allocate
332
 
     *                  some memory.
333
 
     *
334
 
     * @return          PJ_SUCCESS on success.
335
 
     */
336
 
    pj_status_t (*init)(pjmedia_codec *codec,
337
 
                        pj_pool_t *pool );
338
 
 
339
 
    /**
340
 
     * Open the codec and initialize with the specified parameter.
341
 
     * Upon successful initialization, the codec may modify the parameter
342
 
     * and fills in the unspecified values (such as enc_ptime, when
343
 
     * encoder ptime is different than decoder ptime).
344
 
     *
345
 
     * Application should call #pjmedia_codec_open() instead of
346
 
     * calling this function directly.
347
 
     *
348
 
     * @param codec     The codec instance.
349
 
     * @param param     Codec initialization parameter.
350
 
     *
351
 
     * @return          PJ_SUCCESS on success.
352
 
     */
353
 
    pj_status_t (*open)(pjmedia_codec *codec,
354
 
                        pjmedia_codec_param *param );
355
 
 
356
 
    /**
357
 
     * Close and shutdown codec, releasing all resources allocated by
358
 
     * this codec, if any.
359
 
     *
360
 
     * Application should call #pjmedia_codec_close() instead of
361
 
     * calling this function directly.
362
 
     *
363
 
     * @param codec     The codec instance.
364
 
     *
365
 
     * @return          PJ_SUCCESS on success.
366
 
     */
367
 
    pj_status_t (*close)(pjmedia_codec *codec);
368
 
 
369
 
    /**
370
 
     * Modify the codec parameter after the codec is open.
371
 
     * Note that not all codec parameters can be modified during run-time.
372
 
     * When the parameter cannot be changed, this function will return
373
 
     * non-PJ_SUCCESS, and the original parameters will not be changed.
374
 
     *
375
 
     * Application can expect changing trivial codec settings such as
376
 
     * changing VAD setting to succeed.
377
 
     *
378
 
     * Application should call #pjmedia_codec_modify() instead of
379
 
     * calling this function directly.
380
 
     *
381
 
     * @param codec     The codec instance.
382
 
     * @param param     The new codec parameter.
383
 
     *
384
 
     * @return          PJ_SUCCESS on success.
385
 
     */
386
 
    pj_status_t (*modify)(pjmedia_codec *codec,
387
 
                          const pjmedia_codec_param *param );
388
 
 
389
 
    /**
390
 
     * Instruct the codec to inspect the specified payload/packet and
391
 
     * split the packet into individual base frames. Each output frames will
392
 
     * have ptime that is equal to basic frame ptime (i.e. the value of
393
 
     * info.frm_ptime in #pjmedia_codec_param).
394
 
     *
395
 
     * Application should call #pjmedia_codec_parse() instead of
396
 
     * calling this function directly.
397
 
     *
398
 
     * @param codec     The codec instance
399
 
     * @param pkt       The input packet.
400
 
     * @param pkt_size  Size of the packet.
401
 
     * @param timestamp The timestamp of the first sample in the packet.
402
 
     * @param frame_cnt On input, specifies the maximum number of frames
403
 
     *                  in the array. On output, the codec must fill
404
 
     *                  with number of frames detected in the packet.
405
 
     * @param frames    On output, specifies the frames that have been
406
 
     *                  detected in the packet.
407
 
     *
408
 
     * @return          PJ_SUCCESS on success.
409
 
     */
410
 
    pj_status_t (*parse)( pjmedia_codec *codec,
411
 
                          void *pkt,
412
 
                          pj_size_t pkt_size,
413
 
                          const pj_timestamp *timestamp,
414
 
                          unsigned *frame_cnt,
415
 
                          pjmedia_frame frames[]);
416
 
 
417
 
    /**
418
 
     * Instruct the codec to encode the specified input frame. The input
419
 
     * PCM samples MUST have ptime that is multiplication of base frame
420
 
     * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
421
 
     *
422
 
     * Application should call #pjmedia_codec_encode() instead of
423
 
     * calling this function directly.
424
 
     *
425
 
     * @param codec     The codec instance.
426
 
     * @param input     The input frame.
427
 
     * @param out_size  The length of buffer in the output frame.
428
 
     * @param output    The output frame.
429
 
     *
430
 
     * @return          PJ_SUCCESS on success;
431
 
     */
432
 
    pj_status_t (*encode)(pjmedia_codec *codec,
433
 
                          const struct pjmedia_frame *input,
434
 
                          unsigned out_size,
435
 
                          struct pjmedia_frame *output);
436
 
 
437
 
    /**
438
 
     * Instruct the codec to decode the specified input frame. The input
439
 
     * frame MUST have ptime that is exactly equal to base frame
440
 
     * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
441
 
     * Application can achieve this by parsing the packet into base
442
 
     * frames before decoding each frame.
443
 
     *
444
 
     * Application should call #pjmedia_codec_decode() instead of
445
 
     * calling this function directly.
446
 
     *
447
 
     * @param codec     The codec instance.
448
 
     * @param input     The input frame.
449
 
     * @param out_size  The length of buffer in the output frame.
450
 
     * @param output    The output frame.
451
 
     *
452
 
     * @return          PJ_SUCCESS on success;
453
 
     */
454
 
    pj_status_t (*decode)(pjmedia_codec *codec,
455
 
                          const struct pjmedia_frame *input,
456
 
                          unsigned out_size,
457
 
                          struct pjmedia_frame *output);
458
 
 
459
 
    /**
460
 
     * Instruct the codec to recover a missing frame.
461
 
     *
462
 
     * Application should call #pjmedia_codec_recover() instead of
463
 
     * calling this function directly.
464
 
     *
465
 
     * @param codec     The codec instance.
466
 
     * @param out_size  The length of buffer in the output frame.
467
 
     * @param output    The output frame where generated signal
468
 
     *                  will be placed.
469
 
     *
470
 
     * @return          PJ_SUCCESS on success;
471
 
     */
472
 
    pj_status_t (*recover)(pjmedia_codec *codec,
473
 
                           unsigned out_size,
474
 
                           struct pjmedia_frame *output);
475
 
} pjmedia_codec_op;
476
 
 
477
 
 
478
 
 
479
 
/*
480
 
 * Forward declaration for pjmedia_codec_factory.
481
 
 */
482
 
typedef struct pjmedia_codec_factory pjmedia_codec_factory;
483
 
 
484
 
 
485
 
/**
486
 
 * This structure describes a codec instance.
487
 
 */
488
 
struct pjmedia_codec
489
 
{
490
 
    /** Entries to put this codec instance in codec factory's list. */
491
 
    PJ_DECL_LIST_MEMBER(struct pjmedia_codec);
492
 
 
493
 
    /** Codec's private data. */
494
 
    void                    *codec_data;
495
 
 
496
 
    /** Codec factory where this codec was allocated. */
497
 
    pjmedia_codec_factory   *factory;
498
 
 
499
 
    /** Operations to codec. */
500
 
    pjmedia_codec_op        *op;
501
 
};
502
 
 
503
 
 
504
 
 
505
 
/**
506
 
 * This structure describes operations that must be supported by codec
507
 
 * factories.
508
 
 */
509
 
typedef struct pjmedia_codec_factory_op
510
 
{
511
 
    /**
512
 
     * Check whether the factory can create codec with the specified
513
 
     * codec info.
514
 
     *
515
 
     * @param factory   The codec factory.
516
 
     * @param info      The codec info.
517
 
     *
518
 
     * @return          PJ_SUCCESS if this factory is able to create an
519
 
     *                  instance of codec with the specified info.
520
 
     */
521
 
    pj_status_t (*test_alloc)(pjmedia_codec_factory *factory,
522
 
                              const pjmedia_codec_info *info );
523
 
 
524
 
    /**
525
 
     * Create default attributes for the specified codec ID. This function
526
 
     * can be called by application to get the capability of the codec.
527
 
     *
528
 
     * @param factory   The codec factory.
529
 
     * @param info      The codec info.
530
 
     * @param attr      The attribute to be initialized.
531
 
     *
532
 
     * @return          PJ_SUCCESS if success.
533
 
     */
534
 
    pj_status_t (*default_attr)(pjmedia_codec_factory *factory,
535
 
                                const pjmedia_codec_info *info,
536
 
                                pjmedia_codec_param *attr );
537
 
 
538
 
    /**
539
 
     * Enumerate supported codecs that can be created using this factory.
540
 
     *
541
 
     *  @param factory  The codec factory.
542
 
     *  @param count    On input, specifies the number of elements in
543
 
     *                  the array. On output, the value will be set to
544
 
     *                  the number of elements that have been initialized
545
 
     *                  by this function.
546
 
     *  @param info     The codec info array, which contents will be
547
 
     *                  initialized upon return.
548
 
     *
549
 
     *  @return         PJ_SUCCESS on success.
550
 
     */
551
 
    pj_status_t (*enum_info)(pjmedia_codec_factory *factory,
552
 
                             unsigned *count,
553
 
                             pjmedia_codec_info codecs[]);
554
 
 
555
 
    /**
556
 
     * Create one instance of the codec with the specified codec info.
557
 
     *
558
 
     * @param factory   The codec factory.
559
 
     * @param info      The codec info.
560
 
     * @param p_codec   Pointer to receive the codec instance.
561
 
     *
562
 
     * @return          PJ_SUCCESS on success.
563
 
     */
564
 
    pj_status_t (*alloc_codec)(pjmedia_codec_factory *factory,
565
 
                               const pjmedia_codec_info *info,
566
 
                               pjmedia_codec **p_codec);
567
 
 
568
 
    /**
569
 
     * This function is called by codec manager to return a particular
570
 
     * instance of codec back to the codec factory.
571
 
     *
572
 
     * @param factory   The codec factory.
573
 
     * @param codec     The codec instance to be returned.
574
 
     *
575
 
     * @return          PJ_SUCCESS on success.
576
 
     */
577
 
    pj_status_t (*dealloc_codec)(pjmedia_codec_factory *factory,
578
 
                                 pjmedia_codec *codec );
579
 
 
580
 
    /**
581
 
     * This callback will be called to deinitialize and destroy this factory.
582
 
     */
583
 
    pj_status_t (*destroy)(void);
584
 
 
585
 
} pjmedia_codec_factory_op;
586
 
 
587
 
 
588
 
 
589
 
/**
590
 
 * Codec factory describes a module that is able to create codec with specific
591
 
 * capabilities. These capabilities can be queried by codec manager to create
592
 
 * instances of codec.
593
 
 */
594
 
struct pjmedia_codec_factory
595
 
{
596
 
    /** Entries to put this structure in the codec manager list. */
597
 
    PJ_DECL_LIST_MEMBER(struct pjmedia_codec_factory);
598
 
 
599
 
    /** The factory's private data. */
600
 
    void                     *factory_data;
601
 
 
602
 
    /** Operations to the factory. */
603
 
    pjmedia_codec_factory_op *op;
604
 
 
605
 
};
606
 
 
607
 
 
608
 
/**
609
 
 * Declare maximum codecs
610
 
 */
611
 
#define PJMEDIA_CODEC_MGR_MAX_CODECS        32
612
 
 
613
 
 
614
 
/**
615
 
 * Specify these values to set the codec priority, by calling
616
 
 * #pjmedia_codec_mgr_set_codec_priority().
617
 
 */
618
 
typedef enum pjmedia_codec_priority
619
 
{
620
 
    /**
621
 
     * This priority makes the codec the highest in the order.
622
 
     * The last codec specified with this priority will get the
623
 
     * highest place in the order, and will change the priority
624
 
     * of previously highest priority codec to NEXT_HIGHER.
625
 
     */
626
 
    PJMEDIA_CODEC_PRIO_HIGHEST = 255,
627
 
 
628
 
    /**
629
 
     * This priority will put the codec as the next codec after
630
 
     * codecs with this same priority.
631
 
     */
632
 
    PJMEDIA_CODEC_PRIO_NEXT_HIGHER = 254,
633
 
 
634
 
    /**
635
 
     * This is the initial codec priority when it is registered to
636
 
     * codec manager by codec factory.
637
 
     */
638
 
    PJMEDIA_CODEC_PRIO_NORMAL = 128,
639
 
 
640
 
    /**
641
 
     * This priority makes the codec the lowest in the order.
642
 
     * The last codec specified with this priority will be put
643
 
     * in the last place in the order.
644
 
     */
645
 
    PJMEDIA_CODEC_PRIO_LOWEST = 1,
646
 
 
647
 
    /**
648
 
     * This priority will prevent the codec from being listed in the
649
 
     * SDP created by media endpoint, thus should prevent the codec
650
 
     * from being used in the sessions. However, the codec will still
651
 
     * be listed by #pjmedia_codec_mgr_enum_codecs() and other codec
652
 
     * query functions.
653
 
     */
654
 
    PJMEDIA_CODEC_PRIO_DISABLED = 0
655
 
 
656
 
} pjmedia_codec_priority;
657
 
 
658
 
 
659
 
/**
660
 
 * Codec identification (e.g. "pcmu/8000/1").
661
 
 * See @ref codec_ident for more info.
662
 
 */
663
 
typedef char pjmedia_codec_id[32];
664
 
 
665
 
 
666
 
/**
667
 
 * Opaque declaration of default codecs parameters.
668
 
 */
669
 
typedef struct pjmedia_codec_default_param pjmedia_codec_default_param;
670
 
 
671
 
/**
672
 
 * Codec manager maintains array of these structs for each supported
673
 
 * codec.
674
 
 */
675
 
struct pjmedia_codec_desc
676
 
{
677
 
    pjmedia_codec_info      info;       /**< Codec info.            */
678
 
    pjmedia_codec_id        id;         /**< Fully qualified name   */
679
 
    pjmedia_codec_priority  prio;       /**< Priority.              */
680
 
    pjmedia_codec_factory  *factory;    /**< The factory.           */
681
 
    pjmedia_codec_default_param *param; /**< Default codecs
682
 
                                             parameters.            */
683
 
};
684
 
 
685
 
 
686
 
/**
687
 
 * The declaration for codec manager. Application doesn't normally need
688
 
 * to see this declaration, but nevertheless this declaration is needed
689
 
 * by media endpoint to instantiate the codec manager.
690
 
 */
691
 
typedef struct pjmedia_codec_mgr
692
 
{
693
 
    /** Media endpoint instance. */
694
 
    pj_pool_factory             *pf;
695
 
 
696
 
    /** Codec manager pool. */
697
 
    pj_pool_t                   *pool;
698
 
 
699
 
    /** Codec manager mutex. */
700
 
    pj_mutex_t                  *mutex;
701
 
 
702
 
    /** List of codec factories registered to codec manager. */
703
 
    pjmedia_codec_factory        factory_list;
704
 
 
705
 
    /** Number of supported codecs. */
706
 
    unsigned                     codec_cnt;
707
 
 
708
 
    /** Array of codec descriptor. */
709
 
    struct pjmedia_codec_desc    codec_desc[PJMEDIA_CODEC_MGR_MAX_CODECS];
710
 
 
711
 
} pjmedia_codec_mgr;
712
 
 
713
 
 
714
 
 
715
 
/**
716
 
 * Initialize codec manager. Normally this function is called by pjmedia
717
 
 * endpoint's initialization code.
718
 
 *
719
 
 * @param mgr       Codec manager instance.
720
 
 * @param pf        Pool factory instance.
721
 
 *
722
 
 * @return          PJ_SUCCESS on success.
723
 
 */
724
 
PJ_DECL(pj_status_t) pjmedia_codec_mgr_init(pjmedia_codec_mgr *mgr,
725
 
                                            pj_pool_factory *pf);
726
 
 
727
 
 
728
 
/**
729
 
 * Destroy codec manager. Normally this function is called by pjmedia
730
 
 * endpoint's deinitialization code.
731
 
 *
732
 
 * @param mgr       Codec manager instance.
733
 
 *
734
 
 * @return          PJ_SUCCESS on success.
735
 
 */
736
 
PJ_DECL(pj_status_t) pjmedia_codec_mgr_destroy(pjmedia_codec_mgr *mgr);
737
 
 
738
 
 
739
 
/**
740
 
 * Register codec factory to codec manager. This will also register
741
 
 * all supported codecs in the factory to the codec manager.
742
 
 *
743
 
 * @param mgr       The codec manager instance. Application can get the
744
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
745
 
 * @param factory   The codec factory to be registered.
746
 
 *
747
 
 * @return          PJ_SUCCESS on success.
748
 
 */
749
 
PJ_DECL(pj_status_t)
750
 
pjmedia_codec_mgr_register_factory( pjmedia_codec_mgr *mgr,
751
 
                                    pjmedia_codec_factory *factory);
752
 
 
753
 
/**
754
 
 * Unregister codec factory from the codec manager. This will also
755
 
 * remove all the codecs registered by the codec factory from the
756
 
 * codec manager's list of supported codecs. This function should
757
 
 * only be called by the codec implementers and not by application.
758
 
 *
759
 
 * @param mgr       The codec manager instance, use
760
 
 *                      #pjmedia_endpt_get_codec_mgr().
761
 
 * @param factory   The codec factory to be unregistered.
762
 
 *
763
 
 * @return          PJ_SUCCESS on success.
764
 
 */
765
 
PJ_DECL(pj_status_t)
766
 
pjmedia_codec_mgr_unregister_factory( pjmedia_codec_mgr *mgr,
767
 
                                      pjmedia_codec_factory *factory);
768
 
 
769
 
/**
770
 
 * Enumerate all supported codecs that have been registered to the
771
 
 * codec manager by codec factories.
772
 
 *
773
 
 * @param mgr       The codec manager instance. Application can get the
774
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
775
 
 * @param count     On input, specifies the number of elements in
776
 
 *                  the array. On output, the value will be set to
777
 
 *                  the number of elements that have been initialized
778
 
 *                  by this function.
779
 
 * @param info      The codec info array, which contents will be
780
 
 *                  initialized upon return.
781
 
 * @param prio      Optional pointer to receive array of codec priorities.
782
 
 *
783
 
 * @return          PJ_SUCCESS on success.
784
 
 */
785
 
PJ_DECL(pj_status_t) pjmedia_codec_mgr_enum_codecs( pjmedia_codec_mgr *mgr,
786
 
                                                    unsigned *count,
787
 
                                                    pjmedia_codec_info info[],
788
 
                                                    unsigned *prio);
789
 
 
790
 
/**
791
 
 * Get codec info for the specified static payload type. Note that
792
 
 * this can only find codec with static payload types. This function can
793
 
 * be used to find codec info for a payload type inside SDP which doesn't
794
 
 * have the corresponding rtpmap attribute.
795
 
 *
796
 
 * @param mgr       The codec manager instance. Application can get the
797
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
798
 
 * @param pt        Static payload type/number.
799
 
 * @param inf       Pointer to receive codec info.
800
 
 *
801
 
 * @return          PJ_SUCCESS on success.
802
 
 */
803
 
PJ_DECL(pj_status_t)
804
 
pjmedia_codec_mgr_get_codec_info( pjmedia_codec_mgr *mgr,
805
 
                                  unsigned pt,
806
 
                                  const pjmedia_codec_info **inf);
807
 
 
808
 
/**
809
 
 * Convert codec info struct into a unique codec identifier.
810
 
 * A codec identifier looks something like "L16/44100/2".
811
 
 *
812
 
 * @param info      The codec info
813
 
 * @param id        Buffer to put the codec info string.
814
 
 * @param max_len   The length of the buffer.
815
 
 *
816
 
 * @return          The null terminated codec info string, or NULL if
817
 
 *                  the buffer is not long enough.
818
 
 */
819
 
PJ_DECL(char*) pjmedia_codec_info_to_id(const pjmedia_codec_info *info,
820
 
                                        char *id, unsigned max_len );
821
 
 
822
 
 
823
 
/**
824
 
 * Find codecs by the unique codec identifier. This function will find
825
 
 * all codecs that match the codec identifier prefix. For example, if
826
 
 * "L16" is specified, then it will find "L16/8000/1", "L16/16000/1",
827
 
 * and so on, up to the maximum count specified in the argument.
828
 
 *
829
 
 * @param mgr       The codec manager instance. Application can get the
830
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
831
 
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
832
 
 *                  string is given, it will match all codecs.
833
 
 * @param count     Maximum number of codecs to find. On return, it
834
 
 *                  contains the actual number of codecs found.
835
 
 * @param p_info    Array of pointer to codec info to be filled. This
836
 
 *                  argument may be NULL, which in this case, only
837
 
 *                  codec count will be returned.
838
 
 * @param prio      Optional array of codec priorities.
839
 
 *
840
 
 * @return          PJ_SUCCESS if at least one codec info is found.
841
 
 */
842
 
PJ_DECL(pj_status_t)
843
 
pjmedia_codec_mgr_find_codecs_by_id( pjmedia_codec_mgr *mgr,
844
 
                                     const pj_str_t *codec_id,
845
 
                                     unsigned *count,
846
 
                                     const pjmedia_codec_info *p_info[],
847
 
                                     unsigned prio[]);
848
 
 
849
 
 
850
 
/**
851
 
 * Set codec priority. The codec priority determines the order of
852
 
 * the codec in the SDP created by the endpoint. If more than one codecs
853
 
 * are found with the same codec_id prefix, then the function sets the
854
 
 * priorities of all those codecs.
855
 
 *
856
 
 * @param mgr       The codec manager instance. Application can get the
857
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
858
 
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
859
 
 *                  string is given, it will match all codecs.
860
 
 * @param prio      Priority to be set. The priority can have any value
861
 
 *                  between 1 to 255. When the priority is set to zero,
862
 
 *                  the codec will be disabled.
863
 
 *
864
 
 * @return          PJ_SUCCESS if at least one codec info is found.
865
 
 */
866
 
PJ_DECL(pj_status_t)
867
 
pjmedia_codec_mgr_set_codec_priority(pjmedia_codec_mgr *mgr,
868
 
                                     const pj_str_t *codec_id,
869
 
                                     pj_uint8_t prio);
870
 
 
871
 
 
872
 
/**
873
 
 * Get default codec param for the specified codec info.
874
 
 *
875
 
 * @param mgr       The codec manager instance. Application can get the
876
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
877
 
 * @param info      The codec info, which default parameter's is being
878
 
 *                  queried.
879
 
 * @param param     On return, will be filled with the default codec
880
 
 *                  parameter.
881
 
 *
882
 
 * @return          PJ_SUCCESS on success.
883
 
 */
884
 
PJ_DECL(pj_status_t)
885
 
pjmedia_codec_mgr_get_default_param( pjmedia_codec_mgr *mgr,
886
 
                                     const pjmedia_codec_info *info,
887
 
                                     pjmedia_codec_param *param );
888
 
 
889
 
 
890
 
/**
891
 
 * Set default codec param for the specified codec info.
892
 
 *
893
 
 * @param mgr       The codec manager instance. Application can get the
894
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
895
 
 * @param info      The codec info, which default parameter's is being
896
 
 *                  updated.
897
 
 * @param param     The new default codec parameter. Set to NULL to reset
898
 
 *                  codec parameter to library default settings.
899
 
 *
900
 
 * @return          PJ_SUCCESS on success.
901
 
 */
902
 
PJ_DECL(pj_status_t)
903
 
pjmedia_codec_mgr_set_default_param( pjmedia_codec_mgr *mgr,
904
 
                                     const pjmedia_codec_info *info,
905
 
                                     const pjmedia_codec_param *param );
906
 
 
907
 
 
908
 
/**
909
 
 * Request the codec manager to allocate one instance of codec with the
910
 
 * specified codec info. The codec will enumerate all codec factories
911
 
 * until it finds factory that is able to create the specified codec.
912
 
 *
913
 
 * @param mgr       The codec manager instance. Application can get the
914
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
915
 
 * @param info      The information about the codec to be created.
916
 
 * @param p_codec   Pointer to receive the codec instance.
917
 
 *
918
 
 * @return          PJ_SUCCESS on success.
919
 
 */
920
 
PJ_DECL(pj_status_t)
921
 
pjmedia_codec_mgr_alloc_codec( pjmedia_codec_mgr *mgr,
922
 
                               const pjmedia_codec_info *info,
923
 
                               pjmedia_codec **p_codec);
924
 
 
925
 
/**
926
 
 * Deallocate the specified codec instance. The codec manager will return
927
 
 * the instance of the codec back to its factory.
928
 
 *
929
 
 * @param mgr       The codec manager instance. Application can get the
930
 
 *                  instance by calling #pjmedia_endpt_get_codec_mgr().
931
 
 * @param codec     The codec instance.
932
 
 *
933
 
 * @return          PJ_SUCESS on success.
934
 
 */
935
 
PJ_DECL(pj_status_t) pjmedia_codec_mgr_dealloc_codec(pjmedia_codec_mgr *mgr,
936
 
                                                     pjmedia_codec *codec);
937
 
 
938
 
 
939
 
 
940
 
/**
941
 
 * Initialize codec using the specified attribute.
942
 
 *
943
 
 * @param codec     The codec instance.
944
 
 * @param pool      Pool to use when the codec needs to allocate some memory.
945
 
 *
946
 
 * @return          PJ_SUCCESS on success.
947
 
 */
948
 
PJ_INLINE(pj_status_t) pjmedia_codec_init( pjmedia_codec *codec,
949
 
                                           pj_pool_t *pool )
950
 
{
951
 
    return (*codec->op->init)(codec, pool);
952
 
}
953
 
 
954
 
 
955
 
/**
956
 
 * Open the codec and initialize with the specified parameter.
957
 
 * Upon successful initialization, the codec may modify the parameter
958
 
 * and fills in the unspecified values (such as enc_ptime, when
959
 
 * encoder ptime is different than decoder ptime).
960
 
 *
961
 
 * @param codec     The codec instance.
962
 
 * @param param     Codec initialization parameter.
963
 
 *
964
 
 * @return          PJ_SUCCESS on success.
965
 
 */
966
 
PJ_INLINE(pj_status_t) pjmedia_codec_open( pjmedia_codec *codec,
967
 
                                           pjmedia_codec_param *param )
968
 
{
969
 
    return (*codec->op->open)(codec, param);
970
 
}
971
 
 
972
 
 
973
 
/**
974
 
 * Close and shutdown codec, releasing all resources allocated by
975
 
 * this codec, if any.
976
 
 *
977
 
 * @param codec     The codec instance.
978
 
 *
979
 
 * @return          PJ_SUCCESS on success.
980
 
 */
981
 
PJ_INLINE(pj_status_t) pjmedia_codec_close( pjmedia_codec *codec )
982
 
{
983
 
    return (*codec->op->close)(codec);
984
 
}
985
 
 
986
 
 
987
 
/**
988
 
 * Modify the codec parameter after the codec is open.
989
 
 * Note that not all codec parameters can be modified during run-time.
990
 
 * When the parameter cannot be changed, this function will return
991
 
 * non-PJ_SUCCESS, and the original parameters will not be changed.
992
 
 *
993
 
 * Application can expect changing trivial codec settings such as
994
 
 * changing VAD setting to succeed.
995
 
 *
996
 
 * @param codec     The codec instance.
997
 
 * @param param     The new codec parameter.
998
 
 *
999
 
 * @return          PJ_SUCCESS on success.
1000
 
 */
1001
 
PJ_INLINE(pj_status_t) pjmedia_codec_modify(pjmedia_codec *codec,
1002
 
                                            const pjmedia_codec_param *param)
1003
 
{
1004
 
    return (*codec->op->modify)(codec, param);
1005
 
}
1006
 
 
1007
 
 
1008
 
/**
1009
 
 * Instruct the codec to inspect the specified payload/packet and
1010
 
 * split the packet into individual base frames. Each output frames will
1011
 
 * have ptime that is equal to basic frame ptime (i.e. the value of
1012
 
 * info.frm_ptime in #pjmedia_codec_param).
1013
 
 *
1014
 
 * @param codec     The codec instance
1015
 
 * @param pkt       The input packet.
1016
 
 * @param pkt_size  Size of the packet.
1017
 
 * @param timestamp The timestamp of the first sample in the packet.
1018
 
 * @param frame_cnt On input, specifies the maximum number of frames
1019
 
 *                  in the array. On output, the codec must fill
1020
 
 *                  with number of frames detected in the packet.
1021
 
 * @param frames    On output, specifies the frames that have been
1022
 
 *                  detected in the packet.
1023
 
 *
1024
 
 * @return          PJ_SUCCESS on success.
1025
 
 */
1026
 
PJ_INLINE(pj_status_t) pjmedia_codec_parse( pjmedia_codec *codec,
1027
 
                                            void *pkt,
1028
 
                                            pj_size_t pkt_size,
1029
 
                                            const pj_timestamp *timestamp,
1030
 
                                            unsigned *frame_cnt,
1031
 
                                            pjmedia_frame frames[] )
1032
 
{
1033
 
    return (*codec->op->parse)(codec, pkt, pkt_size, timestamp,
1034
 
                               frame_cnt, frames);
1035
 
}
1036
 
 
1037
 
 
1038
 
/**
1039
 
 * Instruct the codec to encode the specified input frame. The input
1040
 
 * PCM samples MUST have ptime that is multiplication of base frame
1041
 
 * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
1042
 
 *
1043
 
 * @param codec         The codec instance.
1044
 
 * @param input         The input frame.
1045
 
 * @param out_size      The length of buffer in the output frame.
1046
 
 * @param output        The output frame.
1047
 
 *
1048
 
 * @return              PJ_SUCCESS on success;
1049
 
 */
1050
 
PJ_INLINE(pj_status_t) pjmedia_codec_encode(
1051
 
                                        pjmedia_codec *codec,
1052
 
                                        const struct pjmedia_frame *input,
1053
 
                                        unsigned out_size,
1054
 
                                        struct pjmedia_frame *output )
1055
 
{
1056
 
    return (*codec->op->encode)(codec, input, out_size, output);
1057
 
}
1058
 
 
1059
 
 
1060
 
/**
1061
 
 * Instruct the codec to decode the specified input frame. The input
1062
 
 * frame MUST have ptime that is exactly equal to base frame
1063
 
 * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
1064
 
 * Application can achieve this by parsing the packet into base
1065
 
 * frames before decoding each frame.
1066
 
 *
1067
 
 * @param codec         The codec instance.
1068
 
 * @param input         The input frame.
1069
 
 * @param out_size      The length of buffer in the output frame.
1070
 
 * @param output        The output frame.
1071
 
 *
1072
 
 * @return              PJ_SUCCESS on success;
1073
 
 */
1074
 
PJ_INLINE(pj_status_t) pjmedia_codec_decode(
1075
 
                                        pjmedia_codec *codec,
1076
 
                                        const struct pjmedia_frame *input,
1077
 
                                        unsigned out_size,
1078
 
                                        struct pjmedia_frame *output )
1079
 
{
1080
 
    return (*codec->op->decode)(codec, input, out_size, output);
1081
 
}
1082
 
 
1083
 
 
1084
 
/**
1085
 
 * Instruct the codec to recover a missing frame.
1086
 
 *
1087
 
 * @param codec         The codec instance.
1088
 
 * @param out_size      The length of buffer in the output frame.
1089
 
 * @param output        The output frame where generated signal
1090
 
 *                      will be placed.
1091
 
 *
1092
 
 * @return              PJ_SUCCESS on success;
1093
 
 */
1094
 
PJ_INLINE(pj_status_t) pjmedia_codec_recover( pjmedia_codec *codec,
1095
 
                                              unsigned out_size,
1096
 
                                              struct pjmedia_frame *output )
1097
 
{
1098
 
    if (codec->op && codec->op->recover)
1099
 
        return (*codec->op->recover)(codec, out_size, output);
1100
 
    else
1101
 
        return PJ_ENOTSUP;
1102
 
}
1103
 
 
1104
 
 
1105
 
/**
1106
 
 * @}
1107
 
 */
1108
 
 
1109
 
/**
1110
 
 * @defgroup PJMEDIA_CODEC_CODECS Supported codecs
1111
 
 * @ingroup PJMEDIA_CODEC
1112
 
 * @brief Documentation about individual codec supported by PJMEDIA
1113
 
 * @{
1114
 
 * Please see the APIs provided by the individual codecs below.
1115
 
 */
1116
 
/**
1117
 
 * @}
1118
 
 */
1119
 
 
1120
 
 
1121
 
 
1122
 
 
1123
 
PJ_END_DECL
1124
 
 
1125
 
 
1126
 
#endif  /* __PJMEDIA_CODEC_H__ */