voice-gateway-service/pjproject/pjmedia/include/pjmedia/rtcp_xr.h

/* 
 * 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_RTCP_XR_H__
#define __PJMEDIA_RTCP_XR_H__

/**
 * @file rtcp_xr.h
 * @brief RTCP XR implementation.
 */

#include <pjmedia/types.h>
#include <pj/math.h>


PJ_BEGIN_DECL


/**
 * @defgroup PJMED_RTCP_XR RTCP Extended Report (XR) - RFC 3611
 * @ingroup PJMEDIA_SESSION
 * @brief RTCP XR extension to RTCP session
 * @{
 *
 * PJMEDIA implements subsets of RTCP XR specification (RFC 3611) to monitor
 * the quality of the real-time media (audio/video) transmission.
 */

/**
 * Enumeration of report types of RTCP XR. Useful for user to enable varying
 * combinations of RTCP XR report blocks.
 */
typedef enum {
    PJMEDIA_RTCP_XR_LOSS_RLE        = (1 << 0),
    PJMEDIA_RTCP_XR_DUP_RLE         = (1 << 1),
    PJMEDIA_RTCP_XR_RCPT_TIMES      = (1 << 2),
    PJMEDIA_RTCP_XR_RR_TIME         = (1 << 3),
    PJMEDIA_RTCP_XR_DLRR            = (1 << 4),
    PJMEDIA_RTCP_XR_STATS           = (1 << 5),
    PJMEDIA_RTCP_XR_VOIP_METRICS    = (1 << 6)
} pjmedia_rtcp_xr_type;

/**
 * Enumeration of info need to be updated manually to RTCP XR. Most info
 * could be updated automatically each time RTP received.
 */
typedef enum {
    PJMEDIA_RTCP_XR_INFO_SIGNAL_LVL = 1,
    PJMEDIA_RTCP_XR_INFO_NOISE_LVL  = 2,
    PJMEDIA_RTCP_XR_INFO_RERL       = 3,
    PJMEDIA_RTCP_XR_INFO_R_FACTOR   = 4,
    PJMEDIA_RTCP_XR_INFO_MOS_LQ     = 5,
    PJMEDIA_RTCP_XR_INFO_MOS_CQ     = 6,
    PJMEDIA_RTCP_XR_INFO_CONF_PLC   = 7,
    PJMEDIA_RTCP_XR_INFO_CONF_JBA   = 8,
    PJMEDIA_RTCP_XR_INFO_CONF_JBR   = 9,
    PJMEDIA_RTCP_XR_INFO_JB_NOM     = 10,
    PJMEDIA_RTCP_XR_INFO_JB_MAX     = 11,
    PJMEDIA_RTCP_XR_INFO_JB_ABS_MAX = 12
} pjmedia_rtcp_xr_info;

/**
 * Enumeration of PLC types definitions for RTCP XR report.
 */
typedef enum {
    PJMEDIA_RTCP_XR_PLC_UNK         = 0,
    PJMEDIA_RTCP_XR_PLC_DIS         = 1,
    PJMEDIA_RTCP_XR_PLC_ENH         = 2,
    PJMEDIA_RTCP_XR_PLC_STD         = 3
} pjmedia_rtcp_xr_plc_type;

/**
 * Enumeration of jitter buffer types definitions for RTCP XR report.
 */
typedef enum {
    PJMEDIA_RTCP_XR_JB_UNKNOWN      = 0,
    PJMEDIA_RTCP_XR_JB_FIXED        = 2,
    PJMEDIA_RTCP_XR_JB_ADAPTIVE     = 3
} pjmedia_rtcp_xr_jb_type;


#pragma pack(1)

/**
 * This type declares RTCP XR Report Header.
 */
typedef struct pjmedia_rtcp_xr_rb_header
{
    pj_uint8_t           bt;            /**< Block type.                */
    pj_uint8_t           specific;      /**< Block specific data.       */
    pj_uint16_t          length;        /**< Block length.              */
} pjmedia_rtcp_xr_rb_header;

