Ticket #923: New API to retrieve current jitter buffer state from a stream/session

 - added pjmedia_session_get_stream_stat_jbuf() and pjmedia_session_get_stream_stat_jbuf()
 - fixed const correctness in pjmedia_jbuf_get_state(), jb_framelist_size(), and pj_math_stat_get_stddev(), 
 - modify the jitter buffer statistic log message printed by stream (it contains newlines)



git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2844 74dad513-b988-da41-8d7b-12977e46ad98

6 files changed, 66 insertions, 13 deletions

diff --git a/pjmedia/include/pjmedia/jbuf.h b/pjmedia/include/pjmedia/jbuf.h
index 4088e359..cd5e9f13 100644
--- a/pjmedia/include/pjmedia/jbuf.h
+++ b/pjmedia/include/pjmedia/jbuf.h
@@ -300,7 +300,7 @@ PJ_DECL(void) pjmedia_jbuf_get_frame2(pjmedia_jbuf *jb,
  *
  * @return		PJ_SUCCESS on success.
  */
-PJ_DECL(pj_status_t) pjmedia_jbuf_get_state( pjmedia_jbuf *jb,
+PJ_DECL(pj_status_t) pjmedia_jbuf_get_state( const pjmedia_jbuf *jb,
 					     pjmedia_jb_state *state );
 
 
diff --git a/pjmedia/include/pjmedia/session.h b/pjmedia/include/pjmedia/session.h
index c235d13b..2fd7d1a2 100644
--- a/pjmedia/include/pjmedia/session.h
+++ b/pjmedia/include/pjmedia/session.h
@@ -269,6 +269,7 @@ PJ_DECL(pj_status_t) pjmedia_session_get_port( pjmedia_session *session,
 /**
  * Get session statistics. The stream statistic shows various
  * indicators such as packet count, packet lost, jitter, delay, etc.
+ * See also #pjmedia_session_get_stream_stat_jbuf()
  *
  * @param session	The media session.
  * @param index		Stream index.
@@ -301,6 +302,21 @@ PJ_DECL(pj_status_t) pjmedia_session_get_stream_stat_xr(
 
 
 /**
+ * Get current jitter buffer state for the specified stream.
+ * See also #pjmedia_session_get_stream_stat()
+ *
+ * @param session	The media session.
+ * @param index		Stream index.
+ * @param state		Jitter buffer state.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_session_get_stream_stat_jbuf(
+					    pjmedia_session *session,
+					    unsigned index,
+					    pjmedia_jb_state *state);
+
+/**
  * Dial DTMF digit to the stream, using RFC 2833 mechanism.
  *
  * @param session	The media session.
diff --git a/pjmedia/include/pjmedia/stream.h b/pjmedia/include/pjmedia/stream.h
index 0227f645..94727e25 100644
--- a/pjmedia/include/pjmedia/stream.h
+++ b/pjmedia/include/pjmedia/stream.h
@@ -28,6 +28,7 @@
 
 #include <pjmedia/codec.h>
 #include <pjmedia/endpoint.h>
+#include <pjmedia/jbuf.h>
 #include <pjmedia/port.h>
 #include <pjmedia/rtcp.h>
 #include <pjmedia/transport.h>
@@ -214,7 +215,8 @@ PJ_DECL(pj_status_t) pjmedia_stream_start(pjmedia_stream *stream);
 
 
 /**
- * Get the stream statistics.
+ * Get the stream statistics. See also
+ * #pjmedia_stream_get_stat_jbuf()
  *
  * @param stream	The media stream.
  * @param stat		Media stream statistics.
@@ -238,6 +240,19 @@ PJ_DECL(pj_status_t) pjmedia_stream_get_stat_xr( const pjmedia_stream *stream,
 #endif
 
 /**
+ * Get current jitter buffer state. See also
+ * #pjmedia_stream_get_stat()
+ *
+ * @param stream	The media stream.
+ * @param state		Jitter buffer state.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_stream_get_stat_jbuf(const pjmedia_stream *stream,
+						  pjmedia_jb_state *state);
+
+
+/**
  * Pause the individual channel in the stream.
  *
  * @param stream	The media channel.
diff --git a/pjmedia/src/pjmedia/jbuf.c b/pjmedia/src/pjmedia/jbuf.c
index 1df68a57..2af89911 100644
--- a/pjmedia/src/pjmedia/jbuf.c
+++ b/pjmedia/src/pjmedia/jbuf.c
@@ -211,7 +211,7 @@ static pj_status_t jb_framelist_reset(jb_framelist_t *framelist)
 }
 
 
-static unsigned jb_framelist_size(jb_framelist_t *framelist) 
+static unsigned jb_framelist_size(const jb_framelist_t *framelist) 
 {
     return framelist->size;
 }
@@ -468,12 +468,12 @@ PJ_DEF(pj_status_t) pjmedia_jbuf_reset(pjmedia_jbuf *jb)
 
 PJ_DEF(pj_status_t) pjmedia_jbuf_destroy(pjmedia_jbuf *jb)
 {
-    TRACE__((jb->jb_name.ptr, "\n"
-	    "  JB summary:\n"
-	    "    size=%d prefetch=%d\n"
-	    "    delay (min/max/avg/dev)=%d/%d/%d/%d ms\n"
-	    "    burst (min/max/avg/dev)=%d/%d/%d/%d frames\n"
-	    "    lost=%d discard=%d empty=%d\n",
+    TRACE__((jb->jb_name.ptr, ""
+	    "JB summary:"
+	    " size=%d prefetch=%d,"
+	    " delay (min/max/avg/dev)=%d/%d/%d/%d ms,"
+	    " burst (min/max/avg/dev)=%d/%d/%d/%d frames,"
+	    " lost=%d discard=%d empty=%d",
 	    jb->jb_framelist.size, jb->jb_prefetch,
 	    jb->jb_delay.min, jb->jb_delay.max, jb->jb_delay.mean, 
 	    pj_math_stat_get_stddev(&jb->jb_delay),
@@ -765,7 +765,7 @@ PJ_DEF(void) pjmedia_jbuf_get_frame2(pjmedia_jbuf *jb,
 /*
  * Get jitter buffer state.
  */
-PJ_DEF(pj_status_t) pjmedia_jbuf_get_state( pjmedia_jbuf *jb,
+PJ_DEF(pj_status_t) pjmedia_jbuf_get_state( const pjmedia_jbuf *jb,
 					    pjmedia_jb_state *state )
 {
     PJ_ASSERT_RETURN(jb && state, PJ_EINVAL);
diff --git a/pjmedia/src/pjmedia/session.c b/pjmedia/src/pjmedia/session.c
index a2b33a98..097ae4b7 100644
--- a/pjmedia/src/pjmedia/session.c
+++ b/pjmedia/src/pjmedia/session.c
@@ -857,6 +857,17 @@ PJ_DEF(pj_status_t) pjmedia_session_get_stream_stat_xr(
 }
 #endif
 
+PJ_DEF(pj_status_t) pjmedia_session_get_stream_stat_jbuf(
+					    pjmedia_session *session,
+					    unsigned index,
+					    pjmedia_jb_state *state)
+{
+    PJ_ASSERT_RETURN(session && state && index < session->stream_cnt, 
+		     PJ_EINVAL);
+
+    return pjmedia_stream_get_stat_jbuf(session->stream[index], state);
+}
+
 /*
  * Dial DTMF digit to the stream, using RFC 2833 mechanism.
  */
diff --git a/pjmedia/src/pjmedia/stream.c b/pjmedia/src/pjmedia/stream.c
index 35b6dc90..587370e3 100644
--- a/pjmedia/src/pjmedia/stream.c
+++ b/pjmedia/src/pjmedia/stream.c
@@ -327,6 +327,7 @@ static pj_status_t get_frame( pjmedia_port *port, pjmedia_frame *frame)
 	     */
 	    if (frame_type != stream->jb_last_frm) {
 		pjmedia_jb_state jb_state;
+		const char *with_plc = "";
 
 		/* Activate PLC to smoothen the missing frame */
 		if (stream->codec->op->recover && 
@@ -346,13 +347,14 @@ static pj_status_t get_frame( pjmedia_port *port, pjmedia_frame *frame)
 
 		    } while (samples_count < samples_required);
 
+		    with_plc = ", plc invoked";
 		} 
 
 		/* Report the state of jitter buffer */
 		pjmedia_jbuf_get_state(stream->jb, &jb_state);
 		PJ_LOG(5,(stream->port.info.name.ptr, 
-			  "Jitter buffer empty (prefetch=%d)", 
-			  jb_state.prefetch));
+			  "Jitter buffer empty (prefetch=%d)%s", 
+			  jb_state.prefetch, with_plc));
 
 	    }
 
@@ -1879,7 +1881,6 @@ PJ_DEF(pj_status_t) pjmedia_stream_create( pjmedia_endpt *endpt,
 	//jb_init = (jb_min_pre + jb_max_pre) / 2;
 	jb_init = 0;
 
-
     /* Create jitter buffer */
     status = pjmedia_jbuf_create(pool, &stream->port.info.name,
 				 stream->frame_size, 
@@ -2172,6 +2173,16 @@ PJ_DEF(pj_status_t) pjmedia_stream_get_stat_xr( const pjmedia_stream *stream,
 #endif
 
 /*
+ * Get jitter buffer state.
+ */
+PJ_DEF(pj_status_t) pjmedia_stream_get_stat_jbuf(const pjmedia_stream *stream,
+						 pjmedia_jb_state *state)
+{
+    PJ_ASSERT_RETURN(stream && state, PJ_EINVAL);
+    return pjmedia_jbuf_get_state(stream->jb, state);
+}
+
+/*
  * Pause stream.
  */
 PJ_DEF(pj_status_t) pjmedia_stream_pause( pjmedia_stream *stream,