upgrade sdk to 3.2.1

Author: Xia Ning

Android/APIExample/lib-component/build.gradle

@@ -35,7 +35,7 @@ dependencies {
 //    api 'io.agora.rtc:full-sdk:3.0.0'
 //    api 'io.agora.rtc:full-sdk:3.1.2'
 
-    api 'io.agora.rtc:full-sdk:3.2.0'
+    api 'io.agora.rtc:full-sdk:3.2.1'
     api 'io.agora:agoraplayer:1.1.2'
 
 }

Android/APIExample/lib-raw-data/src/main/cpp/include/AgoraBase.h

@@ -159,10 +159,18 @@ enum WARN_CODE_TYPE
     /** 122: Try connecting to another server.
     */
     WARN_OPEN_CHANNEL_TRY_NEXT_VOS = 122,
-    /** 131: The channel connection cannot be recovered. */
+    /** 131: The channel connection cannot be recovered.
+     */
     WARN_CHANNEL_CONNECTION_UNRECOVERABLE = 131,
+    /** 132: The IP address has changed.
+     */
     WARN_CHANNEL_CONNECTION_IP_CHANGED = 132,
+    /** 133: The port has changed.
+     */
     WARN_CHANNEL_CONNECTION_PORT_CHANGED = 133,
+    /** 134: The socket error occurs, try to rejoin channel.
+     */
+    WARN_CHANNEL_SOCKET_ERROR = 134,
     /** 701: An error occurs in opening the audio mixing file.
     */
     WARN_AUDIO_MIXING_OPEN_ERROR = 701,
@@ -235,13 +243,13 @@ enum WARN_CODE_TYPE
      * - Update the sound card drive.
      */
     WARN_ADM_WIN_CORE_IMPROPER_CAPTURE_RELEASE = 1324,
-    /** 1610: Super-resolution warning: The original video dimensions of the remote user exceed 640 * 480.
+    /** 1610: The origin resolution of the remote video is beyond the range where the super-resolution algorithm can be applied.
     */
     WARN_SUPER_RESOLUTION_STREAM_OVER_LIMITATION = 1610,
-    /** 1611: Super-resolution warning: Another user is using super resolution.
+    /** 1611: Another user is already using the super-resolution algorithm.
     */
     WARN_SUPER_RESOLUTION_USER_COUNT_OVER_LIMITATION = 1611,
-    /** 1612: The device is not supported.
+    /** 1612: The device does not support the super-resolution algorithm.
     */
     WARN_SUPER_RESOLUTION_DEVICE_NOT_SUPPORTED = 1612,
     /// @cond
@@ -306,8 +314,13 @@ enum ERROR_CODE_TYPE
     ERR_NET_NOBUFS = 15,
     /** 17: The request to join the channel is rejected.
      *
-     * - This error usually occurs when the user is already in the channel, and still calls the method to join the channel, for example, \ref agora::rtc::IRtcEngine::joinChannel "joinChannel".
-     * - This error usually occurs when the user tries to join a channel during a call test (\ref agora::rtc::IRtcEngine::startEchoTest "startEchoTest"). Once you call \ref agora::rtc::IRtcEngine::startEchoTest "startEchoTest", you need to call \ref agora::rtc::IRtcEngine::stopEchoTest "stopEchoTest" before joining a channel.
+     * - This error usually occurs when the user is already in the channel, and still calls the method to join the
+     * channel, for example, \ref agora::rtc::IRtcEngine::joinChannel "joinChannel".
+     * - This error usually occurs when the user tries to join a channel
+     * during \ref agora::rtc::IRtcEngine::startEchoTest "startEchoTest". Once you
+     * call \ref agora::rtc::IRtcEngine::startEchoTest "startEchoTest", you need to
+     * call \ref agora::rtc::IRtcEngine::stopEchoTest "stopEchoTest" before joining a channel.
+     * - The user tries to join the channel with a token that is expired.
      */
     ERR_JOIN_CHANNEL_REJECTED = 17,
     /** 18: The request to leave the channel is rejected.
@@ -382,7 +395,7 @@ enum ERROR_CODE_TYPE
     /** 120: Decryption fails. The user may have used a different encryption password to join the channel. Check your settings or try rejoining the channel.
      */
     ERR_DECRYPTION_FAILED = 120,
-    /** 123: The client is banned by the server.
+    /** 123: The user is banned by the server. This error occurs when the user is kicked off the channel from the server.
      */
     ERR_CLIENT_IS_BANNED_BY_SERVER = 123,
     /** 124: Incorrect watermark file parameter.
@@ -589,27 +602,27 @@ enum ERROR_CODE_TYPE
      * session category is not compatible with the settings of the Audio Unit.
     */
     ERR_ADM_IOS_VPIO_RESTART_FAIL = 1214,
-    /// @cond
+
     ERR_ADM_IOS_SET_RENDER_CALLBACK_FAIL = 1219,
-    /// @endcond
+
     /** **DEPRECATED** */
     ERR_ADM_IOS_SESSION_SAMPLERATR_ZERO = 1221,
