Added sound port (sound_port.h/c), and changed sound and RTCP names from pj_* to pjmedia_*

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

5 files changed, 258 insertions, 69 deletions

diff --git a/pjmedia/include/pjmedia/errno.h b/pjmedia/include/pjmedia/errno.h
index 7537744a..3d95c44a 100644
--- a/pjmedia/include/pjmedia/errno.h
+++ b/pjmedia/include/pjmedia/errno.h
@@ -415,6 +415,11 @@ PJ_BEGIN_DECL
  * Incompatible bytes per frame
  */
 #define PJMEDIA_ENCBYTES	    (PJMEDIA_ERRNO_START+165)    /* 220165 */
+/**
+ * @hideinitializer
+ * Incompatible number of channels
+ */
+#define PJMEDIA_ENCCHANNEL	    (PJMEDIA_ERRNO_START+166)    /* 220166 */
 
 
 /************************************************************
diff --git a/pjmedia/include/pjmedia/port.h b/pjmedia/include/pjmedia/port.h
index 5437061a..196e7139 100644
--- a/pjmedia/include/pjmedia/port.h
+++ b/pjmedia/include/pjmedia/port.h
@@ -78,6 +78,7 @@ struct pjmedia_port_info
     unsigned	    pt;			/**< Payload type (can be dynamic). */
     pj_str_t	    encoding_name;	/**< Encoding name.		    */
     unsigned	    sample_rate;	/**< Sampling rate.		    */
+    unsigned	    channel_count;	/**< Number of channels.	    */
     unsigned	    bits_per_sample;	/**< Bits/sample		    */
     unsigned	    samples_per_frame;	/**< No of samples per frame.	    */
     unsigned	    bytes_per_frame;	/**< No of samples per frame.	    */
diff --git a/pjmedia/include/pjmedia/rtcp.h b/pjmedia/include/pjmedia/rtcp.h
index d0873e72..f39c7800 100644
--- a/pjmedia/include/pjmedia/rtcp.h
+++ b/pjmedia/include/pjmedia/rtcp.h
@@ -39,7 +39,7 @@ PJ_BEGIN_DECL
 /**
  * RTCP sender report.
  */
-struct pj_rtcp_sr
+struct pjmedia_rtcp_sr
 {
     pj_uint32_t	    ssrc;	    /**< SSRC identification.		*/
     pj_uint32_t	    ntp_sec;	    /**< NTP time, seconds part.	*/
@@ -50,14 +50,14 @@ struct pj_rtcp_sr
 };
 
 /**
- * @see pj_rtcp_sr
+ * @see pjmedia_rtcp_sr
  */
-typedef struct pj_rtcp_sr pj_rtcp_sr;
+typedef struct pjmedia_rtcp_sr pjmedia_rtcp_sr;
 
 /**
  * RTCP receiver report.
  */
-struct pj_rtcp_rr
+struct pjmedia_rtcp_rr
 {
     pj_uint32_t	    ssrc;	    /**< SSRC identification.		*/
 #if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
@@ -78,15 +78,15 @@ struct pj_rtcp_rr
 };
 
 /**
- * @see pj_rtcp_rr
+ * @see pjmedia_rtcp_rr
  */
-typedef struct pj_rtcp_rr pj_rtcp_rr;
+typedef struct pjmedia_rtcp_rr pjmedia_rtcp_rr;
 
 
 /**
  * RTCP common header.
  */
-struct pj_rtcp_common
+struct pjmedia_rtcp_common
 {
 #if defined(PJ_IS_BIG_ENDIAN) && PJ_IS_BIG_ENDIAN!=0
     unsigned	    version:2;	/**< packet type            */
@@ -103,48 +103,48 @@ struct pj_rtcp_common
 };
 
 /**
- * @see pj_rtcp_common
+ * @see pjmedia_rtcp_common
  */