/**
 * This type declares RTCP XR Receiver Reference Time Report Block.
 */
typedef struct pjmedia_rtcp_xr_rb_rr_time
{
    pjmedia_rtcp_xr_rb_header header;   /**< Block header.              */
    pj_uint32_t          ntp_sec;       /**< NTP time, seconds part.    */
    pj_uint32_t          ntp_frac;      /**< NTP time, fractions part.  */
} pjmedia_rtcp_xr_rb_rr_time;


/**
 * This type declares RTCP XR DLRR Report Sub-block
 */
typedef struct pjmedia_rtcp_xr_rb_dlrr_item
{
    pj_uint32_t          ssrc;          /**< receiver SSRC              */
    pj_uint32_t          lrr;           /**< last receiver report       */
    pj_uint32_t          dlrr;          /**< delay since last receiver
                                             report                     */
} pjmedia_rtcp_xr_rb_dlrr_item;

/**
 * This type declares RTCP XR DLRR Report Block
 */
typedef struct pjmedia_rtcp_xr_rb_dlrr
{
    pjmedia_rtcp_xr_rb_header header;   /**< Block header.              */
    pjmedia_rtcp_xr_rb_dlrr_item item;  /**< Block contents, 
                                             variable length list       */
} pjmedia_rtcp_xr_rb_dlrr;

/**
 * This type declares RTCP XR Statistics Summary Report Block
 */
typedef struct pjmedia_rtcp_xr_rb_stats
{
    pjmedia_rtcp_xr_rb_header header;   /**< Block header.                   */
    pj_uint32_t          ssrc;          /**< Receiver SSRC                   */
    pj_uint16_t          begin_seq;     /**< Begin RTP sequence reported     */
    pj_uint16_t          end_seq;       /**< End RTP sequence reported       */
    pj_uint32_t          lost;          /**< Number of packet lost in this 
                                             interval  */
    pj_uint32_t          dup;           /**< Number of duplicated packet in 
                                             this interval */
    pj_uint32_t          jitter_min;    /**< Minimum jitter in this interval */
    pj_uint32_t          jitter_max;    /**< Maximum jitter in this interval */
    pj_uint32_t          jitter_mean;   /**< Average jitter in this interval */
    pj_uint32_t          jitter_dev;    /**< Jitter deviation in this 
                                             interval */
    pj_uint32_t          toh_min:8;     /**< Minimum ToH in this interval    */
    pj_uint32_t          toh_max:8;     /**< Maximum ToH in this interval    */
    pj_uint32_t          toh_mean:8;    /**< Average ToH in this interval    */
    pj_uint32_t          toh_dev:8;     /**< ToH deviation in this interval  */
} pjmedia_rtcp_xr_rb_stats;

/**
 * This type declares RTCP XR VoIP Metrics Report Block
 */
typedef struct pjmedia_rtcp_xr_rb_voip_mtc
{
    pjmedia_rtcp_xr_rb_header header;   /**< Block header.              */
    pj_uint32_t          ssrc;          /**< Receiver SSRC              */
    pj_uint8_t           loss_rate;     /**< Packet loss rate           */
    pj_uint8_t           discard_rate;  /**< Packet discarded rate      */
    pj_uint8_t           burst_den;     /**< Burst density              */
    pj_uint8_t           gap_den;       /**< Gap density                */
    pj_uint16_t          burst_dur;     /**< Burst duration             */
    pj_uint16_t          gap_dur;       /**< Gap duration               */
    pj_uint16_t          rnd_trip_delay;/**< Round trip delay           */
    pj_uint16_t          end_sys_delay; /**< End system delay           */
    pj_uint8_t           signal_lvl;    /**< Signal level               */
    pj_uint8_t           noise_lvl;     /**< Noise level                */
    pj_uint8_t           rerl;          /**< Residual Echo Return Loss  */
    pj_uint8_t           gmin;          /**< The gap threshold          */
    pj_uint8_t           r_factor;      /**< Voice quality metric carried
                                             over this RTP session      */
    pj_uint8_t           ext_r_factor;  /**< Voice quality metric carried 
                                             outside of this RTP session*/
    pj_uint8_t           mos_lq;        /**< Mean Opinion Score for 
                                             Listening Quality          */
    pj_uint8_t           mos_cq;        /**< Mean Opinion Score for 
                                             Conversation Quality       */
    pj_uint8_t           rx_config;     /**< Receiver configuration     */
    pj_uint8_t           reserved2;     /**< Not used                   */
    pj_uint16_t          jb_nom;        /**< Current delay by jitter
                                             buffer                     */
    pj_uint16_t          jb_max;        /**< Maximum delay by jitter
                                             buffer                     */
    pj_uint16_t          jb_abs_max;    /**< Maximum possible delay by
                                             jitter buffer              */
} pjmedia_rtcp_xr_rb_voip_mtc;


