/* 

 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)

 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 

 */

#ifndef __PJMEDIA_PORT_H__

#define __PJMEDIA_PORT_H__

/**

 * @file port.h

 * @brief Port interface declaration

 */

#include <pjmedia/clock.h>

#include <pjmedia/event.h>

#include <pjmedia/format.h>

#include <pjmedia/frame.h>

#include <pjmedia/signatures.h>

#include <pj/assert.h>

#include <pj/lock.h>

#include <pj/os.h>

/**

  @addtogroup PJMEDIA_PORT Media Ports Framework

  @{

  @section media_port_intro Media Port Concepts

  @subsection The Media Port

  A media port (represented with pjmedia_port "class") provides a generic

  and extensible framework for implementing media elements. Media element

  itself could be a media source, sink, or processing element. A media

  port interface basically has the following properties:

  - media port information (pjmedia_port_info) to describe the

  media port properties (sampling rate, number of channels, etc.),

  - optional pointer to function to acquire frames from the port (the

    <tt>get_frame() </tt> interface), which will be called by

    #pjmedia_port_get_frame() public API, and

  - optional pointer to function to store frames to the port (the

    <tt>put_frame()</tt> interface) which will be called by

    #pjmedia_port_put_frame() public API.

  The <tt>get_frame()</tt> and <tt>put_frame()</tt> interface of course

  would only need to be implemented if the media port emits and/or takes

  media frames respectively.

  Media ports are passive "objects". By default, there is no worker thread

  to run the media flow. Applications (or other PJMEDIA

  components, as explained in @ref PJMEDIA_PORT_CLOCK) must actively call

  #pjmedia_port_get_frame() or #pjmedia_port_put_frame() from/to the media

  port in order to retrieve/store media frames.

  Some media ports (such as @ref PJMEDIA_CONF and @ref PJMEDIA_RESAMPLE_PORT)

  may be interconnected with (or encapsulate) other port, to perform the

  combined task of the ports, while some

  others represent the ultimate source/sink termination for the media. 

  Interconnection means the upstream media port will call <tt>get_frame()</tt>

  and <tt>put_frame()</tt> to its downstream media port. For this to happen,

  the media ports need to have the same format, where format is defined as

  combination of sample format, clock rate, channel count, bits per sample,

  and samples per frame for audio media.

  @subsection port_clock_ex1 Example: Manual Resampling

  For example, suppose application wants to convert the sampling rate

  of one WAV file to another. In this case, application would create and

  arrange media ports connection as follows:

  \img{pjmedia/docs/sample-manual-resampling.jpg}

  Application would setup the media ports using the following pseudo-

  code:

  \code

      pjmedia_port *player, *resample, *writer;

      pj_status_t status;

      // Create the file player port.

      status = pjmedia_wav_player_port_create(pool, 

                                              "Input.WAV",          // file name

                                              20,                   // ptime.

                                              PJMEDIA_FILE_NO_LOOP, // flags

                                              0,                    // buffer size

                                              NULL,                 // user data.

                                              &player );

      PJ_ASSERT_RETURN(status==PJ_SUCCESS, PJ_SUCCESS);

      // Create the resample port with specifying the target sampling rate, 

      // and with the file port as the source. This will effectively

      // connect the resample port with the player port.

      status = pjmedia_resample_port_create( pool, player, 8000, 

                                             0, &resample);

      PJ_ASSERT_RETURN(status==PJ_SUCCESS, PJ_SUCCESS);

      // Create the file writer, specifying the resample port's configuration

      // as the WAV parameters.

      status pjmedia_wav_writer_port_create(pool, 

                                            "Output.WAV",  // file name.

                                            resample->info.clock_rate,

                                            resample->info.channel_count,

                                            resample->info.samples_per_frame,

                                            resample->info.bits_per_sample,

                                            0,          // flags

                                            0,          // buffer size

                                            NULL,       // user data.

                                            &writer);

  \endcode

  After the ports have been set up, application can perform the conversion

  process by running this loop:

  \code

        pj_int16_t samplebuf[MAX_FRAME];

        while (1) {

            pjmedia_frame frame;

            pj_status_t status;

            frame.buf = samplebuf;

            frame.size = sizeof(samplebuf);

            // Get the frame from resample port.

            status = pjmedia_port_get_frame(resample, &frame);

            if (status != PJ_SUCCESS || frame.type == PJMEDIA_FRAME_TYPE_NONE) {

                // End-of-file, end the conversion.

                break;

            }

            // Put the frame to write port.

            status = pjmedia_port_put_frame(writer, &frame);

            if (status != PJ_SUCCESS) {

                // Error in writing the file.

                break;

            }

        }

  \endcode

  For the sake of completeness, after the resampling process is done, 

  application would need to destroy the ports:

  \code

        // Note: by default, destroying resample port will destroy the

        //       the downstream port too.

        pjmedia_port_destroy(resample);

        pjmedia_port_destroy(writer);

  \endcode

  The above steps are okay for our simple purpose of changing file's sampling

  rate. But for other purposes, the process of reading and writing frames

  need to be done in timely manner (for example, sending RTP packets to

  remote stream). And more over, as the application's scope goes bigger,

  the same pattern of manually reading/writing frames comes up more and more often,

  thus perhaps it would be better if PJMEDIA provides mechanism to 

  automate this process.

  And indeed PJMEDIA does provide such mechanism, which is described in 

  @ref PJMEDIA_PORT_CLOCK section.

  @subsection media_port_autom Automating Media Flow

  PJMEDIA provides few mechanisms to make media flows automatically

  among media ports. This concept is described in @ref PJMEDIA_PORT_CLOCK 

  section.

*/

