Updated doxygen documentation to all headers in PJMEDIA

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

3 files changed, 109 insertions, 149 deletions

diff --git a/pjmedia/src/pjmedia/port.c b/pjmedia/src/pjmedia/port.c
index 50a008e9..96c07c08 100644
--- a/pjmedia/src/pjmedia/port.c
+++ b/pjmedia/src/pjmedia/port.c
@@ -25,84 +25,6 @@
 
 
 /**
- * Connect two ports.
- */
-PJ_DEF(pj_status_t) pjmedia_port_connect( pj_pool_t *pool,
-					  pjmedia_port *upstream_port,
-					  pjmedia_port *downstream_port)
-{
-    pj_status_t status;
-
-    PJ_ASSERT_RETURN(pool && upstream_port && downstream_port, PJ_EINVAL);
-
-#if 0
-    /* They both MUST have the same media type. */
-    PJ_ASSERT_RETURN(upstream_port->info.type ==
-		     downstream_port->info.type, PJMEDIA_ENCTYPE);
-
-    /* They both MUST have the same clock rate. */
-    PJ_ASSERT_RETURN(upstream_port->info.sample_rate ==
-		     downstream_port->info.sample_rate, PJMEDIA_ENCCLOCKRATE);
-
-    /* They both MUST have the same samples per frame */
-    PJ_ASSERT_RETURN(upstream_port->info.samples_per_frame ==
-		     downstream_port->info.samples_per_frame, 
-		     PJMEDIA_ENCSAMPLESPFRAME);
-
-    /* They both MUST have the same bits per sample */
-    PJ_ASSERT_RETURN(upstream_port->info.bits_per_sample ==
-		     downstream_port->info.bits_per_sample, 
-		     PJMEDIA_ENCBITS);
-
-    /* They both MUST have the same bytes per frame */
-    PJ_ASSERT_RETURN(upstream_port->info.bytes_per_frame ==
-		     downstream_port->info.bytes_per_frame, 
-		     PJMEDIA_ENCBYTES);
-#endif
-
-    /* Create mutual attachment. */
-    if (upstream_port->on_downstream_connect) {
-	status = upstream_port->on_downstream_connect( pool, upstream_port,
-						       downstream_port );
-	if (status != PJ_SUCCESS)
-	    return status;
-    }
-
-    if (downstream_port->on_upstream_connect) {
-	status = downstream_port->on_upstream_connect( pool, downstream_port,
-						       upstream_port );
-	if (status != PJ_SUCCESS)
-	    return status;
-    }
-
-    /* Save the attachment. */
-    upstream_port->downstream_port = downstream_port;
-    downstream_port->upstream_port = upstream_port;
-    
-    /* Done. */
-    return PJ_SUCCESS;
-}
-
-
-/**
- * Disconnect ports.
- */
-PJ_DEF(pj_status_t) pjmedia_port_disconnect( pjmedia_port *upstream_port,
-					     pjmedia_port *downstream_port)
-{
-    PJ_ASSERT_RETURN(upstream_port && downstream_port, PJ_EINVAL);
-
-    if (upstream_port->downstream_port == downstream_port)
-	upstream_port->downstream_port = NULL;
-
-    if (downstream_port->upstream_port == upstream_port)
-	downstream_port->upstream_port = NULL;
-
-    return PJ_SUCCESS;
-}
-
-
-/**
  * Get a frame from the port (and subsequent downstream ports).
  */
 PJ_DEF(pj_status_t) pjmedia_port_get_frame( pjmedia_port *port,
@@ -115,7 +37,6 @@ PJ_DEF(pj_status_t) pjmedia_port_get_frame( pjmedia_port *port,
 }
 
 
-
 /**
  * Put a frame to the port (and subsequent downstream ports).
  */
@@ -139,16 +60,6 @@ PJ_DEF(pj_status_t) pjmedia_port_destroy( pjmedia_port *port )
 
     PJ_ASSERT_RETURN(port, PJ_EINVAL);
 
-    /* Recursively call this function again to destroy downstream
-     * port first.
-     */
-    if (port->downstream_port) {
-	status = pjmedia_port_destroy(port->downstream_port);
-	if (status != PJ_SUCCESS)
-	    return status;
-	pjmedia_port_disconnect(port, port->downstream_port);
-    }
-
     if (port->on_destroy)
 	status = port->on_destroy(port);
     else
@@ -159,4 +70,3 @@ PJ_DEF(pj_status_t) pjmedia_port_destroy( pjmedia_port *port )
 
 
 
-
diff --git a/pjmedia/src/pjmedia/resample_port.c b/pjmedia/src/pjmedia/resample_port.c
index 8dad6430..ca128515 100644
--- a/pjmedia/src/pjmedia/resample_port.c
+++ b/pjmedia/src/pjmedia/resample_port.c
@@ -28,12 +28,12 @@
 struct resample_port
 {
     pjmedia_port	 base;
+    pjmedia_port	*dn_port;
+    unsigned		 options;
     pjmedia_resample	*resample_get;
     pjmedia_resample	*resample_put;
     pj_int16_t		*get_buf;
     pj_int16_t		*put_buf;
-    unsigned		 downstream_frame_size;
-    unsigned		 upstream_frame_size;
 };
 
 
@@ -42,74 +42,86 @@ static pj_status_t resample_put_frame(pjmedia_port *this_port,
 				      const pjmedia_frame *frame);
 static pj_status_t resample_get_frame(pjmedia_port *this_port, 
 				      pjmedia_frame *frame);
+static pj_status_t resample_destroy(pjmedia_port *this_port);
 
 
 
 PJ_DEF(pj_status_t) pjmedia_resample_port_create( pj_pool_t *pool,
-						  pj_bool_t high_quality,
-						  pj_bool_t large_filter,
-						  unsigned downstream_rate,
-						  unsigned upstream_rate,
-						  unsigned channel_count,
-						  unsigned samples_per_frame,
-						  pjmedia_port **p_port )
+						  pjmedia_port *dn_port,
+						  unsigned clock_rate,
+						  unsigned opt,
+						  pjmedia_port **p_port  )
 {
     struct resample_port *rport;
-    unsigned upstream_samples_per_frame;
+    unsigned ptime;
     pj_status_t status;
 
-    PJ_ASSERT_RETURN(pool && p_port, PJ_EINVAL);
+    /* Validate arguments. */
+    PJ_ASSERT_RETURN(pool && dn_port && clock_rate && p_port, PJ_EINVAL);
 
-    upstream_samples_per_frame = (unsigned)(samples_per_frame * 1.0 *
-					    upstream_rate / downstream_rate);
+    /* Only supports 16bit samples per frame */
+    PJ_ASSERT_RETURN(dn_port->info.bits_per_sample == 16, PJMEDIA_ENCBITS);
 
+    ptime = dn_port->info.samples_per_frame * 1000 / 
+	    dn_port->info.clock_rate;
+    
     /* Create and initialize port. */
     rport = pj_pool_zalloc(pool, sizeof(struct resample_port));
     PJ_ASSERT_RETURN(rport != NULL, PJ_ENOMEM);
 
-    rport->base.info.bits_per_sample = 16;
-    rport->base.info.bytes_per_frame = samples_per_frame * BYTES_PER_SAMPLE;
-    rport->base.info.channel_count = channel_count;
+    rport->base.info.clock_rate = clock_rate;
+    rport->base.info.samples_per_frame = clock_rate * ptime / 1000;
+    rport->base.info.bytes_per_frame = rport->base.info.samples_per_frame *
+				       BYTES_PER_SAMPLE;
+    rport->base.info.bits_per_sample = BYTES_PER_SAMPLE * 8;
+    rport->base.info.channel_count = dn_port->info.channel_count;
     rport->base.info.encoding_name = pj_str("pcm");
     rport->base.info.has_info = 1;
     rport->base.info.name = pj_str("resample");
     rport->base.info.need_info = 0;
     rport->base.info.pt = 0xFF;
-    rport->base.info.clock_rate = upstream_rate;
-    rport->base.info.samples_per_frame = upstream_samples_per_frame;
-    rport->base.info.signature = 0;
+    rport->base.info.signature = PJMEDIA_PORT_SIGNATURE('R','S','M','P');
     rport->base.info.type = PJMEDIA_TYPE_AUDIO;
 
-    rport->downstream_frame_size = samples_per_frame;
-    rport->upstream_frame_size = upstream_samples_per_frame;
+    rport->dn_port = dn_port;
+    rport->options = opt;
+
 
     /* Create buffers. 
      * We need separate buffer for get_frame() and put_frame() since
      * both functions may run simultaneously.
      */
-    rport->get_buf = pj_pool_alloc(pool, samples_per_frame * BYTES_PER_SAMPLE);
-    PJ_ASSERT_RETURN(rport->get_buf, PJ_ENOMEM);
+    rport->get_buf = pj_pool_alloc(pool, rport->base.info.bytes_per_frame);
+    PJ_ASSERT_RETURN(rport->get_buf != NULL, PJ_ENOMEM);
 
-    rport->put_buf = pj_pool_alloc(pool, samples_per_frame * BYTES_PER_SAMPLE);
-    PJ_ASSERT_RETURN(rport->put_buf, PJ_ENOMEM);
+    rport->put_buf = pj_pool_alloc(pool, rport->base.info.bytes_per_frame);
+    PJ_ASSERT_RETURN(rport->put_buf != NULL, PJ_ENOMEM);
 
 
     /* Create "get_frame" resample */
-    status = pjmedia_resample_create( pool, high_quality, large_filter,
-				      downstream_rate, upstream_rate,
-				      samples_per_frame, &rport->resample_get);
+    status = pjmedia_resample_create(pool, 
+				     (opt&PJMEDIA_RESAMPLE_USE_LINEAR)==0,
+				     (opt&PJMEDIA_RESAMPLE_USE_SMALL_FILTER)==0,
+				     dn_port->info.clock_rate, 
+				     rport->base.info.clock_rate,
+				     dn_port->info.samples_per_frame, 
+				     &rport->resample_get);
     if (status != PJ_SUCCESS)
 	return status;
 
     /* Create "put_frame" resample */
-    status = pjmedia_resample_create( pool, high_quality, large_filter,
-				      upstream_rate, downstream_rate,
-				      upstream_samples_per_frame,
-				      &rport->resample_put);
-
-    /* Set get_frame and put_frame interface */
+    status = pjmedia_resample_create(pool, 
+				     (opt&PJMEDIA_RESAMPLE_USE_LINEAR)==0, 
+				     (opt&PJMEDIA_RESAMPLE_USE_SMALL_FILTER)==0,
+				     rport->base.info.clock_rate, 
+				     dn_port->info.clock_rate,
+				     rport->base.info.samples_per_frame,
+				     &rport->resample_put);
+
+    /* Media port interface */
     rport->base.get_frame = &resample_get_frame;
     rport->base.put_frame = &resample_put_frame;
+    rport->base.on_destroy = &resample_destroy;
 
 
     /* Done */
@@ -127,16 +139,16 @@ static pj_status_t resample_put_frame(pjmedia_port *this_port,
     pjmedia_frame downstream_frame;
 
     /* Return if we don't have downstream port. */
-    if (this_port->downstream_port == NULL) {
+    if (rport->dn_port == NULL) {
 	return PJ_SUCCESS;
     }
 
     if (frame->type == PJMEDIA_FRAME_TYPE_AUDIO) {
-	pjmedia_resample_run( rport->resample_put, frame->buf, rport->put_buf);
+	pjmedia_resample_run( rport->resample_put, frame->buf, 
+			      rport->put_buf);
 
 	downstream_frame.buf = rport->put_buf;
-	downstream_frame.size = rport->downstream_frame_size * 
-				BYTES_PER_SAMPLE;
+	downstream_frame.size = rport->dn_port->info.bytes_per_frame;
     } else {
 	downstream_frame.buf = frame->buf;
 	downstream_frame.size = frame->size;
@@ -145,8 +157,7 @@ static pj_status_t resample_put_frame(pjmedia_port *this_port,
     downstream_frame.type = frame->type;
     downstream_frame.timestamp.u64 = frame->timestamp.u64;
 
-    return pjmedia_port_put_frame( this_port->downstream_port, 
-				   &downstream_frame );
+    return pjmedia_port_put_frame( rport->dn_port, &downstream_frame );
 }
 
 
@@ -155,31 +166,53 @@ static pj_status_t resample_get_frame(pjmedia_port *this_port,
 				      pjmedia_frame *frame)
 {
     struct resample_port *rport = (struct resample_port*) this_port;
-    pjmedia_frame downstream_frame;
+    pjmedia_frame tmp_frame;
     pj_status_t status;
 
     /* Return silence if we don't have downstream port */
-    if (this_port->downstream_port == NULL) {
+    if (rport->dn_port == NULL) {
 	pj_memset(frame->buf, frame->size, 0);
 	return PJ_SUCCESS;
     }
 
-    downstream_frame.buf = rport->get_buf;
-    downstream_frame.size = rport->downstream_frame_size * BYTES_PER_SAMPLE;
-    downstream_frame.timestamp.u64 = frame->timestamp.u64;
-    downstream_frame.type = PJMEDIA_FRAME_TYPE_AUDIO;
+    tmp_frame.buf = rport->get_buf;
+    tmp_frame.size = rport->dn_port->info.bytes_per_frame;
+    tmp_frame.timestamp.u64 = frame->timestamp.u64;
+    tmp_frame.type = PJMEDIA_FRAME_TYPE_AUDIO;
 
-    status = pjmedia_port_get_frame( this_port->downstream_port,
-				     &downstream_frame);
+    status = pjmedia_port_get_frame( rport->dn_port, &tmp_frame);
     if (status != PJ_SUCCESS)
 	return status;
 
-    pjmedia_resample_run( rport->resample_get, rport->get_buf, frame->buf);
+    if (tmp_frame.type != PJMEDIA_FRAME_TYPE_AUDIO) {
+	frame->type = tmp_frame.type;
+	frame->timestamp = tmp_frame.timestamp;
+	frame->size = tmp_frame.size;
+	if (tmp_frame.size)
+	    pj_memcpy(frame->buf, tmp_frame.buf, tmp_frame.size);
+	return PJ_SUCCESS;
+    }
 
-    frame->size = rport->upstream_frame_size * BYTES_PER_SAMPLE;
+    pjmedia_resample_run( rport->resample_get, tmp_frame.buf, frame->buf);
+
+    frame->size = rport->base.info.bytes_per_frame;
     frame->type = PJMEDIA_FRAME_TYPE_AUDIO;
 
     return PJ_SUCCESS;
 }
 
 
+static pj_status_t resample_destroy(pjmedia_port *this_port)
+{
+    struct resample_port *rport = (struct resample_port*) this_port;
+
+    if ((rport->options & PJMEDIA_RESAMPLE_DONT_DESTROY_DN)==0) {
+	pjmedia_port_destroy(rport->dn_port);
+	rport->dn_port = NULL;
+    }
+
+    /* Nothing else to do */
+
+    return PJ_SUCCESS;
+}
+
diff --git a/pjmedia/src/pjmedia/wav_player.c b/pjmedia/src/pjmedia/wav_player.c
index 060055d2..e7c3df40 100644
--- a/pjmedia/src/pjmedia/wav_player.c
+++ b/pjmedia/src/pjmedia/wav_player.c
@@ -55,6 +55,8 @@
 struct file_port
 {
     pjmedia_port     base;
+    unsigned	     options;
+    pj_bool_t	     eof;
     pj_size_t	     bufsize;
     char	    *buf;
     char	    *readpos;
@@ -114,6 +116,10 @@ static pj_status_t fill_buffer(struct file_port *fport)
     pj_ssize_t size;
     pj_status_t status;
 
+    if (fport->eof) {
+	return PJ_EEOF;
+    }
+
     while (size_left > 0) {
 
 	/* Calculate how many bytes to read in this run. */
@@ -135,11 +141,19 @@ static pj_status_t fill_buffer(struct file_port *fport)
 	 * encountered EOF. Rewind the file.
 	 */
 	if (size < (pj_ssize_t)size_to_read) {
-	    PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, rewinding..",
-		      (int)fport->base.info.name.slen,
-		      fport->base.info.name.ptr));
-	    fport->fpos = sizeof(struct pjmedia_wave_hdr);
-	    pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET);
+	    if (fport->options & PJMEDIA_FILE_NO_LOOP) {
+		PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, stopping..",
+			  (int)fport->base.info.name.slen,
+			  fport->base.info.name.ptr));
+		fport->eof = PJ_TRUE;
+		return PJ_EEOF;
+	    } else {
+		PJ_LOG(5,(THIS_FILE, "File port %.*s EOF, rewinding..",
+			  (int)fport->base.info.name.slen,
+			  fport->base.info.name.ptr));
+		fport->fpos = sizeof(struct pjmedia_wave_hdr);
+		pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET);
+	    }
 	}
     }
 