/**
 * Constant of RTCP-XR content size.
 */
#define PJMEDIA_RTCP_XR_BUF_SIZE \
    sizeof(pjmedia_rtcp_xr_rb_rr_time) + \
    sizeof(pjmedia_rtcp_xr_rb_dlrr) + \
    sizeof(pjmedia_rtcp_xr_rb_stats) + \
    sizeof(pjmedia_rtcp_xr_rb_voip_mtc)


/**
 * This structure declares RTCP XR (Extended Report) packet.
 */
typedef struct pjmedia_rtcp_xr_pkt
{
    struct {
#if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
        unsigned         version:2;     /**< packet type            */
        unsigned         p:1;           /**< padding flag           */
        unsigned         count:5;       /**< varies by payload type */
        unsigned         pt:8;          /**< payload type           */
#else
        unsigned         count:5;       /**< varies by payload type */
        unsigned         p:1;           /**< padding flag           */
        unsigned         version:2;     /**< packet type            */
        unsigned         pt:8;          /**< payload type           */
#endif
        unsigned         length:16;     /**< packet length          */
        pj_uint32_t      ssrc;          /**< SSRC identification    */
    } common;

    pj_int8_t            buf[PJMEDIA_RTCP_XR_BUF_SIZE];
                                        /**< Content buffer   */
} pjmedia_rtcp_xr_pkt;

#pragma pack()


/**
 * This structure describes RTCP XR statitic.
 */
typedef struct pjmedia_rtcp_xr_stream_stat
{
    struct {
        pj_time_val         update;     /**< Time of last update.           */

        pj_uint32_t         begin_seq;  /**< Begin # seq of this interval.  */
        pj_uint32_t         end_seq;    /**< End # seq of this interval.    */
        unsigned            count;      /**< Number of packets.             */

        /**
         * Flags represent whether the such report is valid/updated
         */
        unsigned            l:1;        /**< Lost flag                      */
        unsigned            d:1;        /**< Duplicated flag                */
        unsigned            j:1;        /**< Jitter flag                    */
        unsigned            t:2;        /**< TTL or Hop Limit, 
                                             0=none, 1=TTL, 2=HL            */

        unsigned            lost;       /**< Number of packets lost         */
        unsigned            dup;        /**< Number of duplicated packets   */
        pj_math_stat        jitter;     /**< Jitter statistics (in usec)    */
        pj_math_stat        toh;        /**< TTL of hop limit statistics.   */
    } stat_sum;

    struct {
        pj_time_val         update;         /**< Time of last update.       */

        pj_uint8_t          loss_rate;      /**< Packet loss rate           */
        pj_uint8_t          discard_rate;   /**< Packet discarded rate      */
        pj_uint8_t          burst_den;      /**< Burst density              */
        pj_uint8_t          gap_den;        /**< Gap density                */
        pj_uint16_t         burst_dur;      /**< Burst duration             */
        pj_uint16_t         gap_dur;        /**< Gap duration               */
        pj_uint16_t         rnd_trip_delay; /**< Round trip delay           */
        pj_uint16_t         end_sys_delay;  /**< End system delay           */
        pj_int8_t           signal_lvl;     /**< Signal level               */
        pj_int8_t           noise_lvl;      /**< Noise level                */
        pj_uint8_t          rerl;           /**< Residual Echo Return Loss  */
        pj_uint8_t          gmin;           /**< The gap threshold          */
        pj_uint8_t          r_factor;       /**< Voice quality metric carried
                                                 over this RTP session      */
        pj_uint8_t          ext_r_factor;   /**< Voice quality metric carried 
                                                 outside of this RTP session*/
        pj_uint8_t          mos_lq;         /**< Mean Opinion Score for 
                                                 Listening Quality          */
        pj_uint8_t          mos_cq;         /**< Mean Opinion Score for 
                                                 Conversation Quality       */
        pj_uint8_t          rx_config;      /**< Receiver configuration     */
        pj_uint16_t         jb_nom;         /**< Current delay by jitter
                                                 buffer                     */
        pj_uint16_t         jb_max;         /**< Maximum delay by jitter
                                                 buffer                     */
        pj_uint16_t         jb_abs_max;     /**< Maximum possible delay by
                                                 jitter buffer              */
    } voip_mtc;

} pjmedia_rtcp_xr_stream_stat;