PJ_BEGIN_DECL

/* Since media port's callback is called synchronously and has a return value,

 * it can introduce a deadlock when a mutex is held before calling it.

 * To prevent this, media ports' set_eof_cb() and set_cb() functions have

 * been deprecated and replaced by set_eof_cb2() and set_cb2(), which

 * will call the callback asynchronously without expecting any return value.

 *

 * See also https://github.com/pjsip/pjproject/issues/2251.

 */

#ifndef DEPRECATED_FOR_TICKET_2251

#  define DEPRECATED_FOR_TICKET_2251    0

#endif

/**

 * Create 32bit port signature from ASCII characters.

 */

#define PJMEDIA_PORT_SIG(a,b,c,d)               PJMEDIA_OBJ_SIG(a,b,c,d)

/**

 * Port operation setting.

 */

typedef enum pjmedia_port_op

{

    /** 

     * No change to the port TX or RX settings.

     */

    PJMEDIA_PORT_NO_CHANGE,

    /**

     * TX or RX is disabled from the port. It means get_frame() or

     * put_frame() WILL NOT be called for this port.

     */

    PJMEDIA_PORT_DISABLE,

    /**

     * TX or RX is muted, which means that get_frame() or put_frame()

     * will still be called, but the audio frame is discarded.

     */

    PJMEDIA_PORT_MUTE,

    /**

     * Enable TX and RX to/from this port.

     */

    PJMEDIA_PORT_ENABLE

} pjmedia_port_op;

/**

 * Port info.

 */

typedef struct pjmedia_port_info

{

    pj_str_t        name;               /**< Port name.                     */

    pj_uint32_t     signature;          /**< Port signature.                */

    pjmedia_dir     dir;                /**< Port direction.                */

    pjmedia_format  fmt;                /**< Format.                        */

} pjmedia_port_info;

/**

 * Utility to retrieve audio clock rate/sampling rate value from

 * pjmedia_port_info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Audio clock rate.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_SRATE(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return pia->fmt.det.aud.clock_rate;

}

/**

 * Utility to retrieve audio channel count value from pjmedia_port_info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Audio channel count.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_CCNT(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return pia->fmt.det.aud.channel_count;

}

/**

 * Utility to retrieve audio bits per sample value from pjmedia_port_info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Number of bits per sample.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_BITS(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return pia->fmt.det.aud.bits_per_sample;

}

/**

 * Utility to retrieve audio frame interval (ptime) value from

 * pjmedia_port_info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Frame interval in msec.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_PTIME(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return pia->fmt.det.aud.frame_time_usec / 1000;

}

/**

 * This is a utility routine to retrieve the audio samples_per_frame value

 * from port info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Samples per frame value.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_SPF(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return PJMEDIA_AFD_SPF(&pia->fmt.det.aud);

}

/**

 * This is a utility routine to retrieve the average bitrate value

 * from port info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Bitrate, in bits per second.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_AVG_BPS(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return pia->fmt.det.aud.avg_bps;

}

/**

 * This is a utility routine to retrieve the maximum bitrate value

 * from port info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Bitrate, in bits per second.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_MAX_BPS(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return pia->fmt.det.aud.max_bps;

}

/**

 * This is a utility routine to retrieve the average audio frame size value

 * from pjmedia_port_info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Frame size in bytes.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_AVG_FSZ(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return PJMEDIA_AFD_AVG_FSZ(&pia->fmt.det.aud);

}

/**

 * Utility to retrieve audio frame size from maximum bitrate from

 * pjmedia_port_info.

 *

 * @param pia           Pointer to port info containing audio format.

 * @return              Frame size in bytes.

 */