-    /** 1301: Audio device module: An audio driver abnomality or a
+    /** 1301: Audio device module: An audio driver abnormality or a
      * compatibility issue occurs. Solutions: Disable and restart the audio
      * device, or reboot the system.*/
     ERR_ADM_WIN_CORE_INIT = 1301,
-    /** 1303: Audio device module: A recording driver abnomality or a
+    /** 1303: Audio device module: A recording driver abnormality or a
      * compatibility issue occurs. Solutions: Disable and restart the audio
      * device, or reboot the system. */
     ERR_ADM_WIN_CORE_INIT_RECORDING = 1303,
-    /** 1306: Audio device module: A playout driver abnomality or a
+    /** 1306: Audio device module: A playout driver abnormality or a
      * compatibility issue occurs. Solutions: Disable and restart the audio
      * device, or reboot the system. */
     ERR_ADM_WIN_CORE_INIT_PLAYOUT = 1306,
     /** 1307: Audio device module: No audio device is available. Solutions:
      * Plug in a proper audio device. */
     ERR_ADM_WIN_CORE_INIT_PLAYOUT_NULL = 1307,
-    /** 1309: Audio device module: An audio driver abnomality or a
+    /** 1309: Audio device module: An audio driver abnormality or a
      * compatibility issue occurs. Solutions: Disable and restart the audio
      * device, or reboot the system. */
     ERR_ADM_WIN_CORE_START_RECORDING = 1309,

Android/APIExample/lib-raw-data/src/main/cpp/include/IAgoraMediaEngine.h