typedef struct pjmedia_rtcp_xr_stat
{
    pjmedia_rtcp_xr_stream_stat  rx;  /**< Decoding direction statistics.   */
    pjmedia_rtcp_xr_stream_stat  tx;  /**< Encoding direction statistics.   */
    pj_math_stat                 rtt; /**< Round-trip delay stat (in usec) 
                                           the value is calculated from 
                                           receiver side.                   */
} pjmedia_rtcp_xr_stat;

/**
 * Forward declaration of RTCP session
 */
struct pjmedia_rtcp_session;

/**
 * RTCP session is used to monitor the RTP session of one endpoint. There
 * should only be one RTCP session for a bidirectional RTP streams.
 */
struct pjmedia_rtcp_xr_session
{
    char                   *name;       /**< Name identification.           */
    pjmedia_rtcp_xr_pkt     pkt;        /**< Cached RTCP XR packet.         */

    pj_uint32_t             rx_lrr;     /**< NTP ts in last RR received.    */
    pj_timestamp            rx_lrr_time;/**< Time when last RR is received. */
    pj_uint32_t             rx_last_rr; /**< # pkt received since last 
                                             sending RR time.               */

    pjmedia_rtcp_xr_stat    stat;       /**< RTCP XR statistics.            */

    /* The reference sequence number is an extended sequence number
     * that serves as the basis for determining whether a new 16 bit
     * sequence number comes earlier or later in the 32 bit sequence
     * space.
     */
    pj_uint32_t             src_ref_seq;
    pj_bool_t               uninitialized_src_ref_seq;

    /* This structure contains variables needed for calculating 
     * burst metrics.
     */
    struct {
        pj_uint32_t         pkt;
        pj_uint32_t         lost;
        pj_uint32_t         loss_count;
        pj_uint32_t         discard_count;
        pj_uint32_t         c11;
        pj_uint32_t         c13;
        pj_uint32_t         c14;
        pj_uint32_t         c22;
        pj_uint32_t         c23;
        pj_uint32_t         c33;
    } voip_mtc_stat;

    unsigned ptime;                     /**< Packet time.                   */
    unsigned frames_per_packet;         /**< # frames per packet.           */

    struct pjmedia_rtcp_session *rtcp_session;
                                        /**< Parent/RTCP session.           */
};

typedef struct pjmedia_rtcp_xr_session pjmedia_rtcp_xr_session;