@@ -156,7 +170,7 @@ static pj_status_t fill_buffer(struct file_port *fport)
 PJ_DEF(pj_status_t) pjmedia_wav_player_port_create( pj_pool_t *pool,
 						     const char *filename,
 						     unsigned ptime,
-						     unsigned flags,
+						     unsigned options,
 						     pj_ssize_t buff_size,
 						     void *user_data,
 						     pjmedia_port **p_port )
@@ -167,8 +181,6 @@ PJ_DEF(pj_status_t) pjmedia_wav_player_port_create( pj_pool_t *pool,
     pj_status_t status;
 
 
-    PJ_UNUSED_ARG(flags);
-
     /* Check arguments. */
     PJ_ASSERT_RETURN(pool && filename && p_port, PJ_EINVAL);
 
@@ -260,6 +272,7 @@ PJ_DEF(pj_status_t) pjmedia_wav_player_port_create( pj_pool_t *pool,
 
     /* Initialize */
     fport->base.user_data = user_data;
+    fport->options = options;
 
     /* Update port info. */
     fport->base.info.channel_count = wave_hdr.fmt_hdr.nchan;
@@ -337,6 +350,7 @@ PJ_DEF(pj_status_t) pjmedia_wav_player_port_set_pos(pjmedia_port *port,
 		    samples * BYTES_PER_SAMPLE;
     pj_file_setpos( fport->fd, fport->fpos, PJ_SEEK_SET);
 
+    fport->eof = PJ_FALSE;
     return fill_buffer(fport);
 }
 
@@ -384,8 +398,11 @@ static pj_status_t file_get_frame(pjmedia_port *this_port,
 	    fport->readpos = fport->buf;
 
 	    status = fill_buffer(fport);
-	    if (status != PJ_SUCCESS)
+	    if (status != PJ_SUCCESS) {
+		frame->type = PJMEDIA_FRAME_TYPE_NONE;
+		frame->size = 0;
 		return status;
+	    }
 	}
     } else {
 	unsigned endread;