@@ -48,7 +48,7 @@ class IAudioFrameObserver {
      The size of the data buffer is as follows: `buffer` = `samples` × `channels` × `bytesPerSample`.
      */
     void* buffer;  //data buffer
-      /** The timestamp of the external audio frame. You can use this parameter for the following purposes:
+      /** The timestamp (ms) of the external audio frame. You can use this parameter for the following purposes:
        - Restore the order of the captured audio frame.
        - Synchronize audio and video frames in video-related scenarios, including where external video sources are used.
        */
@@ -124,7 +124,7 @@ class IAudioFrameObserver {
   /** Gets the before-mixing playback audio frame from multiple channels.
 
   After you successfully register the audio frame observer, if you set the return
-  value of isMultipleChannelFrameWanted as true, the SDK triggers this callback each
+  value of \ref IAudioFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each
   time it receives a before-mixing audio frame from any of the channel.
 
   @param channelId The channel ID of this audio frame.
@@ -207,7 +207,7 @@ class IVideoFrameObserver {
     /** Set the rotation of this frame before rendering the video. Supports 0, 90, 180, 270 degrees clockwise.
      */
     int rotation; // rotation of this frame (0, 90, 180, 270)
-      /** The timestamp of the external audio frame. It is mandatory. You can use this parameter for the following purposes:
+      /** The timestamp (ms) of the external audio frame. It is mandatory. You can use this parameter for the following purposes:
        - Restore the order of the captured audio frame.
        - Synchronize audio and video frames in video-related scenarios, including scenarios where external video sources are used.
      @note This timestamp is for rendering the video stream, and not for capturing the video stream.
@@ -225,7 +225,8 @@ class IVideoFrameObserver {
    * After pre-processing, you can send the processed video data back to the SDK by setting the `videoFrame` parameter in this callback.
    *
    * @note
-   * This callback does not support sending processed RGBA video data back to the SDK.
+   * - This callback does not support sending processed RGBA video data back to the SDK.
+   * - The video data that this callback gets has not been pre-processed, without the watermark, the cropped content, the rotation, and the image enhancement.
    *
    * @param videoFrame Pointer to VideoFrame.
    * @return Whether or not to ignore the current video frame if the pre-processing fails:
@@ -352,12 +353,12 @@ class IVideoFrameObserver {
 
    In the multi-channel scenario, if you want to get video data from multiple channels,
    set the return value of this callback as true. After that, the SDK triggers the
-   onRenderVideoFrameEx callback to send you
+   \ref IVideoFrameObserver::onRenderVideoFrameEx "onRenderVideoFrameEx" callback to send you
    the video data from various channels. You can also get the channel ID of each video frame.
 
    @note
    - Once you set the return value of this callback as true, the SDK triggers only the `onRenderVideoFrameEx` callback to
-   send the video frame. onRenderVideoFrame will not be triggered. In the multi-channel scenario, Agora recommends setting the return value as true.
+   send the video frame. \ref IVideoFrameObserver::onRenderVideoFrame "onRenderVideoFrame" will not be triggered. In the multi-channel scenario, Agora recommends setting the return value as true.
    - If you set the return value of this callback as false, the SDK triggers only the `onRenderVideoFrame` callback to send the video data.
    @return
    - `true`: Receive video data from multiple channels.
@@ -368,7 +369,7 @@ class IVideoFrameObserver {
   /** Gets the video frame from multiple channels.
 
    After you successfully register the video frame observer, if you set the return value of
-   isMultipleChannelFrameWanted as true, the SDK triggers this callback each time it receives a video frame
+   \ref IVideoFrameObserver::isMultipleChannelFrameWanted "isMultipleChannelFrameWanted" as true, the SDK triggers this callback each time it receives a video frame
    from any of the channel.
 
    You can process the video data retrieved from this callback according to your scenario, and send the
@@ -456,7 +457,7 @@ class IVideoFrame {
   /** Retrieves the height of the frame.
    */
   virtual int height() const = 0;
-  /** Retrieves the timestamp (90 ms) of the frame.
+  /** Retrieves the timestamp (ms) of the frame.
    */
   virtual unsigned int timestamp() const = 0;
   /** Retrieves the render time (ms).
@@ -540,6 +541,8 @@ struct ExternalVideoFrame
     };
 
     /** The video pixel format.
+     *
+     * @note The SDK does not support the alpha channel, and discards any alpha value passed to the SDK.
      */
     enum VIDEO_PIXEL_FORMAT
     {
@@ -602,9 +605,17 @@ struct ExternalVideoFrame
     /** [Raw data related parameter] The clockwise rotation of the video frame. You can set the rotation angle as 0, 90, 180, or 270. The default value is 0.
      */
     int rotation;
-    /** Timestamp of the incoming video frame (ms). An incorrect timestamp results in frame loss or unsynchronized audio and video.
+    /** Timestamp (ms) of the incoming video frame. An incorrect timestamp results in frame loss or unsynchronized audio and video.
      */
     long long timestamp;
+
+    ExternalVideoFrame()
+    :cropLeft(0)
+    ,cropTop(0)
+    ,cropRight(0)
+    ,cropBottom(0)
+    ,rotation(0)
+    {}
 };
 
 class IMediaEngine {
@@ -615,6 +626,8 @@ class IMediaEngine {
 
    This method is used to register an audio frame observer object (register a callback). This method is required to register callbacks when the engine is required to provide an \ref IAudioFrameObserver::onRecordAudioFrame "onRecordAudioFrame" or \ref IAudioFrameObserver::onPlaybackAudioFrame "onPlaybackAudioFrame" callback.
 
+   @note Ensure that you call this method before joining a channel.
+
    @param observer Audio frame observer object instance. See IAudioFrameObserver. Set the value as NULL to release the
    audio observer object. Agora recommends calling `registerAudioFrameObserver(NULL)` after receiving the \ref agora::rtc::IRtcEngineEventHandler::onLeaveChannel "onLeaveChannel" callback.
 
@@ -624,19 +637,21 @@ class IMediaEngine {
    */
   virtual int registerAudioFrameObserver(IAudioFrameObserver* observer) = 0;
   /** Registers a video frame observer object.
-
-   You need to implement the IVideoFrameObserver class in this method, and register callbacks according to your scenarios.
-
-   After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.
-
-   @note When handling the video data returned in the callbacks, pay attention to the changes in the `width` and `height` parameters,
-   which may be adapted under the following circumstances:
-   - When the network condition deteriorates, the video resolution decreases incrementally.
-   - If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes.
-   @param observer Video frame observer object instance. If NULL is passed in, the registration is canceled.
-   @return
-   - 0: Success.
-   - < 0: Failure.
+   *
+   * You need to implement the IVideoFrameObserver class in this method, and register callbacks according to your scenarios.
+   *
+   * After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.
+   *
+   * @note
+   * - When handling the video data returned in the callbacks, pay attention to the changes in the `width` and `height` parameters,
+   * which may be adapted under the following circumstances:
+   *  - When the network condition deteriorates, the video resolution decreases incrementally.
+   *  - If the user adjusts the video profile, the resolution of the video returned in the callbacks also changes.
+   * - Ensure that you call this method before joining a channel.
+   * @param observer Video frame observer object instance. If NULL is passed in, the registration is canceled.
+   * @return
+   * - 0: Success.
+   * - < 0: Failure.
    */
   virtual int registerVideoFrameObserver(IVideoFrameObserver* observer) = 0;
   /** **DEPRECATED** */
@@ -688,9 +703,8 @@ class IMediaEngine {
    * "onPlaybackAudioFrame" callback and the
    * \ref agora::media::IMediaEngine::pullAudioFrame "pullAudioFrame" method is as
    * follows:
-   *  - `onPlaybackAudioFrame`: The SDK sends the audio data to the app once
-   * every 10 ms. Any delay in processing the audio frames may result in audio
-   * jitter.
+   *  - `onPlaybackAudioFrame`: The SDK sends the audio data to the app through this callback.
+   * Any delay in processing the audio frames may result in audio jitter.
    *  - `pullAudioFrame`: The app pulls the remote audio data. After setting the
    * audio data parameters, the SDK adjusts the frame buffer and avoids
    * problems caused by jitter in the external audio playback.
@@ -705,6 +719,8 @@ class IMediaEngine {
   virtual int pullAudioFrame(IAudioFrameObserver::AudioFrame* frame) = 0;
     /** Configures the external video source.
 
+    @note Ensure that you call this method before joining a channel.
+
     @param enable Sets whether to use the external video source:
     - true: Use the external video source.
     - false: (Default) Do not use the external video source.