Changed sound device framework to allow opening bidirectional streams from one device

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

3 files changed, 110 insertions, 9 deletions

diff --git a/pjmedia/include/pjmedia/sound.h b/pjmedia/include/pjmedia/sound.h
index 3d0b444e..6389ecf8 100644
--- a/pjmedia/include/pjmedia/sound.h
+++ b/pjmedia/include/pjmedia/sound.h
@@ -111,7 +111,45 @@ PJ_DECL(const pjmedia_snd_dev_info*) pjmedia_snd_get_dev_info(unsigned index);
 
 
 /**
- * Create a new audio stream for audio capture purpose.
+ * Create sound stream for both capturing audio and audio playback,  from the 
+ * same device. This is the recommended way to create simultaneous recorder 
+ * and player streams, because it should work on backends that does not allow
+ * a device to be opened more than once.
+ *
+ * @param rec_id	    Device index for recorder/capture stream, or
+ *			    -1 to use the first capable device.
+ * @param play_id	    Device index for playback stream, or -1 to use 
+ *			    the first capable 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 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(int rec_id,
+				      int play_id,
+				      unsigned clock_rate,
+				      unsigned channel_count,
+				      unsigned samples_per_frame,
+				      unsigned bits_per_sample,
+				      pjmedia_snd_rec_cb rec_cb,
+				      pjmedia_snd_play_cb play_cb,
+				      void *user_data,
+				      pjmedia_snd_stream **p_snd_strm);
+
+
+/**
+ * Create a unidirectional audio stream for capturing audio samples from
+ * the sound device.
  *
  * @param index		    Device index, or -1 to let the library choose the 
  *			    first available device.
@@ -128,7 +166,7 @@ PJ_DECL(const pjmedia_snd_dev_info*) pjmedia_snd_get_dev_info(unsigned index);
  *
  * @return		    PJ_SUCCESS on success.
  */
-PJ_DECL(pj_status_t) pjmedia_snd_open_recorder( int index,
+PJ_DECL(pj_status_t) pjmedia_snd_open_rec( int index,
 					   unsigned clock_rate,
 					   unsigned channel_count,
 					   unsigned samples_per_frame,
@@ -138,7 +176,8 @@ PJ_DECL(pj_status_t) pjmedia_snd_open_recorder( int index,
 					   pjmedia_snd_stream **p_snd_strm);
 
 /**
- * Create a new audio stream for playing audio samples.
+ * Create a unidirectional audio stream for playing audio samples to the
+ * sound device.
  *
  * @param index		    Device index, or -1 to let the library choose the 
  *			    first available device.
@@ -165,6 +204,7 @@ PJ_DECL(pj_status_t) pjmedia_snd_open_player( int index,
 					 void *user_data,
 					 pjmedia_snd_stream **p_snd_strm );
 
+
 /**
  * Start the stream.
  *
diff --git a/pjmedia/include/pjmedia/sound_port.h b/pjmedia/include/pjmedia/sound_port.h
index c7d1153d..53fa35a3 100644
--- a/pjmedia/include/pjmedia/sound_port.h
+++ b/pjmedia/include/pjmedia/sound_port.h
@@ -41,9 +41,42 @@ PJ_BEGIN_DECL
  */
 typedef struct pjmedia_snd_port pjmedia_snd_port;
 
+
 /**
- * Create sound device port for capturing audio streams from the sound device
- * with the specified parameters.
+ * Create bidirectional sound port for both capturing and playback of
+ * audio samples.
+ *
+ * @param pool		    Pool to allocate sound port structure.
+ * @param rec_id	    Device index for recorder/capture stream, or
+ *			    -1 to use the first capable device.
+ * @param play_id	    Device index for playback stream, or -1 to use 
+ *			    the first capable 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( pj_pool_t *pool,
+					      int rec_id,
+					      int play_id,
+					      unsigned clock_rate,
+					      unsigned channel_count,
+					      unsigned samples_per_frame,
+					      unsigned bits_per_sample,
+					      unsigned options,
+					      pjmedia_snd_port **p_port);
+
+/**
+ * Create unidirectional 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 
@@ -71,8 +104,8 @@ PJ_DECL(pj_status_t) pjmedia_snd_port_create_rec(pj_pool_t *pool,
 						 pjmedia_snd_port **p_port);
 					      
 /**
- * Create sound device port for playing audio streams with the specified 
- * parameters.
+ * Create unidirectional 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 
@@ -112,9 +145,20 @@ 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
+ * Retrieve the sound stream associated by this sound device port.
+ *
+ * @param snd_port	    The sound device port.
+ *
+ * @return		    The sound stream instance.
+ */
+PJ_DECL(pjmedia_snd_stream*) pjmedia_snd_port_get_snd_stream(
+						pjmedia_snd_port *snd_port);
+
+
+/**
+ * Connect a port to the sound device port. If the sound device port has 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
+ * the port's put_frame() function. If the sound device has a sound player
  * device, then this will start periodic function call to the port's
  * get_frame() function.
  *
diff --git a/pjmedia/include/pjmedia/types.h b/pjmedia/include/pjmedia/types.h
index ac3af4e8..8166b7cb 100644
--- a/pjmedia/include/pjmedia/types.h
+++ b/pjmedia/include/pjmedia/types.h
@@ -63,6 +63,23 @@ enum pjmedia_dir
 
 };
 
+/* Alternate names for media direction: */
+
+/**
+ * Direction is capturing audio frames.
+ */
+#define PJMEDIA_DIR_CAPTURE	PJMEDIA_DIR_ENCODING
+
+/**
+ * Direction is playback of audio frames.
+ */
+#define PJMEDIA_DIR_PLAYBACK	PJMEDIA_DIR_DECODING
+
+/**
+ * Direction is both capture and playback.
+ */
+#define PJMEDIA_DIR_CAPTURE_PLAYBACK	PJMEDIA_DIR_ENCODING_DECODING
+
 
 /**
  * Top level media type.