Changeset 2506 for pjproject/trunk/pjmedia/include/pjmedia/sound_port.h

Timestamp:

Mar 12, 2009 6:11:37 PM (14 years ago)

Author:

bennylp

Message:

(Major) Task #737 and #738: integration of APS-Direct and Audiodev from aps-direct branch to trunk.

Location:

pjproject/trunk

Files:

• . (modified) (1 prop)
• pjmedia/include/pjmedia/sound_port.h (modified) (4 diffs)

pjproject/trunk/pjmedia/include/pjmedia/sound_port.h

@@ -25 +25 @@
  * @brief Media port connection abstraction to sound device.
  */
-#include <pjmedia/sound.h>
+#include <pjmedia-audiodev/audiodev.h>
 #include <pjmedia/port.h>
 
@@ -160 +160 @@
                                                     unsigned options,
                                                     pjmedia_snd_port **p_port);
-                                              
+
+
+/**
+ * Create sound device port according to the specified parameters.
+ *
+ * @param pool              Pool to allocate sound port structure.
+ * @param prm               Sound device settings.
+ * @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_create2(pj_pool_t *pool,
+                                              const pjmedia_aud_param *prm,
+                                              pjmedia_snd_port **p_port);
+
 
 /**
@@ -180 +195 @@
  * @return                  The sound stream instance.
  */
-PJ_DECL(pjmedia_snd_stream*) pjmedia_snd_port_get_snd_stream(
+PJ_DECL(pjmedia_aud_stream*) pjmedia_snd_port_get_snd_stream(
                                                 pjmedia_snd_port *snd_port);
 
 
 /**
- * Configure the echo cancellation tail length. By default, echo canceller
- * is enabled in the sound device with the default tail length. After the
- * sound port is created, application can query the current echo canceller
- * tail length by calling #pjmedia_snd_port_get_ec_tail.
- *
- * Note that you should only change the EC settings when the sound port
- * is not connected to any downstream ports, otherwise race condition may
- * occur.
+ * Change the echo cancellation settings. The echo cancellation settings 
+ * should have been specified when this sound port was created, by setting
+ * the appropriate fields in the pjmedia_aud_param, because not all sound
+ * device implementation supports changing the EC setting once the device
+ * has been opened.
+ *
+ * The behavior of this function depends on whether device or software AEC
+ * is being used. If the device supports AEC, this function will forward
+ * the change request to the device and it will be up to the device whether
+ * to support the request. If software AEC is being used (the software EC
+ * will be used if the device does not support AEC), this function will
+ * change the software EC settings.
  *
  * @param snd_port          The sound device port.
@@ -200 +219 @@
  *                          be disabled.
  * @param options           The options to be passed to #pjmedia_echo_create().
+ *                          This is only used if software EC is being used.
  *
  * @return                  PJ_SUCCESS on success.