Added implementation of media clock and master port (to control frame timing of clock-less ports such as file reader/player)

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

3 files changed, 250 insertions, 0 deletions

diff --git a/pjmedia/include/pjmedia.h b/pjmedia/include/pjmedia.h
index 34264b61..f65b2da9 100644
--- a/pjmedia/include/pjmedia.h
+++ b/pjmedia/include/pjmedia.h
@@ -25,6 +25,7 @@
  */
 
 #include <pjmedia/types.h>
+#include <pjmedia/clock.h>
 #include <pjmedia/codec.h>
 #include <pjmedia/conference.h>
 #include <pjmedia/endpoint.h>
@@ -32,6 +33,7 @@
 #include <pjmedia/file_port.h>
 #include <pjmedia/g711.h>
 #include <pjmedia/jbuf.h>
+#include <pjmedia/master_port.h>
 #include <pjmedia/null_port.h>
 #include <pjmedia/port.h>
 #include <pjmedia/resample.h>
diff --git a/pjmedia/include/pjmedia/clock.h b/pjmedia/include/pjmedia/clock.h
new file mode 100644
index 00000000..fa15ee6f
--- /dev/null
+++ b/pjmedia/include/pjmedia/clock.h
@@ -0,0 +1,143 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2006 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_CLOCK_H__
+#define __PJMEDIA_CLOCK_H__
+
+/**
+ * @file clock.h
+ * @brief Media clock.
+ */
+#include <pjmedia/types.h>
+
+
+PJ_BEGIN_DECL
+
+
+/**
+ * Opaque declaration for media clock.
+ */
+typedef struct pjmedia_clock pjmedia_clock;
+
+
+enum pjmedia_clock_options
+{
+    PJMEDIA_CLOCK_NO_ASYNC  = 1,
+};
+
+/**
+ * Type of media clock callback.
+ *
+ * @param ts		    Current timestamp, in samples.
+ * @param user_data	    Application data that is passed when
+ *			    the clock was created.
+ */
+typedef void pjmedia_clock_callback(const pj_timestamp *ts,
+				    void *user_data);
+
+
+
+/**
+ * Create media clock.
+ *
+ * @param pool		    Pool to allocate memory.
+ * @param clock_rate	    Number of samples per second.
+ * @param samples_per_frame Number of samples per frame. This argument
+ *			    along with clock_rate, specifies the interval
+ *			    of each clock run (or clock ticks).
+ * @param options	    By default, the callback will be called 
+ *			    asynchronously (depending on the clock 
+ *			    implementation backend, a thread may be 
+ *			    created). If PJMEDIA_CLOCK_NO_ASYNC is set,
+ *			    application must poll the clock with 
+ *			    #pjmedia_clock_wait() to let the clock runs.
+ * @param cb		    Callback to be called for each clock tick.
+ * @param user_data	    User data, which will be passed to the callback.
+ * @param p_clock	    Pointer to receive the clock instance.
+ *
+ * @return		    PJ_SUCCESS on success, or the appropriate error
+ *			    code.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_create( pj_pool_t *pool,
+					   unsigned clock_rate,
+					   unsigned samples_per_frame,
+					   unsigned options,
+					   pjmedia_clock_callback *cb,
+					   void *user_data,
+					   pjmedia_clock **p_clock);
+
+/**
+ * Start the clock. For clock created with asynchronous flag set to TRUE,
+ * this may start a worker thread for the clock (depending on the 
+ * backend clock implementation being used).
+ *
+ * @param clock		    The media clock.
+ *
+ * @return		    PJ_SUCCES on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_start(pjmedia_clock *clock);
+
+
+/**
+ * Stop the clock.
+ *
+ * @param clock		    The media clock.
+ *
+ * @return		    PJ_SUCCES on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_stop(pjmedia_clock *clock);
+
+
+
+/**
+ * Poll the media clock, and execute the callback when the clock tick has
+ * elapsed. This operation is only valid if the clock is created with async
+ * flag set to FALSE.
+ *
+ * @param clock		    The media clock.
+ * @param wait		    If non-zero, then the function will block until
+ *			    a clock tick elapsed and callback has been called.
+ * @param ts		    Optional argument to receive the current 
+ *			    timestamp.
+ *
+ * @return		    Non-zero if clock tick has elapsed, or FALSE if
+ *			    the function returns before a clock tick has
+ *			    elapsed.
+ */
+PJ_DECL(pj_bool_t) pjmedia_clock_wait(pjmedia_clock *clock,
+				      pj_bool_t wait,
+				      pj_timestamp *ts);
+
+
+/**
+ * Destroy the clock.
+ *
+ * @param clock		    The media clock.
+ *
+ * @return		    PJ_SUCCES on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_clock_destroy(pjmedia_clock *clock);
+
+
+
+PJ_END_DECL
+
+
+
+#endif	/* __PJMEDIA_CLOCK_H__ */
+
diff --git a/pjmedia/include/pjmedia/master_port.h b/pjmedia/include/pjmedia/master_port.h
new file mode 100644
index 00000000..44b7db78
--- /dev/null
+++ b/pjmedia/include/pjmedia/master_port.h
@@ -0,0 +1,105 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2006 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_MASTER_PORT_H__
+#define __PJMEDIA_MASTER_PORT_H__
+
+
+/**
+ * @file master_port.h
+ * @brief Master port.
+ */
+#include <pjmedia/port.h>
+
+
+PJ_BEGIN_DECL
+
+
+/**
+ * Opaque declaration for master port.
+ * A master port has two media ports connected to it, i.e. downstream and
+ * upstream ports. The media stream flowing to the downstream port is called
+ * encoding or send direction, and media stream flowing to the upstream port
+ * is called decoding or receive direction.
+ *
+ * A master port has a "clock" that periodically passes the media frame from 
+ * downstream to upstream ports, and vice versa. In each run, it retrieves 
+ * media frame from one side with #pjmedia_port_get_frame(), and passes the 
+ * media frame to the other side with #pjmedia_port_put_frame(). In each run,
+ * this process is done for twice, i.e. one for each direction.
+ */
+typedef struct pjmedia_master_port pjmedia_master_port;
+
+
+/**
+ * Create a master port.
+ *
+ * @param pool		Pool to allocate master port from.
+ * @param u_port	Upstream port.
+ * @param d_port	Downstream port.
+ * @param options	Options flags.
+ * @param p_m		Pointer to receive the master port instance.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_master_port_create(pj_pool_t *pool,
+						pjmedia_port *u_port,
+						pjmedia_port *d_port,
+						unsigned options,
+						pjmedia_master_port **p_m);
+
+
+
+/**
+ * Start the media flow.
+ *
+ * @param m		The master port.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_master_port_start(pjmedia_master_port *m);
+
+
+
+/**
+ * Stop the media flow.
+ *
+ * @param m		The master port.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_master_port_stop(pjmedia_master_port *m);
+
+
+/**
+ * Destroy the master port, and optionally destroy the upstream and 
+ * downstream ports.
+ *
+ * @param m		The master port.
+ *
+ * @return		PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_master_port_destroy(pjmedia_master_port *m);
+
+
+
+PJ_END_DECL
+
+
+#endif	/* __PJMEDIA_MASTER_PORT_H__ */
+