Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Api 6/6 #3711

Merged
merged 3 commits into from
Jul 22, 2024
Merged

Api 6/6 #3711

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions dita/RTC-NG/API/api_irtcengine_joinchannel.dita
Original file line number Diff line number Diff line change
Expand Up @@ -43,14 +43,16 @@
required int uid});</codeblock>
<codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
</section>
<section id="detailed_desc">
<title>详情</title>
<p conkeyref="joinChannel2/desc1" />
<p conkeyref="joinChannel2/desc2" />
<p conkeyref="joinChannel2/desc3" />
<note type="attention"><ul><li>用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 <apiname>mute</apiname> 方法实现。</li>
<li>如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。</li></ul></note> </section>
<section id="parameters">
<section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
<p>加入频道后,默认情况下用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并<b>影响计费</b>。如果想取消订阅,可以通过相应的 <apiname>mute</apiname> 方法实现。</p>
</section>
<section id="timing" deliveryTarget="details" conkeyref="joinChannel2/timing">
</section>
<section id="restriction" deliveryTarget="details" conkeyref="joinChannel2/restriction">
</section>
<section id="related" deliveryTarget="details" conkeyref="joinChannel2/related">
</section>
<section id="parameters" deliveryTarget="details">
<title>参数</title>
<parml>
<plentry conkeyref="joinChannel2/token">
Expand Down
51 changes: 32 additions & 19 deletions dita/RTC-NG/API/api_irtcengine_joinchannel2.dita
Original file line number Diff line number Diff line change
Expand Up @@ -46,29 +46,42 @@
required ChannelMediaOptions options});</codeblock>
<codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
</section>
<section id="detailed_desc">
<title>详情</title>
<p id="desc1">该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 App 不能互通。</p>
<p id="desc2">成功调用该方法加入频道后会触发以下回调:
<ul>
<li>本地会触发 <xref keyref="onJoinChannelSuccess" /> 和 <xref keyref="onConnectionStateChanged" /> 回调。</li>
<li>通信场景下的用户和直播场景下的主播加入频道后,远端会触发 <xref keyref="onUserJoined" /> 回调。</li>
</ul></p>
<p id="desc3">在网络状况不理想的情况下,客户端可能会与声网服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 <xref keyref="onRejoinChannelSuccess" /> 回调。</p>
<p props="native unreal unity cs">相比 <xref keyref="joinChannel1" />,该方法增加了 <parmname>options</parmname> 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 <parmname>options</parmname> 参数或相应的 <apiname>mute</apiname> 方法实现。</p>
<note id="note_cyz_w1l_mqb" type="attention">
<ul id="ul_sz1_y1l_mqb">
<li>该方法允许用户一次加入仅一个频道。</li>
<li>请务必确保用于生成 Token 的 App ID 和 <xref keyref="initialize" /> 方法初始化引擎时用的是同一个 App ID,否则使用 Token 加入频道失败。</li>
<li>如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。</li>
</ul> </note> </section>
<section id="parameters">
<section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
<p props="native unreal unity cs">相比 <xref keyref="joinChannel1" />,该方法增加了 <parmname>options</parmname> 参数,用于设置媒体选项,如是否在频道内发布音视频流等。用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并<b>影响计费</b>。如果想取消订阅,可以通过设置 <parmname>options</parmname> 参数或相应的 <apiname>mute</apiname> 方法实现。</p>
<p id="flutter rn electron bp">该方法可以在加入频道时设置媒体选项,如是否在频道内发布音视频流等。用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并<b>影响计费</b>。如果想取消订阅,可以通过设置 <parmname>options</parmname> 参数或相应的 <apiname>mute</apiname> 方法实现。</p>
</section>
<section id="timing" deliveryTarget="details">
<title>调用时机</title>
<p>该方法需要在 <xref keyref="initialize"/> 之后再调用。</p>
</section>
<section id="restriction" deliveryTarget="details">
<title>调用限制</title>
<ul>
<li>该方法仅支持用户一次加入一个频道。</li>
<li>使用不同 App ID 的 App 不能互通。</li>
<li>加入频道前,请确保用于生成 Token 的 App ID 和调用 <xref keyref="initialize" /> 方法初始化引擎时使用的是同一个 App ID,否则使用 Token 加入频道会失败。</li>
</ul>
</section>
<section id="related" deliveryTarget="details">
<title>相关回调</title>
<p>成功调用该方法加入频道后会触发以下回调:
<ul>
<li>本地会触发 <xref keyref="onJoinChannelSuccess" /> 和 <xref keyref="onConnectionStateChanged" /> 回调。</li>
<li>通信场景下的用户和直播场景下的主播加入频道后,远端会触发 <xref keyref="onUserJoined" /> 回调。</li>
</ul></p>
<p>在网络状况不理想的情况下,客户端可能会与声网服务器失去连接,此时 SDK 会自动尝试重连,重连成功后,本地会触发 <xref keyref="onRejoinChannelSuccess" /> 回调。</p>
</section>
<section id="parameters" deliveryTarget="details">
<title>参数</title>
<parml>
<plentry id="token">
<pt>token</pt>
<pd>在服务端生成的用于鉴权的动态密钥。详见<xref keyref="guide-token"/>。
<note type="note">如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 <xref keyref="wildcard-token"/>。</note></pd>
<note type="note">
<ul>
<li>(推荐)如果你的项目开启了安全模式,即选择 APP ID + Token 为鉴权机制,则该参数为必填。</li>
<li>如果你的项目仅开启调试模式,即选择 APP ID 为鉴权机制,则无需填入 Token 即可加入频道。成功加入频道 24 小时后会自动退出该频道。</li>
<li>如果你需要同时加入多个频道或在频道间频繁切换,声网推荐你使用通配 Token 以避免每加入一个新的频道都需向服务端申请一个新的 Token,详见 <xref keyref="wildcard-token"/>。</li></ul></note></pd>
</plentry>
<plentry id="channelID">
<pt>channelId</pt>
Expand Down Expand Up @@ -113,7 +126,7 @@
<li>-2:传入的参数无效。例如,使用了不合法的 Token,<parmname>uid</parmname> 参数未设置为整型,或 <xref keyref="ChannelMediaOptions" /> 成员值不合法。你需要填入有效的参数,重新加入频道。</li>
<li>-3:<xref keyref="IRtcEngine" /> 对象初始化失败。你需要重新初始化 <apiname keyref="IRtcEngine" /> 对象。</li>
<li>-7:<apiname keyref="IRtcEngine" /> 对象尚未初始化。你需要在调用该方法前成功初始化 <apiname keyref="IRtcEngine" /> 对象。</li>
<li>-8:<apiname keyref="IRtcEngine" /> 对象内部状态错误。<ph props="android cpp apple framework">可能的原因是:调用 <xref keyref="startEchoTest3" /> 开始通话回路测试后,未调用 <xref keyref="stopEchoTest" /> 停止测试就调用该方法加入频道。你需要在该方法前调用 <apiname keyref="stopEchoTest" />。</ph></li>
<li>-8:<apiname keyref="IRtcEngine" /> 对象内部状态错误。可能的原因是:调用 <xref keyref="startEchoTest3" /> 开始通话回路测试后,未调用 <xref keyref="stopEchoTest" /> 停止测试就调用该方法加入频道。你需要在该方法前调用 <apiname keyref="stopEchoTest" />。</li>
<li>-17:加入频道被拒绝。可能的原因是用户已经在频道中。建议通过 <xref keyref="onConnectionStateChanged" /> 回调判断用户是否在频道中。除收到 <apiname keyref="CONNECTION_STATE_DISCONNECTED" />(1) 状态外,不要再次调用该方法加入频道。</li>
<li>-102:频道名无效。你需要在 <parmname>channelId</parmname> 中填入有效的频道名,重新加入频道。</li>
<li>-121:用户 ID 无效。你需要在 <parmname>uid</parmname> 中填入有效的用户 ID,重新加入频道。</li>
Expand Down
34 changes: 11 additions & 23 deletions dita/RTC-NG/API/api_irtcengine_joinchannelwithuseraccount.dita
Original file line number Diff line number Diff line change
Expand Up @@ -43,17 +43,17 @@
ChannelMediaOptions? options});</codeblock>
<codeblock props="reserve" outputclass="language-cpp"></codeblock></p>
</section>
<section id="detailed_desc">
<title>详情</title>
<p>该方法允许本地用户使用 User Account 和 Token 加入频道。成功加入频道后,会触发以下回调:
<ul>
<li>本地:<xref keyref="onLocalUserRegistered" />、<xref keyref="onJoinChannelSuccess" /> 和 <xref keyref="onConnectionStateChanged" /> 回调。</li>
<li>通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 <xref keyref="onUserJoined" /> 和 <xref keyref="onUserInfoUpdated" /> 回调。</li>
</ul></p>
<section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
<p conkeyref="joinChannelWithUserAccount2/account"></p>
<p>用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 <apiname>mute</apiname> 方法实现。</p>
<note type="attention" id="note"><ul><li>为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。</li>
<li>如果你的项目仅开启调试模式(即选择 APP ID 为鉴权机制),成功加入频道 24 小时后会自动退出该频道。</li></ul></note> </section>
<section id="parameters">
<note type="attention" conkeyref="joinChannelWithUserAccount2/note">
</note> </section>
<section id="timing" deliveryTarget="details" conkeyref="joinChannel2/timing">
</section>
<section id="restriction" deliveryTarget="details" conkeyref="joinChannel2/restriction">
<section id="related" deliveryTarget="details" conkeyref="joinChannelWithUserAccount2/related">
</section>
<section id="parameters" deliveryTarget="details">
<title>参数</title>
<parml>
<plentry conkeyref="joinChannel2/token">
Expand All @@ -77,18 +77,6 @@
</plentry>
</parml>
</section>
<section id="return_values">
<title><ph keyref="return-section-title"/></title>
<p props="flutter">方法成功调用时,无返回值;方法调用失败时,会抛出 <xref keyref="AgoraRtcException"/> 异常,你需要捕获异常并进行处理。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph></p>
<ul props="native unreal bp unity rn electron cs">
<li>0: 方法调用成功。</li>
<li>&lt; 0: 方法调用失败。<ph props="cn">详见<xref keyref="error-code-link"/>了解详情和解决建议。</ph>
<ul>
<li>-2: 参数无效。</li>
<li>-3: SDK 初始化失败,请尝试重新初始化 SDK。</li>
<li>-5: 调用被拒绝。</li>
<li>-17: 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 <xref keyref="IRtcEngine" /> 频道,当已经加入 <xref keyref="IRtcEngine" /> 频道的用户使用有效的频道名再次调用 <xref keyref="IRtcEngine" /> 类中的加入频道方法时,会返回此错误码。</li>
</ul></li>
</ul> </section>
<section id="return_values" conkeyref="joinChannel2/return_values"></section>
</refbody>
</reference>
32 changes: 20 additions & 12 deletions dita/RTC-NG/API/api_irtcengine_joinchannelwithuseraccount2.dita
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="api_irtcengine_joinchannelwithuseraccount2">
<title><ph keyref="joinChannelWithUserAccount2" /></title>
<shortdesc id="short"><ph id="shortdesc">使用 User Account 和 Token 加入频道,并设置是否自动订阅音频或视频流。</ph></shortdesc>
<shortdesc id="short"><ph id="shortdesc">使用 User Account 和 Token 加入频道,并设置频道媒体选项。</ph></shortdesc>
<prolog>
<metadata>
<keywords>
Expand Down Expand Up @@ -47,17 +47,25 @@
required String userAccount,
ChannelMediaOptions? options});</codeblock></p>
</section>
<section id="detailed_desc">
<title>详情</title>
<p id="desc1">该方法允许本地用户使用 User Account 加入频道。成功加入频道后,会触发以下回调:
<ul>
<li>本地:<xref keyref="onLocalUserRegistered" />、<xref keyref="onJoinChannelSuccess" /> 和 <xref keyref="onConnectionStateChanged" /> 回调。</li>
<li>远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 <xref keyref="onUserJoined" /> 和 <xref keyref="onUserInfoUpdated" /> 回调。</li>
</ul></p>
<p id="desc2">用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 <apiname>mute</apiname> 方法实现。</p>
<p props="android ios mac cpp unreal">相比 <xref keyref="joinChannelWithUserAccount1" />,该方法加了 <parmname>options</parmname> 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 <parmname>options</parmname> 参数或相应的 <apiname>mute</apiname> 方法实现。</p>
<note id="note" conkeyref="joinChannelWithUserAccount1/note"></note> </section>
<section id="parameters">
<section id="detailed_desc" deliveryTarget="details" otherprops="no-title">
<p id="account">调用该方法前,如果你未调用 <xref keyref="registerLocalUserAccount"/> 注册一个 User Account,调用该方法加入频道时,SDK 会自动为你创建一个 User Account。先调用 <xref keyref="registerLocalUserAccount"/> 方法注册 Account,再调用此方法加入频道,可以缩短进入频道的时间。</p>
<p props="flutter rn electron bp">用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并<b>影响计费</b>。如果想取消订阅,可以通过调用相应的 <apiname>mute</apiname> 方法实现。</p>
<p props="android ios mac cpp unreal cs unity">相比 <xref keyref="joinChannelWithUserAccount1" />,该方法增加了 <parmname>options</parmname> 参数,用于在加入频道时设置媒体选项,如是否在频道内发布音视频流等。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并<b>影响计费</b>。如果想取消订阅,可以通过设置 <parmname>options</parmname> 参数或相应的 <apiname>mute</apiname> 方法实现。</p>
<note type="attention" id="note">为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。</note>
</section>
<section id="timing" deliveryTarget="details" conkeyref="joinChannel2/timing">
</section>
<section id="restriction" deliveryTarget="details" conkeyref="joinChannel2/restriction">
</section>
<section id="related" deliveryTarget="details">
<title>相关回调</title>
<p>成功加入频道后,会触发以下回调:
<ul>
<li>本地:<xref keyref="onLocalUserRegistered" />、<xref keyref="onJoinChannelSuccess" /> 和 <xref keyref="onConnectionStateChanged" /> 回调。</li>
<li>远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 <xref keyref="onUserJoined" /> 和 <xref keyref="onUserInfoUpdated" /> 回调。</li>
</ul></p>
</section>
<section id="parameters" deliveryTarget="details">
<title>参数</title>
<parml>
<plentry conkeyref="joinChannel2/token">
Expand Down
Loading
Loading