PJ_INLINE(unsigned) PJMEDIA_PIA_MAX_FSZ(const pjmedia_port_info *pia)

{

    pj_assert(pia->fmt.type==PJMEDIA_TYPE_AUDIO &&

              pia->fmt.detail_type==PJMEDIA_FORMAT_DETAIL_AUDIO);

    return PJMEDIA_AFD_MAX_FSZ(&pia->fmt.det.aud);

}

/**

 * Port interface.

 */

typedef struct pjmedia_port

{

    pjmedia_port_info    info;              /**< Port information.  */

    /** Port data can be used by the port creator to attach arbitrary

     *  value to be associated with the port.

     */

    struct port_data {

        void            *pdata;             /**< Pointer data.      */

        long             ldata;             /**< Long data.         */

    } port_data;

    /**

     * Group lock.

     *

     * This is optional, but if this port is registered to the audio/video

     * conference bridge, the bridge will create one if the port has none.

     */

    pj_grp_lock_t       *grp_lock;

    /**

     * Get clock source.

     * This should only be called by #pjmedia_port_get_clock_src().

     */

    pjmedia_clock_src* (*get_clock_src)(struct pjmedia_port *this_port,

                                        pjmedia_dir dir);

    /**

     * Sink interface. 

     * This should only be called by #pjmedia_port_put_frame().

     */

    pj_status_t (*put_frame)(struct pjmedia_port *this_port, 

                             pjmedia_frame *frame);

    /**

     * Source interface. 

     * This should only be called by #pjmedia_port_get_frame().

     */

    pj_status_t (*get_frame)(struct pjmedia_port *this_port, 

                             pjmedia_frame *frame);

    /**

     * Destructor.

     * This should only be called by #pjmedia_port_destroy().

     */

    pj_status_t (*on_destroy)(struct pjmedia_port *this_port);

} pjmedia_port;

/**

 * This is an auxiliary function to initialize port info for

 * ports which deal with PCM audio.

 *

 * @param info              The port info to be initialized.

 * @param name              Port name.

 * @param signature         Port signature.

 * @param clock_rate        Port's clock rate.

 * @param channel_count     Number of channels.

 * @param bits_per_sample   Bits per sample.

 * @param samples_per_frame Number of samples per frame.

 *

 * @return                  PJ_SUCCESS on success.

 */

PJ_DECL(pj_status_t) pjmedia_port_info_init( pjmedia_port_info *info,

                                             const pj_str_t *name,

                                             unsigned signature,

                                             unsigned clock_rate,

                                             unsigned channel_count,

                                             unsigned bits_per_sample,

                                             unsigned samples_per_frame);

/**

 * This is an auxiliary function to initialize port info for

 * ports which deal with PCM audio.

 *

 * @param info              The port info to be initialized.

 * @param name              Port name.

 * @param signature         Port signature.

 * @param dir               Port's direction.

 * @param fmt               Port's media format.

 *

 * @return                  PJ_SUCCESS on success.

 */

PJ_DECL(pj_status_t) pjmedia_port_info_init2(pjmedia_port_info *info,

                                             const pj_str_t *name,

                                             unsigned signature,

                                             pjmedia_dir dir,

                                             const pjmedia_format *fmt);

/**

 * Get a clock source from the port.

 *

 * @param port      The media port.

 * @param dir       Media port's direction.

 *

 * @return          The clock source or NULL if clock source is not present

 *                  in the port.

 */

PJ_DECL(pjmedia_clock_src *) pjmedia_port_get_clock_src( pjmedia_port *port,

                                                         pjmedia_dir dir );