/**
 * Build an RTCP XR packet which contains one or more RTCP XR report blocks.
 * There are seven report types as defined in RFC 3611.
 *
 * @param session   The RTCP XR session.
 * @param rpt_types Report types to be included in the packet, report types
 *                  are defined in pjmedia_rtcp_xr_type, set this to zero
 *                  will make this function build all reports appropriately.
 * @param rtcp_pkt  Upon return, it will contain pointer to the RTCP XR packet.
 * @param len       Upon return, it will indicate the size of the generated 
 *                  RTCP XR packet.
 */
PJ_DECL(void) pjmedia_rtcp_build_rtcp_xr( pjmedia_rtcp_xr_session *session,
                                          unsigned rpt_types,
                                          void **rtcp_pkt, int *len);

/**
 * Call this function to manually update some info needed by RTCP XR to 
 * generate report which could not be populated directly when receiving
 * RTP.
 *
 * @param session   The RTCP XR session.
 * @param info      Info type to be updated, @see pjmedia_rtcp_xr_info.
 * @param val       Value.
 */
PJ_DECL(pj_status_t) pjmedia_rtcp_xr_update_info(
                                          pjmedia_rtcp_xr_session *session,
                                          unsigned info,
                                          pj_int32_t val);

/*
 * Private APIs:
 */

/**
 * This function is called internally by RTCP session when RTCP XR is enabled
 * to initialize the RTCP XR session.
 *
 * @param session   RTCP XR session.
 * @param r_session RTCP session.
 * @param gmin      Gmin value (defined in RFC 3611), set to 0 for default (16).
 * @param frames_per_packet
                    Number of frames per packet.
 */
void pjmedia_rtcp_xr_init( pjmedia_rtcp_xr_session *session, 
                           struct pjmedia_rtcp_session *r_session,
                           pj_uint8_t gmin,
                           unsigned frames_per_packet);

/**
 * This function is called internally by RTCP session to destroy 
 * the RTCP XR session.
 *
 * @param session   RTCP XR session.
 */
void pjmedia_rtcp_xr_fini( pjmedia_rtcp_xr_session *session );

/**
 * This function is called internally by RTCP session when it receives 
 * incoming RTCP XR packets.
 *
 * @param session   RTCP XR session.
 * @param rtcp_pkt  The received RTCP XR packet.
 * @param size      Size of the incoming packet.
 */
void pjmedia_rtcp_xr_rx_rtcp_xr( pjmedia_rtcp_xr_session *session,
                                 const void *rtcp_pkt,
                                 pj_size_t size);

/**
 * This function is called internally by RTCP session whenever an RTP packet
 * is received or lost to let the RTCP XR session update its statistics.
 * Data passed to this function is a result of analyzation by RTCP and the
 * jitter buffer. Whenever some info is available, the value should be zero
 * or more (no negative info), otherwise if info is not available the info
 * should be -1 so no update will be done for this info in the RTCP XR session.
 *
 * @param session   RTCP XR session.
 * @param seq       Sequence number of RTP packet.
 * @param lost      Info if this packet is lost. 
 * @param dup       Info if this packet is a duplication. 
 * @param discarded Info if this packet is discarded 
 *                  (not because of duplication).
 * @param jitter    Info jitter of this packet.
 * @param toh       Info Time To Live or Hops Limit of this packet.
 * @param toh_ipv4  Set PJ_TRUE if packet is transported over IPv4.
 */
void pjmedia_rtcp_xr_rx_rtp( pjmedia_rtcp_xr_session *session,
                             unsigned seq, 
                             int lost,
                             int dup,
                             int discarded,
                             int jitter,
                             int toh, pj_bool_t toh_ipv4);

/**
 * This function is called internally by RTCP session whenever an RTP 
 * packet is sent to let the RTCP XR session do its internal calculations.
 *
 * @param session   RTCP XR session.
 * @param ptsize    Size of RTP payload being sent.
 */
void pjmedia_rtcp_xr_tx_rtp( pjmedia_rtcp_xr_session *session, 
                             unsigned ptsize );

/**
 * @}
 */

PJ_END_DECL


#endif  /* __PJMEDIA_RTCP_XR_H__ */