Merge branch 'devrel/eco82' of https://github.com/icywind/Basic-Video-Call into devrel/eco82

Author: zontan

Group-Video/OpenVideoCall-iOS-Objective-C/OpenVideoCall/LastmileViewController.m

@@ -8,7 +8,10 @@
 
 #import "LastmileViewController.h"
 
+/// LastmileViewController implements various last mille related delegate functions for AgoraRtcEngine.
+/// "Last mile" refers to the connection between the local device and Agora's edge server.
 @interface LastmileViewController () <AgoraRtcEngineDelegate>
+
 @property (weak, nonatomic) IBOutlet UILabel *qualityLabel;
 @property (weak, nonatomic) IBOutlet UILabel *rttLabel;
 @property (weak, nonatomic) IBOutlet UILabel *uplinkLabel;
@@ -64,6 +67,11 @@ - (void)addActivityView {
 }
 
 #pragma mark - AgoraRtcEngineDelegate
+
+/// Reports the last mile network quality of the local user once every two seconds before the user joins a channel.
+/// @param engine - RTC engine instance
+/// @param quality -The last mile network quality based on the uplink and dowlink packet loss rate and jitter. See list at:
+///  https://docs.agora.io/en/Video/API%20Reference/oc/Constants/AgoraNetworkQuality.html
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine lastmileQuality:(AgoraNetworkQuality)quality {
     NSString *string;
     switch (quality) {
@@ -80,6 +88,10 @@ - (void)rtcEngine:(AgoraRtcEngineKit *)engine lastmileQuality:(AgoraNetworkQuali
     self.qualityLabel.text = string;
 }
 
+/// Reports the last-mile network probe result.
+/// @param engine - RTC engine instance
+/// @param result - The uplink and downlink last-mile network probe test result, see list here:
+///   https://docs.agora.io/en/Video/API%20Reference/oc/Classes/AgoraLastmileProbeResult.html
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine lastmileProbeTestResult:(AgoraLastmileProbeResult *)result {
     self.rttLabel.text = [NSString stringWithFormat:@"%lu", (unsigned long)result.rtt];
     self.uplinkLabel.text = [NSString stringWithFormat:@"%lu", (unsigned long)result.uplinkReport.packetLossRate];

Group-Video/OpenVideoCall-iOS-Objective-C/OpenVideoCall/RoomViewController.m

@@ -308,30 +308,65 @@ - (void)leaveChannel {
 }
 
 #pragma mark - <AgoraRtcEngineDelegate>
+
+///  Occurs when the local user joins a specified channel.
+/// @param engine - RTC engine instance
+/// @param channel  - Channel name
+/// @param uid - User ID of the remote user sending the video stream.
+/// @param elapsed - Time elapsed (ms) from the local user calling the joinChannelByToken method until the SDK triggers this callback.
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine didJoinChannel:(NSString *)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed {
     [self info:[NSString stringWithFormat:@"Join channel: %@", channel]];
 }
 
+
+/// Occurs when the connection between the SDK and the server is interrupted.
+/// The SDK triggers this callback when it loses connection with the server for more than four seconds after a connection is established.
+/// After triggering this callback, the SDK tries reconnecting to the server. You can use this callback to implement pop-up reminders.
+/// @param engine - RTC engine instance
 - (void)rtcEngineConnectionDidInterrupted:(AgoraRtcEngineKit *)engine {
     [self alert:@"Connection Interrupted"];
 }
 
+/// Occurs when the SDK cannot reconnect to Agora’s edge server 10 seconds after its connection to the server is interrupted.
+/// @param engine - RTC engine instance
 - (void)rtcEngineConnectionDidLost:(AgoraRtcEngineKit *)engine {
     [self alert:@"Connection Lost"];
 }
 
+
+/// Reports an error during SDK runtime.
+/// @param engine - RTC engine instance
+/// @param errorCode - see complete list on this page
+///         https://docs.agora.io/en/Video/API%20Reference/oc/Constants/AgoraErrorCode.html
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine didOccurError:(AgoraErrorCode)errorCode {
     [self alert:[NSString stringWithFormat:@"Occur error: %ld", errorCode]];
 }
 
-// first remote video frame
+/// First remote video frame,Occurs when the first remote video frame is received and decoded.
+/// This callback is triggered in either of the following scenarios:
+///   * The remote user joins the channel and sends the video stream.
+///   * The remote user stops sending the video stream and re-sends it after 15 seconds. Possible reasons include:
+///   * The remote user leaves channel.
+///   * The remote user drops offline.
+///   * The remote user calls muteLocalVideoStream.
+///   * The remote user calls disableVideo.
+///
+/// @param engine - RTC engine instance
+/// @param uid - User ID of the remote user sending the video stream.
+/// @param size - Size of the first local video frame (width and height).
+/// @param elapsed - Time elapsed (ms) from the local user calling the joinChannelByToken method until the SDK triggers this callback.
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine firstRemoteVideoDecodedOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed {
     VideoSession *userSession = [self videoSessionOfUid:uid];
     userSession.size = size;
     [self.agoraKit setupRemoteVideo:userSession.canvas];
 }
 
-// first local video frame
+/// First local video frame - occurs when the first local video frame is displayed/rendered on the local video view.
+/// @param engine - RTC engine instance
+/// @param size - Size of the first local video frame (width and height).
+/// @param elapsed - Time elapsed (ms) from the local user calling the joinChannelByToken method until the SDK calls this callback.
+///             If the startPreview method is called before the joinChannelByToken method, then elapsed is the time elapsed from
+///             calling the startPreview method until the SDK triggers this callback.
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine firstLocalVideoFrameWithSize:(CGSize)size elapsed:(NSInteger)elapsed {
     if (self.videoSessions.count) {
         VideoSession *selfSession = self.videoSessions.firstObject;
@@ -341,7 +376,11 @@ - (void)rtcEngine:(AgoraRtcEngineKit *)engine firstLocalVideoFrameWithSize:(CGSi
     }
 }
 
-// user offline
+/// Occurs when a remote user (Communication)/host (Live Broadcast) leaves a channel.
+/// @param engine - RTC engine instance
+/// @param uid - User ID of the remote user sending the video stream.
+/// @param reason - reason why user went offline, see complete list of the reasons:
+///         https://docs.agora.io/en/Video/API%20Reference/oc/Constants/AgoraUserOfflineReason.html
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason {
     VideoSession *deleteSession;
     for (VideoSession *session in self.videoSessions) {
@@ -365,18 +404,25 @@ - (void)rtcEngine:(AgoraRtcEngineKit *)engine didOfflineOfUid:(NSUInteger)uid re
     }
 }
 
-// video muted
+/// Occurs when a remote user’s video stream playback pauses/resumes.
+/// @param engine - RTC engine instance
+/// @param muted - true if muted; false otherwise
+/// @param uid - User ID of the remote user sending the video stream.
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine didVideoMuted:(BOOL)muted byUid:(NSUInteger)uid {
     [self setVideoMuted:muted forUid:uid];
 }
 
-// remote stat
+/// Reports the statistics of the video stream from each remote user/host.
+/// @param engine - RTC engine instance
+/// @param stats - Statistics of the received remote video streams. See complete listing at
+///         https://docs.agora.io/en/Video/API%20Reference/oc/Classes/AgoraRtcRemoteVideoStats.html
 - (void)rtcEngine:(AgoraRtcEngineKit *)engine remoteVideoStats:(AgoraRtcRemoteVideoStats *)stats {
     VideoSession *session = [self fetchSessionOfUid:stats.uid];
     [session updateMediaInfo:CGSizeMake(stats.width, stats.height) fps:stats.rendererOutputFrameRate];
 }
 
-// audio mixing
+/// Occurs when the audio mixing file playback finishes.
+/// @param engine - RTC engine instance
 - (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit *)engine {
     self.isAudioMixing = NO;
 }