-typedef struct pj_rtcp_common pj_rtcp_common;
+typedef struct pjmedia_rtcp_common pjmedia_rtcp_common;
 
 /**
  * RTCP packet.
  */
-struct pj_rtcp_pkt
+struct pjmedia_rtcp_pkt
 {
-    pj_rtcp_common  common;	/**< Common header.	    */
-    pj_rtcp_sr	    sr;		/**< Sender report.	    */
-    pj_rtcp_rr	    rr;		/**< variable-length list   */
+    pjmedia_rtcp_common  common;	/**< Common header.	    */
+    pjmedia_rtcp_sr sr;		/**< Sender report.	    */
+    pjmedia_rtcp_rr rr;		/**< variable-length list   */
 };
 
 /**
- * @see pj_rtcp_pkt
+ * @see pjmedia_rtcp_pkt
  */
-typedef struct pj_rtcp_pkt pj_rtcp_pkt;
+typedef struct pjmedia_rtcp_pkt pjmedia_rtcp_pkt;
 
 
 /**
  * NTP time representation.
  */
-struct pj_rtcp_ntp_rec
+struct pjmedia_rtcp_ntp_rec
 {
     pj_uint32_t	    hi;		/**< High order 32-bit part.	*/
     pj_uint32_t	    lo;		/**< Lo order 32-bit part.	*/
 };
 
 /**
- * @see pj_rtcp_ntp_rec
+ * @see pjmedia_rtcp_ntp_rec
  */
-typedef struct pj_rtcp_ntp_rec pj_rtcp_ntp_rec;
+typedef struct pjmedia_rtcp_ntp_rec pjmedia_rtcp_ntp_rec;
 
 
 
 /**
  * RTCP session.
  */
-struct pj_rtcp_session
+struct pjmedia_rtcp_session
 {
-    pj_rtcp_pkt	    rtcp_pkt;	    /**< Cached RTCP packet.		    */
+    pjmedia_rtcp_pkt	    rtcp_pkt;	/**< Cached RTCP packet.	    */
     
     pjmedia_rtp_seq_session seq_ctrl;	/**< RTCP sequence number control.  */
 
@@ -154,16 +154,16 @@ struct pj_rtcp_session
     pj_int32_t	    transit;        /**< Relative trans time for prev pkt   */
     pj_uint32_t	    jitter;	    /**< Estimated jitter		    */
     
-    pj_rtcp_ntp_rec rtcp_lsr;	    /**< NTP ts in last SR received	    */
-    unsigned 	    rtcp_lsr_time;  /**< Time when last SR is received.	    */
-    pj_uint32_t	    peer_ssrc;	    /**< Peer SSRC			    */
+    pjmedia_rtcp_ntp_rec rtcp_lsr;	 /**< NTP ts in last SR received    */
+    unsigned 		 rtcp_lsr_time;  /**< Time when last SR is received.*/
+    pj_uint32_t		 peer_ssrc;	 /**< Peer SSRC			    */
     
 };
 
 /**
- * @see pj_rtcp_session
+ * @see pjmedia_rtcp_session
  */
-typedef struct pj_rtcp_session pj_rtcp_session;
+typedef struct pjmedia_rtcp_session pjmedia_rtcp_session;
 
 
 /**
@@ -172,7 +172,8 @@ typedef struct pj_rtcp_session pj_rtcp_session;
  * @param session   The session
  * @param ssrc	    The SSRC used in to identify the session.
  */
-PJ_DECL(void) pj_rtcp_init( pj_rtcp_session *session, pj_uint32_t ssrc );
+PJ_DECL(void) pjmedia_rtcp_init( pjmedia_rtcp_session *session, 
+				 pj_uint32_t ssrc );
 
 
 /**
@@ -180,7 +181,7 @@ PJ_DECL(void) pj_rtcp_init( pj_rtcp_session *session, pj_uint32_t ssrc );
  *
  * @param session   The session.
  */
