Changeset 2506 for pjproject/trunk/pjsip/include/pjsua-lib/pjsua.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)
• pjsip/include/pjsua-lib/pjsua.h (modified) (8 diffs)

pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

@@ -4201 +4201 @@
     unsigned            ec_tail_len;
 
+    /**
+     * Audio capture buffer length, in milliseconds.
+     *
+     * Default: PJMEDIA_SND_DEFAULT_REC_LATENCY
+     */
+    unsigned            snd_rec_latency;
+
+    /**
+     * Audio playback buffer length, in milliseconds.
+     *
+     * Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY
+     */
+    unsigned            snd_play_latency;
+
     /** 
      * Jitter buffer initial prefetch delay in msec. The value must be
@@ -4273 +4287 @@
     /**
      * Specify idle time of sound device before it is automatically closed,
-     * in seconds.
-     *
-     * Default : -1 (Disable the auto-close feature of sound device)
+     * in seconds. Use value -1 to disable the auto-close feature of sound
+     * device
+     *
+     * Default : 1
      */
     int                 snd_auto_close_time;
@@ -4788 +4803 @@
 
 /**
- * Enum all sound devices installed in the system.
+ * Enum all audio devices installed in the system.
  *
  * @param info          Array of info to be initialized.
@@ -4796 +4811 @@
  *
  * @return              PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsua_enum_aud_devs(pjmedia_aud_dev_info info[],
+                                         unsigned *count);
+
+/**
+ * Enum all sound devices installed in the system (old API).
+ *
+ * @param info          Array of info to be initialized.
+ * @param count         On input, specifies max elements in the array.
+ *                      On return, it contains actual number of elements
+ *                      that have been initialized.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
  *
  *
@@ -4807 +4835 @@
 PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[],
                                          unsigned *count);
-
-
 
 /**
@@ -4880 +4906 @@
 
 /**
- * Configure the echo canceller tail length of the sound port.
+ * Change the echo cancellation settings.
+ *
+ * The behavior of this function depends on whether the sound device is
+ * currently active, and if it is, whether device or software AEC is 
+ * being used. 
+ *
+ * If the sound device is currently active, and if the device supports AEC,
+ * this function will forward the change request to the device and it will
+ * be up to the device on whether 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. In all cases,
+ * the setting will be saved for future opening of the sound device.
+ *
+ * If the sound device is not currently active, this will only change the
+ * default AEC settings and the setting will be applied next time the 
+ * sound device is opened.
  *
  * @param tail_ms       The tail length, in miliseconds. Set to zero to
@@ -4898 +4939 @@
 
 /**
- * Get current echo canceller tail length.
+ * Get current echo canceller tail length. 
  *
  * @param p_tail_ms     Pointer to receive the tail length, in miliseconds. 
@@ -4912 +4953 @@
 PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms);
 
+
+/**
+ * Check whether the sound device is currently active. The sound device
+ * may be inactive if the application has set the auto close feature to
+ * non-zero (the snd_auto_close_time setting in #pjsua_media_config), or
+ * if null sound device or no sound device has been configured via the
+ * #pjsua_set_no_snd_dev() function.
+ */
+PJ_DECL(pj_bool_t) pjsua_snd_is_active(void);
+
+    
+/**
+ * Configure sound device setting to the sound device being used. If sound 
+ * device is currently active, the function will forward the setting to the
+ * sound device instance to be applied immediately, if it supports it. 
+ *
+ * The setting will be saved for future opening of the sound device, if the 
+ * "keep" argument is set to non-zero. If the sound device is currently
+ * inactive, and the "keep" argument is false, this function will return
+ * error.
+ * 
+ * Note that in case the setting is kept for future use, it will be applied
+ * to any devices, even when application has changed the sound device to be
+ * used.
+ *
+ * Note also that the echo cancellation setting should be set with 
+ * #pjsua_set_ec() API instead.
+ *
+ * See also #pjmedia_aud_stream_set_cap() for more information about setting
+ * an audio device capability.
+ *
+ * @param cap           The sound device setting to change.
+ * @param pval          Pointer to value. Please see #pjmedia_aud_dev_cap
+ *                      documentation about the type of value to be 
+ *                      supplied for each setting.
+ * @param keep          Specify whether the setting is to be kept for future
+ *                      use.
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsua_snd_set_setting(pjmedia_aud_dev_cap cap,
+                                           const void *pval,
+                                           pj_bool_t keep);
+
+/**
+ * Retrieve a sound device setting. If sound device is currently active,
+ * the function will forward the request to the sound device. If sound device
+ * is currently inactive, and if application had previously set the setting
+ * and mark the setting as kept, then that setting will be returned.
+ * Otherwise, this function will return error.
+ *
+ * Note that echo cancellation settings should be retrieved with 
+ * #pjsua_get_ec_tail() API instead.
+ *
+ * @param cap           The sound device setting to retrieve.
+ * @param pval          Pointer to receive the value. 
+ *                      Please see #pjmedia_aud_dev_cap documentation about
+ *                      the type of value to be supplied for each setting.
+ *
+ * @return              PJ_SUCCESS on success or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsua_snd_get_setting(pjmedia_aud_dev_cap cap,
+                                           void *pval);