/**

 * Get a frame from the port (and subsequent downstream ports).

 *

 * @param port      The media port.

 * @param frame     Frame to store samples.

 *

 * @return          PJ_SUCCESS on success, or the appropriate error code.

 */

PJ_DECL(pj_status_t) pjmedia_port_get_frame( pjmedia_port *port,

                                             pjmedia_frame *frame );

/**

 * Put a frame to the port (and subsequent downstream ports).

 *

 * @param port      The media port.

 * @param frame     Frame to the put to the port.

 *

 * @return          PJ_SUCCESS on success, or the appropriate error code.

 */

PJ_DECL(pj_status_t) pjmedia_port_put_frame( pjmedia_port *port,

                                             pjmedia_frame *frame );

/**

 * Destroy port (and subsequent downstream ports).

 *

 * Note that if the port has group lock, instead of destroying the port

 * immediately, this function will just decrease the reference counter.

 *

 * @param port      The media port.

 *

 * @return          PJ_SUCCESS on success, or the appropriate error code.

 */

PJ_DECL(pj_status_t) pjmedia_port_destroy( pjmedia_port *port );

/*

 *******************************************************************

 * Helper functions.

 *******************************************************************

 */

/**

 * This is a helper function to initialize the port's group lock. This

 * function will create a group lock if NULL is passed, initialize the group

 * lock by adding the port's destructor to the group lock handler list, and

 * increment the reference counter.

 *

 * Normally this function is only called by media port implementation,

 * application should never call this function.

 *

 * This function will check whether the port implements on_destroy(),

 * because when working with conference bridge, a port is required to manage

 * its lifetime via group lock (e.g: initialized by this function),

 * so basically it must use its own pool and the pool is normally

 * released from its on_destroy().

 *

 * Also note that this function will add a group lock destroy handler

 * that calls port's on_destroy(), so port implementation can release

 * its resources from on_destroy() as usual.

 *

 * @param port              The pjmedia port to be initialized.

 * @param pool              The pool, this can be a temporary pool as

 *                          group lock will create and use its internal pool.

 * @param glock             The group lock, or create a new one if NULL.

 *

 * @return                  PJ_SUCCESS on success, PJ_EEXISTS if group lock

 *                          is already initialized, or the other appropriate

 *                          error code.

 */

PJ_DECL(pj_status_t) pjmedia_port_init_grp_lock( pjmedia_port *port,

                                                 pj_pool_t *pool,

                                                 pj_grp_lock_t *glock );

/**

 * This is a helper function to increase the port reference counter.

 *

 * @param port              The PJMEDIA port.

 *

 * @return                  PJ_SUCCESS on success.

 */

PJ_DECL(pj_status_t) pjmedia_port_add_ref( pjmedia_port *port );

/**

 * This is a helper function to decrease the port reference counter.

 *

 * @param port              The PJMEDIA port.

 *

 * @return                  PJ_SUCCESS on success.

 */

PJ_DECL(pj_status_t) pjmedia_port_dec_ref( pjmedia_port *port );

/**

 * This is a helper function to add port destructor handler.

 *

 * Application can use this function to schedule its resource release.

 * Note that application cannot release the resources related to the port,

 * e.g: memory pool (custom ports that do not use its own pool),

 * immediately after removing the port from the conference bridge

 * as the port removal is done asynchronously.

 *

 * Usually this function is called after adding the port to the conference

 * bridge.

 *

 * @param port              The PJMEDIA port.

 * @param member            A pointer to be passed to the handler.

 * @param handler           The destroy handler.

 *

 * @return                  PJ_SUCCESS on success.

 */

PJ_DECL(pj_status_t) pjmedia_port_add_destroy_handler(

                                            pjmedia_port* port,

                                            void *member,

                                            pj_grp_lock_handler handler);

/**

 * This is a helper function to remove previously registered

 * destructor handler.

 *

 * @param port              The PJMEDIA port.

 * @param member            A pointer to be passed to the handler.

 * @param handler           The destroy handler.

 *

 * @return                  PJ_SUCCESS on success.

 */

PJ_DECL(pj_status_t) pjmedia_port_del_destroy_handler(

                                            pjmedia_port* port,

                                            void *member,

                                            pj_grp_lock_handler handler);

PJ_END_DECL

/**

 * @}

 */

#endif  /* __PJMEDIA_PORT_H__ */