-PJ_DECL(void) pj_rtcp_fini( pj_rtcp_session *session);
+PJ_DECL(void) pjmedia_rtcp_fini( pjmedia_rtcp_session *session);
 
 
 /**
@@ -191,8 +192,9 @@ PJ_DECL(void) pj_rtcp_fini( pj_rtcp_session *session);
  * @param seq	    The RTP packet sequence number, in host byte order.
  * @param ts	    The RTP packet timestamp, in host byte order.
  */
-PJ_DECL(void) pj_rtcp_rx_rtp( pj_rtcp_session *session, pj_uint16_t seq, 
-			      pj_uint32_t ts );
+PJ_DECL(void) pjmedia_rtcp_rx_rtp( pjmedia_rtcp_session *session, 
+				   pj_uint16_t seq, 
+				   pj_uint32_t ts );
 
 
 /**
@@ -203,7 +205,8 @@ PJ_DECL(void) pj_rtcp_rx_rtp( pj_rtcp_session *session, pj_uint16_t seq,
  * @param ptsize    The payload size of the RTP packet (ie packet minus
  *		    RTP header) in bytes.
  */
-PJ_DECL(void) pj_rtcp_tx_rtp( pj_rtcp_session *session, pj_uint16_t ptsize );
+PJ_DECL(void) pjmedia_rtcp_tx_rtp( pjmedia_rtcp_session *session, 
+				   pj_uint16_t ptsize );
 
 
 /**
@@ -215,9 +218,9 @@ PJ_DECL(void) pj_rtcp_tx_rtp( pj_rtcp_session *session, pj_uint16_t ptsize );
  * @param len	    [output] Upon return, it will indicate the size of 
  *		    the RTCP packet.
  */
-PJ_DECL(void) pj_rtcp_build_rtcp( pj_rtcp_session *session, 
-				  pj_rtcp_pkt **rtcp_pkt, 
-				  int *len );
+PJ_DECL(void) pjmedia_rtcp_build_rtcp( pjmedia_rtcp_session *session, 
+				       pjmedia_rtcp_pkt **rtcp_pkt, 
+				       int *len );
 
 
 /**
diff --git a/pjmedia/include/pjmedia/sound.h b/pjmedia/include/pjmedia/sound.h
index 5719c0f9..3d0b444e 100644
--- a/pjmedia/include/pjmedia/sound.h
+++ b/pjmedia/include/pjmedia/sound.h
@@ -36,18 +36,18 @@ PJ_BEGIN_DECL
  */
 
 /** Opaque data type for audio stream. */
-typedef struct pj_snd_stream pj_snd_stream;
+typedef struct pjmedia_snd_stream pjmedia_snd_stream;
 
 /**
- * Device information structure returned by #pj_snd_get_dev_info.
+ * Device information structure returned by #pjmedia_snd_get_dev_info.
  */
-typedef struct pj_snd_dev_info
+typedef struct pjmedia_snd_dev_info
 {
     char	name[64];	        /**< Device name.		    */
     unsigned	input_count;	        /**< Max number of input channels.  */
     unsigned	output_count;	        /**< Max number of output channels. */
     unsigned	default_samples_per_sec;/**< Default sampling rate.	    */
-} pj_snd_dev_info;
+} pjmedia_snd_dev_info;
 
 /** 
  * This callback is called by player stream when it needs additional data
@@ -62,7 +62,7 @@ typedef struct pj_snd_dev_info
  *
  * @return		Non-zero to stop the stream.
  */
-typedef pj_status_t (*pj_snd_play_cb)(/* in */   void *user_data,
+typedef pj_status_t (*pjmedia_snd_play_cb)(/* in */   void *user_data,
 				      /* in */   pj_uint32_t timestamp,
 				      /* out */  void *output,
 				      /* out */  unsigned size);
@@ -78,7 +78,7 @@ typedef pj_status_t (*pj_snd_play_cb)(/* in */   void *user_data,
  *
  * @return		Non-zero to stop the stream.
  */
-typedef pj_status_t (*pj_snd_rec_cb)(/* in */   void *user_data,
+typedef pj_status_t (*pjmedia_snd_rec_cb)(/* in */   void *user_data,
 				     /* in */   pj_uint32_t timestamp,
 				     /* in */   const void *input,
 				     /* in*/    unsigned size);
@@ -90,7 +90,7 @@ typedef pj_status_t (*pj_snd_rec_cb)(/* in */   void *user_data,
  *
  * @return		Zero on success.
  */
-PJ_DECL(pj_status_t) pj_snd_init(pj_pool_factory *factory);
+PJ_DECL(pj_status_t) pjmedia_snd_init(pj_pool_factory *factory);
 
 
 /**
@@ -98,57 +98,72 @@ PJ_DECL(pj_status_t) pj_snd_init(pj_pool_factory *factory);
  *
  * @return		Number of devices.
  */
-PJ_DECL(int) pj_snd_get_dev_count(void);
+PJ_DECL(int) pjmedia_snd_get_dev_count(void);
 
 
 /**
  * Get device info.
  *
  * @param index		The index of the device, which should be in the range
- *			from zero to #pj_snd_get_dev_count - 1.
+ *			from zero to #pjmedia_snd_get_dev_count - 1.
  */
-PJ_DECL(const pj_snd_dev_info*) pj_snd_get_dev_info(unsigned index);
+PJ_DECL(const pjmedia_snd_dev_info*) pjmedia_snd_get_dev_info(unsigned index);
 
 
 /**
  * Create a new audio stream for audio capture purpose.
  *
- * @param index		Device index, or -1 to let the library choose the first
- *			available device, or -2 to use NULL device.
- * @param param		Stream parameters.
- * @param rec_cb	Callback to handle captured audio samples.
- * @param user_data	User data to be associated with the stream.
- *
- * @return		Audio stream, or NULL if failed.
- */
-PJ_DECL(pj_status_t) pj_snd_open_recorder( int index,
+ * @param index		    Device index, or -1 to let the library choose the 
+ *			    first available device.
+ * @param clock_rate	    Sound device's clock rate to set.
+ * @param channel_count	    Set number of channels, 1 for mono, or 2 for
+ *			    stereo. The channel count determines the format
+ *			    of the frame.
+ * @param samples_per_frame Number of samples per frame.
+ * @param bits_per_sample   Set the number of bits per sample. The normal 
+ *			    value for this parameter is 16 bits per sample.
+ * @param rec_cb	    Callback to handle captured audio samples.
+ * @param user_data	    User data to be associated with the stream.
+ * @param p_snd_strm	    Pointer to receive the stream instance.
+ *
+ * @return		    PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_open_recorder( int index,
 					   unsigned clock_rate,
 					   unsigned channel_count,
 					   unsigned samples_per_frame,
 					   unsigned bits_per_sample,
-					   pj_snd_rec_cb rec_cb,
+					   pjmedia_snd_rec_cb rec_cb,
 					   void *user_data,
-					   pj_snd_stream **p_snd_strm);
+					   pjmedia_snd_stream **p_snd_strm);
 
 /**
  * Create a new audio stream for playing audio samples.
  *
- * @param index		Device index, or -1 to let the library choose the first
- *			available device, or -2 to use NULL device.
- * @param param		Stream parameters.
- * @param play_cb	Callback to supply audio samples.
- * @param user_data	User data to be associated with the stream.
- *
- * @return		Audio stream, or NULL if failed.
- */
-PJ_DECL(pj_status_t) pj_snd_open_player( int index,
+ * @param index		    Device index, or -1 to let the library choose the 
+ *			    first available device.
+ * @param clock_rate	    Sound device's clock rate to set.
+ * @param channel_count	    Set number of channels, 1 for mono, or 2 for
+ *			    stereo. The channel count determines the format
+ *			    of the frame.
+ * @param samples_per_frame Number of samples per frame.
+ * @param bits_per_sample   Set the number of bits per sample. The normal 
+ *			    value for this parameter is 16 bits per sample.
+ * @param play_cb	    Callback to be called when the sound player needs
+ *			    more audio samples to play.
+ * @param user_data	    User data to be associated with the stream.
+ * @param p_snd_strm	    Pointer to receive the stream instance.
+ *
+ * @return		    PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_open_player( int index,
 					 unsigned clock_rate,
 					 unsigned channel_count,
 					 unsigned samples_per_frame,
 					 unsigned bits_per_sample,
-					 pj_snd_play_cb play_cb,
+					 pjmedia_snd_play_cb play_cb,
 					 void *user_data,
-					 pj_snd_stream **p_snd_strm );
+					 pjmedia_snd_stream **p_snd_strm );
 
 /**
  * Start the stream.
@@ -157,7 +172,7 @@ PJ_DECL(pj_status_t) pj_snd_open_player( int index,
  *
  * @return		Zero on success.
  */
-PJ_DECL(pj_status_t) pj_snd_stream_start(pj_snd_stream *stream);
+PJ_DECL(pj_status_t) pjmedia_snd_stream_start(pjmedia_snd_stream *stream);
 
 /**
  * Stop the stream.
@@ -166,7 +181,7 @@ PJ_DECL(pj_status_t) pj_snd_stream_start(pj_snd_stream *stream);
  *
  * @return		Zero on success.
  */
-PJ_DECL(pj_status_t) pj_snd_stream_stop(pj_snd_stream *stream);
+PJ_DECL(pj_status_t) pjmedia_snd_stream_stop(pjmedia_snd_stream *stream);
 
 /**
  * Destroy the stream.
@@ -175,14 +190,14 @@ PJ_DECL(pj_status_t) pj_snd_stream_stop(pj_snd_stream *stream);
  *
  * @return		Zero on success.
  */
-PJ_DECL(pj_status_t) pj_snd_stream_close(pj_snd_stream *stream);
+PJ_DECL(pj_status_t) pjmedia_snd_stream_close(pjmedia_snd_stream *stream);
 
 /**
  * Deinitialize sound library.
  *
  * @return		Zero on success.
  */
-PJ_DECL(pj_status_t) pj_snd_deinit(void);
+PJ_DECL(pj_status_t) pjmedia_snd_deinit(void);
 
 
 
diff --git a/pjmedia/include/pjmedia/sound_port.h b/pjmedia/include/pjmedia/sound_port.h
new file mode 100644
index 00000000..c7d1153d
--- /dev/null
+++ b/pjmedia/include/pjmedia/sound_port.h
@@ -0,0 +1,165 @@
+/* $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_SOUND_PORT_H__
+#define __PJMEDIA_SOUND_PORT_H__
+
+/**
+ * @file sound_port.h
+ * @brief Media port connection abstraction to sound device.
+ */
+#include <pjmedia/sound.h>
+#include <pjmedia/port.h>
+
+PJ_BEGIN_DECL
+
+/**
+ * @defgroup PJMED_SND_PORT Media Port Connection Abstraction to Sound Device
+ * @ingroup PJMEDIA
+ * @{
+ */
+
+/**
+ * This opaque type describes sound device port connection.
+ * Sound device port is not a media port, but it is used to connect media
+ * port to the sound device.
+ */
+typedef struct pjmedia_snd_port pjmedia_snd_port;
+
+/**
+ * Create sound device port for capturing audio streams from the sound device
+ * with the specified parameters.
+ *
+ * @param pool		    Pool to allocate sound port structure.
+ * @param index		    Device index, or -1 to let the library choose the 
+ *			    first available device.
+ * @param clock_rate	    Sound device's clock rate to set.
+ * @param channel_count	    Set number of channels, 1 for mono, or 2 for
+ *			    stereo. The channel count determines the format
+ *			    of the frame.
+ * @param samples_per_frame Number of samples per frame.
+ * @param bits_per_sample   Set the number of bits per sample. The normal 
+ *			    value for this parameter is 16 bits per sample.
+ * @param options	    Options flag, currently must be zero.
+ * @param p_port	    Pointer to receive the sound device port instance.
+ *
+ * @return		    PJ_SUCCESS on success, or the appropriate error
+ *			    code.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_port_create_rec(pj_pool_t *pool,
+						 int index,
+						 unsigned clock_rate,
+						 unsigned channel_count,
+						 unsigned samples_per_frame,
+						 unsigned bits_per_sample,
+						 unsigned options,
+						 pjmedia_snd_port **p_port);
+					      
+/**
+ * Create sound device port for playing audio streams with the specified 
+ * parameters.
+ *
+ * @param pool		    Pool to allocate sound port structure.
+ * @param index		    Device index, or -1 to let the library choose the 
+ *			    first available device.
+ * @param clock_rate	    Sound device's clock rate to set.
+ * @param channel_count	    Set number of channels, 1 for mono, or 2 for
+ *			    stereo. The channel count determines the format
+ *			    of the frame.
+ * @param samples_per_frame Number of samples per frame.
+ * @param bits_per_sample   Set the number of bits per sample. The normal 
+ *			    value for this parameter is 16 bits per sample.
+ * @param options	    Options flag, currently must be zero.
+ * @param p_port	    Pointer to receive the sound device port instance.
+ *
+ * @return		    PJ_SUCCESS on success, or the appropriate error
+ *			    code.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_port_create_player(pj_pool_t *pool,
+						    int index,
+						    unsigned clock_rate,
+						    unsigned channel_count,
+						    unsigned samples_per_frame,
+						    unsigned bits_per_sample,
+						    unsigned options,
+						    pjmedia_snd_port **p_port);
+					      
+
+/**
+ * Destroy sound device port.
+ *
+ * @param snd_port	    The sound device port.
+ *
+ * @return		    PJ_SUCCESS on success, or the appropriate error
+ *			    code.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_port_destroy(pjmedia_snd_port *snd_port);
+
+
+/**
+ * Connect a port to the sound device port. If the sound device port is a
+ * sound recorder device, then this will start periodic function call to
+ * the port's put_frame() function. If the sound device is a sound player
+ * device, then this will start periodic function call to the port's
+ * get_frame() function.
+ *
+ * For this version of PJMEDIA, the media port MUST have the same audio
+ * settings as the sound device port, or otherwise the connection will
+ * fail. This means the port MUST have the same clock_rate, channel count,
+ * samples per frame, and bits per sample as the sound device port.
+ *
+ * @param snd_port	    The sound device port.
+ *
+ * @return		    PJ_SUCCESS on success, or the appropriate error
+ *			    code.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_port_connect(pjmedia_snd_port *snd_port,
+					      pjmedia_port *port);
+
+
+/**
+ * Retrieve the port instance currently attached to the sound port, if any.
+ *
+ * @param snd_port	    The sound device port.
+ *
+ * @return		    The port instance currently attached to the 
+ *			    sound device port, or NULL if there is no port
+ *			    currently attached to the sound device port.
+ */
+PJ_DECL(pjmedia_port*) pjmedia_snd_port_get_port(pjmedia_snd_port *snd_port);
+
+
+/**
+ * Disconnect currently attached port from the sound device port.
+ *
+ * @param snd_port	    The sound device port.
+ *
+ * @return		    PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjmedia_snd_port_disconnect(pjmedia_snd_port *snd_port);
+
+
+/**
+ * @}
+ */
+
+PJ_END_DECL
+
+
+#endif	/* __PJMEDIA_SOUND_PORT_H__ */
+