Public 成员函数

virtual ~IChannel ()
 
virtual int release ()=0
 
virtual int setChannelEventHandler (IChannelEventHandler *channelEh)=0
 
virtual int joinChannel (const char *token, const char *info, uid_t uid, const ChannelMediaOptions &options)=0
 
virtual int joinChannelWithUserAccount (const char *token, const char *userAccount, const ChannelMediaOptions &options)=0
 
virtual int leaveChannel ()=0
 
virtual int publish ()=0
 
virtual int unpublish ()=0
 
virtual const char * channelId ()=0
 
virtual int getCallId (agora::util::AString &callId)=0
 
virtual int renewToken (const char *token)=0
 
virtual int setEncryptionSecret (const char *secret)=0
 
virtual int setEncryptionMode (const char *encryptionMode)=0
 
virtual int enableEncryption (bool enabled, const EncryptionConfig &config)=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role)=0
 
virtual int setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
 
virtual int setRemoteVoicePosition (uid_t uid, double pan, double gain)=0
 
virtual int setRemoteRenderMode (uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0
 
virtual int setDefaultMuteAllRemoteAudioStreams (bool mute)=0
 
virtual int setDefaultMuteAllRemoteVideoStreams (bool mute)=0
 
virtual int muteAllRemoteAudioStreams (bool mute)=0
 
virtual int adjustUserPlaybackSignalVolume (uid_t userId, int volume)=0
 
virtual int muteRemoteAudioStream (uid_t userId, bool mute)=0
 
virtual int muteAllRemoteVideoStreams (bool mute)=0
 
virtual int muteRemoteVideoStream (uid_t userId, bool mute)=0
 
virtual int setRemoteVideoStreamType (uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addPublishStreamUrl (const char *url, bool transcodingEnabled)=0
 
virtual int removePublishStreamUrl (const char *url)=0
 
virtual int setLiveTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0
 
virtual int removeInjectStreamUrl (const char *url)=0
 
virtual int startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0
 
virtual int stopChannelMediaRelay ()=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 

详细描述

构造及析构函数说明

◆ ~IChannel()

virtual agora::rtc::IChannel::~IChannel ( )
inlinevirtual

成员函数说明

◆ release()

virtual int agora::rtc::IChannel::release ( )
pure virtual

销毁 IChannel 对象。

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败
    • ERR_NOT_INITIALIZED (7): SDK 尚未初始化,就调用其 API。请确认在调用 API 之前已创建 IChannel 对象并完成初始化。

◆ setChannelEventHandler()

virtual int agora::rtc::IChannel::setChannelEventHandler ( IChannelEventHandler channelEh)
pure virtual

设置 IChannel 对象的事件句柄。

你可以通过设置的事件句柄监听本 IChannel 对象对应频道的事件,并接收频道中用户视频信息等。

参数
channelEhIChannel 对象的事件句柄。详见 IChannelEventHandler
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ joinChannel()

virtual int agora::rtc::IChannel::joinChannel ( const char *  token,
const char *  info,
uid_t  uid,
const ChannelMediaOptions options 
)
pure virtual

通过 UID 加入频道。

该方法与 IRtcEngine 类下的 joinChannel 方法有以下区别:

IChannel::joinChannel IRtcEngine::joinChannel
channelId 参数。因为创建 IChannel 对象时已指定了 channelId需要填入可以标识频道的 channelId
加了 options 参数,可在加入频道前通过该参数设置是否订阅该频道的音视频流。 options 参数。加入频道即默认订阅频道内的音视频流。
通过创建多个 IChannel 对象,并调用相应对象的 IChannel joinChannel "joinChannel" 方法,实现同时加入多个频道。 只允许加入一个频道。
通过该方法加入频道后,SDK 默认不发布本地音视频流到本频道,用户需要调用 IChannel publish "publish" 方法进行发布。 通过该方法加入频道后,SDK 默认发布音视频流发布到本频道。
注解
  • 该方法不支持相同的用户重复加入同一个频道。
  • 我们建议不同频道中使用不同的 UID。
  • 如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 UID 是不同的。
  • 请确保用于生成 Token 的 App ID 和创建 IRtcEngine 对象时用的 App ID 一致。
参数
token在 App 服务器端生成的用于鉴权的 Token:
  • 安全要求不高:你可以使用控制台生成的临时 Token,详见 获取临时 Token.
  • 安全要求高:将值设为你的服务端生成的正式 Token,详见 获取正式 Token.
info(非必选项)开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户。
uid用户 ID,32 位无符号整数。建议设置范围:1 到 232-1,并保证唯一性。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
options频道媒体设置选项: ChannelMediaOptions
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -3(ERR_NOT_READY): SDK 初始化失败,请尝试重新初始化 SDK。
    • -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因:
      • 已经创建了一个同名的 IChannel 频道。
      • 已经通过 IChannel 加入了一个频道,并在该 IChannel 频道中发布了音视频流。

◆ joinChannelWithUserAccount()

virtual int agora::rtc::IChannel::joinChannelWithUserAccount ( const char *  token,
const char *  userAccount,
const ChannelMediaOptions options 
)
pure virtual

通过 User account 加入频道。

该方法与 IRtcEngine 类下的 joinChannelWithUserAccount 方法有以下区别:

IChannel::joinChannelWithUserAccount IRtcEngine::joinChannelWithUserAccount
channelId 参数。因为创建 IChannel 对象时已指定了 channelId需要填入可以标识频道的 channelId
加了 options 参数,可在加入频道前通过该参数设置是否订阅该频道的音视频流。 options 参数。加入频道即默认订阅频道内的音视频流。
通过创建多个 IChannel 对象,并调用相应对象的 IChannel joinChannelWithUserAccount "joinChannelWithUserAccount" 方法,实现同时加入多个频道。 只允许加入一个频道。
通过该方法加入频道后,SDK 默认不发布本地音视频流到本频道,用户需要调用 IChannel publish "publish" 方法进行发布。 通过该方法加入频道后,SDK 默认发布音视频流发布到本频道。
注解
  • 该方法不支持相同的用户重复加入同一个频道。
  • 我们建议不同频道中使用不同的 user account。
  • 如果想要从不同的设备同时接入同一个频道,请确保每个设备上使用的 user account 是不同的。
  • 请确保用于生成 Token 的 App ID 和创建 IChannel 对象时用的 App ID 一致。
参数
token在 App 服务器端生成的用于鉴权的 Token:
  • 安全要求不高:你可以使用控制台生成的临时 Token,详见 获取临时 Token.
  • 安全要求高:将值设为你的服务端生成的正式 Token,详见 获取正式 Token.
userAccount用户 User Account。该参数为必需,最大不超过 255 字节,不可为 null。请确保加入频道的 User Account 的唯一性。 以下为支持的字符集范围(共 89 个字符):
  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
  • 空格
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
options频道媒体设置选项: ChannelMediaOptions。
返回

◆ leaveChannel()

virtual int agora::rtc::IChannel::leaveChannel ( )
pure virtual

离开频道。

离开频道,即挂断或退出通话。

当调用 joinChannel 方法后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。 不管当前是否在通话中,都可以调用 leaveChannel,没有副作用。该方法会把会话相关的所有资源释放掉。 该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。 成功调用该方法离开频道后,本地会触发 onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。

注解
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -1(ERR_FAILED): 一般性的错误(未明确归类)。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

◆ publish()

virtual int agora::rtc::IChannel::publish ( )
pure virtual

将本地音视频流发布到本频道。

该方法的调用需满足以下要求,否则 SDK 会返回 ERR_REFUSED (5) :

  • 该方法仅支持将音视频流发布到当前 IChannel 类所对应的频道。
  • 直播场景下,该方法仅适用于角色为主播的用户。你可以调用该 IChannel 类下的 setClientRole 方法设置用户角色。
  • SDK 只支持用户同一时间在一个频道发布一路音视频流。详情请参考进阶功能《多频道管理》。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ unpublish()

virtual int agora::rtc::IChannel::unpublish ( )
pure virtual

停止将本地音视频流发布到本频道。

请确保你想要 unpublish 音视频流的频道 channelId,与当前正在 IChannel publish "publish" 音视频流的频道 channelId 一致,否则 SDK 会返回 ERR_REFUSED (5)

返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ channelId()

virtual const char* agora::rtc::IChannel::channelId ( )
pure virtual

获取当前频道的频道名。

返回
  • 方法调用成功,返回 channelId,即当前频道的频道名。
  • 方法调用失败,返回空字符串 ""。

◆ getCallId()

virtual int agora::rtc::IChannel::getCallId ( agora::util::AString callId)
pure virtual

获取当前通话 ID。

客户端在每次 joinChannel 后会生成一个对应的 callId,标识该客户端的此次通话。 有些方法如 ratecomplain 需要在通话结束后调用,向 SDK 提交反馈,这些方法必须指定 CallId 参数。使用这些反馈方法,需要在通话过程中调用 getCallId 方法获取 CallId,在通话结束后在反馈方法中作为参数传入。

参数
[out]callId当前的通话 ID。
返回
  • 0: 方法调用成功,返回当前通话 ID
  • < 0: 方法调用失败

◆ renewToken()

virtual int agora::rtc::IChannel::renewToken ( const char *  token)
pure virtual

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制,过一段时间后使用的 Token 会失效。当:

App 应重新获取 Token,然后调用该方法更新 Token,否则 SDK 无法和服务器建立连接。

参数
token新的 Token。
返回
  • 0(ERR_OK): 方法调用成功。
  • < 0: 方法调用失败。
    • -1(ERR_FAILED): 一般性的错误(未明确归类)。
    • -2(ERR_INALID_ARGUMENT): 参数无效。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

◆ setEncryptionSecret()

virtual int agora::rtc::IChannel::setEncryptionSecret ( const char *  secret)
pure virtual

启用内置加密,并设置数据加密密码。

在加入频道之前,App 需调用 setEncryptionSecret 方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。

注解
  • 请不要在旁路推流时调用此方法。
  • 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
secret加密密码。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setEncryptionMode()

virtual int agora::rtc::IChannel::setEncryptionMode ( const char *  encryptionMode)
pure virtual

启用内置的加密方案。

Agora Video SDK 支持内置加密方案,默认支持 AES-128-XTS。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。

注解
在调用本方法前,请先调用 setEncryptionSecret 启用内置加密功能。
参数
encryptionMode加密模式:
  • "aes-128-xts": 128 位 AES 加密,XTS 模式;
  • "aes-128-ecb":128 位 AES 加密,ECB 模式;
  • "aes-256-xts": 256 位 AES 加密,XTS 模式;
  • "": 设置为空字符串时,默认使用加密方式 "aes-128-xts"。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ enableEncryption()

virtual int agora::rtc::IChannel::enableEncryption ( bool  enabled,
const EncryptionConfig config 
)
pure virtual

开启或关闭内置加密。

自从
v3.1.0

在安全要求较高的场景下,Agora 建议你在加入频道前,调用 enableEncryption 方法开启内置加密。

同一频道内所有用户必须使用相同的加密模式和密钥。一旦所有用户都离开频道,该频道的加密密钥会自动清除。

注解
  • 如果开启了内置加密,则不能使用 RTMP 推流功能。
  • Agora 支持 4 种加密模式。除 SM4_128_ECB 模式外,其他加密模式都需要在集成 SDK 时,额外添加加密库文件。详见《媒体流加密》。
参数
enabled是否开启内置加密:
  • true: 开启
  • false: 关闭
config配置内置加密模式和密钥。详见 EncryptionConfig。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败
    • -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
    • -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
    • -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。需在调用 API 之前已创建 IRtcEngine 对象并完成初始化。

◆ registerPacketObserver()

virtual int agora::rtc::IChannel::registerPacketObserver ( IPacketObserver observer)
pure virtual

注册数据包观测器。

该方法注册数据包观测器 (Packet Observer)。在 Agora SDK 发送/接收(语音、视频)网络包时,会回调 IPacketObserver 定义的接口,App 可用此接口对数据做处理,例如加解密。

注解
  • 处理后发送到网络的包大小不应超过 1200 字节,否则有可能发送失败。
  • 若需调用此方法,需确保接收端和发送端都调用此方法,否则会出现未定义行为(例如音频无声或视频黑屏)。
  • 若在直播场景下使用 CDN 推流、录制或储存,Agora 不建议调用此方法。
参数
observerIPacketObserver
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ registerMediaMetadataObserver()

virtual int agora::rtc::IChannel::registerMediaMetadataObserver ( IMetadataObserver observer,
IMetadataObserver::METADATA_TYPE  type 
)
pure virtual

注册媒体 metadata 观测器用于接收或发送 metadata。

注解
  • 请在 joinChannel 前调用该方法
  • 该方法仅使用于直播场景
参数
observer指向已注册的 metadata 观测器的指针。详见: IMetadataObserver
type用户希望在观测器中使用的 METADATA 类型 。目前仅支持 VIDEO_METADATA 。详见: METADATA_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setClientRole()

virtual int agora::rtc::IChannel::setClientRole ( CLIENT_ROLE_TYPE  role)
pure virtual

设置直播场景下的用户角色。

在加入频道前,用户需要通过本方法设置观众(默认)或主播。在加入频道后,用户可以通过本方法切换用户角色。

直播场景下,如果你在加入频道后调用该方法切换用户角色,调用成功后,本地会触发 onClientRoleChanged 回调;远端会触发 onUserJoined 回调或 onUserOffline (BECOME_AUDIENCE) 回调。

注解
该方法仅适用于直播场景。
参数
role直播场景里的用户角色: CLIENT_ROLE_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteUserPriority()

virtual int agora::rtc::IChannel::setRemoteUserPriority ( uid_t  uid,
PRIORITY_TYPE  userPriority 
)
pure virtual

设置远端用户流的优先级。

设置远端用户的优先级。如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。 弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注解
目前 Agora SDK 仅允许将一名远端用户设为高优先级。
参数
uid远端用户的 ID。
userPriority远端用户的需求优先级。详见: PRIORITY_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteVoicePosition()

virtual int agora::rtc::IChannel::setRemoteVoicePosition ( uid_t  uid,
double  pan,
double  gain 
)
pure virtual

设置远端用户的语音位置。

设置远端用户声音的空间位置和音量,方便本地用户听声辨位。

通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。

注解
  • 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
  • 为获得最佳听觉体验,我们建议使用该方法时使用立体声外放。
参数
uid远端用户的 ID
pan设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
  • (默认)0.0: 声音出现在正前方。
  • -1.0: 声音出现在左边。
  • 1.0: 声音出现在右边。
gain设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteRenderMode()

virtual int agora::rtc::IChannel::setRemoteRenderMode ( uid_t  userId,
RENDER_MODE_TYPE  renderMode,
VIDEO_MIRROR_MODE_TYPE  mirrorMode 
)
pure virtual

更新远端视图显示模式。

初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注解
  • 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
  • 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
userId远端用户 ID。
renderMode远端用户视图的渲染模式,详见 RENDER_MODE_TYPE
mirrorMode
  • 远端用户视图的镜像模式,详见 VIDEO_MIRROR_MODE_TYPE
  • Note: 默认关闭远端用户的镜像模式。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setDefaultMuteAllRemoteAudioStreams()

virtual int agora::rtc::IChannel::setDefaultMuteAllRemoteAudioStreams ( bool  mute)
pure virtual

设置是否默认接收所有音频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams (true),会接收不到设置后加入频道的用户的音频流。

注解
停止接收音频流后,如果想要恢复接收,请调用 muteRemoteAudioStream (false), 并指定你想要接收的远端用户 uid;如果想恢复接收多个用户的音频流,则需要多次调用 muteRemoteAudioStreamsetDefaultMuteAllRemoteAudioStreams (false) 只能恢复接收后面加入频道的用户的音频流。
参数
mute
  • true: 默认停止接收所有音频流;
  • false: 默认接收所有音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setDefaultMuteAllRemoteVideoStreams()

virtual int agora::rtc::IChannel::setDefaultMuteAllRemoteVideoStreams ( bool  mute)
pure virtual

设置是否默认停止接收视频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams (true),会接收不到设置后加入频道的用户的视频流。

注解
停止接收视频流后,如果想要恢复接收,请调用 muteRemoteVideoStream (false), 并指定你想要接收的远端用户 uid;如果想恢复接收多个用户的视频流,则需要多次调用 muteRemoteVideoStreamsetDefaultMuteAllRemoteVideoStreams (false) 只能恢复接收后面加入频道的用户的视频流。
参数
mute
  • true: 默认停止接收所有远端视频;
  • false: 默认接收所有远端视频(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteAllRemoteAudioStreams()

virtual int agora::rtc::IChannel::muteAllRemoteAudioStreams ( bool  mute)
pure virtual

接收/停止接收所有音频流。

参数
mute
  • true: 停止接收所有音频流;
  • false: 继续接收所有音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ adjustUserPlaybackSignalVolume()

virtual int agora::rtc::IChannel::adjustUserPlaybackSignalVolume ( uid_t  userId,
int  volume 
)
pure virtual

调节本地播放的指定远端用户音量。

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。

注解
  • 请在加入频道后,调用该方法。
  • 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
userId远端用户 ID。
volume播放音量,取值范围为 [0,100]:
  • 0: 静音
  • 100: 原始音量
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteRemoteAudioStream()

virtual int agora::rtc::IChannel::muteRemoteAudioStream ( uid_t  userId,
bool  mute 
)
pure virtual

接收/停止接收指定音频流。

注解
如果之前有调用过 muteAllRemoteAudioStreams (true) 停止订阅所有远端音频,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false)。 muteAllRemoteAudioStreams 是全局控制,muteRemoteAudioStream 是精细控制。
参数
userId指定用户的 ID
mute
  • true: 停止接收指定音频流;
  • false: 继续接收指定音频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteAllRemoteVideoStreams()

virtual int agora::rtc::IChannel::muteAllRemoteVideoStreams ( bool  mute)
pure virtual

接收/停止接收所有远端视频流。

参数
mute
  • true: 停止接收所有远端视频流;
  • false: 允许接收所有远端视频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ muteRemoteVideoStream()

virtual int agora::rtc::IChannel::muteRemoteVideoStream ( uid_t  userId,
bool  mute 
)
pure virtual

接收/停止接收指定远端用户的视频流。

注解
如果之前调用过 muteAllRemoteVideoStreams (true) 停止接收放所有远端视频流,在调用本 API 之前请确保你已调用 muteAllRemoteVideoStreams (false) 。muteAllRemoteVideoStreams 是全局控制,muteRemoteVideoStream 是精细控制。
参数
userId指定用户的用户 ID。
mute
  • true: 停止接收指定远端用户的视频流;
  • false: 允许接收指定远端用户的视频流(默认)。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteVideoStreamType()

virtual int agora::rtc::IChannel::setRemoteVideoStreamType ( uid_t  userId,
REMOTE_VIDEO_STREAM_TYPE  streamType 
)
pure virtual

设置订阅的视频流类型。

在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式, 接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流, 小流则是低分辨率低码率的视频流。

正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。 视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数
userId用户 ID。
streamType视频流类型: REMOTE_VIDEO_STREAM_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setRemoteDefaultVideoStreamType()

virtual int agora::rtc::IChannel::setRemoteDefaultVideoStreamType ( REMOTE_VIDEO_STREAM_TYPE  streamType)
pure virtual

设置默认订阅的视频流类型。

在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false) 关闭双流模式, 接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流, 小流则是低分辨率低码率的视频流。

正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认 的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 onApiCallExecuted 中返回。

参数
streamType视频流类型: REMOTE_VIDEO_STREAM_TYPE
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ createDataStream()

virtual int agora::rtc::IChannel::createDataStream ( int *  streamId,
bool  reliable,
bool  ordered 
)
pure virtual

创建数据流。

该方法用于创建数据流。RtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒,若超过 5 秒接收方尚未收到数据流,则数据通道会向 App 报错。

注解
将 reliable 和 ordered 同时设为 true 或 false。不要一个设为 true 另一个设为 false。
参数
streamId数据流 ID。
reliable
  • true: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 onStreamMessageError 回调获得相应报错信息。
  • false: 接收方不保证收到,就算数据丢失也不会报错。
ordered
  • true: 接收方 5 秒内会按照发送方发送的顺序收到数据包;
  • false: 接收方不保证按照发送方发送的顺序收到数据包。
返回
  • 0: 创建数据流成功。
  • < 0: 创建数据流失败。

◆ sendStreamMessage()

virtual int agora::rtc::IChannel::sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtual

发送数据流。

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制:频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。 API 须对数据通道的传送速率进行控制: 每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。 成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息;若调用失败,远端会触发 onStreamMessageError 回调。

注解
该方法仅适用于通信场景以及直播场景下的主播用户,如果直播场景下的观众调用此方法可能会造成观众变主播。
参数
streamIdcreateDataStream 返回的数据流 ID。
data自定义数据。
length数据长度。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ addPublishStreamUrl()

virtual int agora::rtc::IChannel::addPublishStreamUrl ( const char *  url,
bool  transcodingEnabled 
)
pure virtual

增加旁路推流地址。

调用该方法后,SDK会在本地触发 onRtmpStreamingStateChanged 回调,报告增加旁路推流地址的状态。

注解
  • 请确保在成功加入频道后才能调用该接口。
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
  • 该方法仅适用于直播场景。
参数
urlCDN 推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
transcodingEnabled
  • true: 转码( 转码 是指在旁路推流时对音视频流进行转码处理后再推送到其他 RTMP 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景)。如果设为 true,需先调用 setLiveTranscoding 方法。
  • false: 不转码。
返回

◆ removePublishStreamUrl()

virtual int agora::rtc::IChannel::removePublishStreamUrl ( const char *  url)
pure virtual

删除旁路推流地址。

调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告删除旁路推流地址的状态。

注解
  • 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
  • URL 不支持中文等特殊字符。
  • 该方法仅适用于直播场景。
参数
url待删除的旁路推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ setLiveTranscoding()

virtual int agora::rtc::IChannel::setLiveTranscoding ( const LiveTranscoding transcoding)
pure virtual

设置直播推流转码。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 onTranscodingUpdated 回调。

注解
  • 该方法仅适用于直播场景。
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 首次调用该方法更新转码设置时,不会触发 onTranscodingUpdated 回调。
参数
transcoding详见 LiveTranscoding
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ addInjectStreamUrl()

virtual int agora::rtc::IChannel::addInjectStreamUrl ( const char *  url,
const InjectStreamConfig config 
)
pure virtual

输入在线媒体流。

注解
  • 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
  • 该方法适用于 Native SDK v2.4.1 及之后的版本。
  • 该方法仅适用于直播场景中的主播用户。
  • 频道内同一时间只允许输入一个在线媒体流。

该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后,SDK 会在本地触发 onStreamInjectedStatus 回调,报告输入在线媒体流的状态;成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 onUserJoined 回调,其中 uid 为 666。该音视频流会出现在频道中。

参数
url添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。
  • 支持的音频编码格式:AAC;
  • 支持的视频编码格式:H.264(AVC)。
config所添加的视频流属性定义,详见: InjectStreamConfig
返回

◆ removeInjectStreamUrl()

virtual int agora::rtc::IChannel::removeInjectStreamUrl ( const char *  url)
pure virtual

删除导入的外部媒体流。

注解
成功删除外部视频源 URL 地址后会触发 onUserOffline 回调,uid 为 666。
参数
url已导入、待删除的外部视频源 URL 地址。
返回
  • 0: 方法调用成功
  • < 0: 方法调用失败

◆ startChannelMediaRelay()

virtual int agora::rtc::IChannel::startChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChangedonChannelMediaRelayEvent 回调,并在回调中报告当前的跨频道媒体流转发状态和事件。

注解
  • 请在成功加入频道后调用该方法。
  • 该方法仅对直播场景下的主播有效。
  • 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
  • 跨频道媒体流转发功能需要提交工单联系技术支持开通。
  • 该功能不支持 String 型 UID。
参数
configuration跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration
返回
  • 0:方法调用成功。
  • < 0:方法调用失败

◆ updateChannelMediaRelay()

virtual int agora::rtc::IChannel::updateChannelMediaRelay ( const ChannelMediaRelayConfiguration configuration)
pure virtual

更新媒体流转发的频道。

成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道, 或退出当前的转发频道,可以调用该方法。

成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。

注解
请在 startChannelMediaRelay 方法后调用该方法,更新媒体流转发的频道。
参数
configuration跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration
返回
  • 0:方法调用成功。
  • < 0:方法调用失败

◆ stopChannelMediaRelay()

virtual int agora::rtc::IChannel::stopChannelMediaRelay ( )
pure virtual

停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。

成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。

注解
如果该方法调用不成功,SDK 会触发 onChannelMediaRelayStateChanged 回调,并报告状态码 RELAY_ERROR_SERVER_NO_RESPONSE (2) 或 RELAY_ERROR_SERVER_CONNECTION_LOST (8)。你可以调用 leaveChannel 方法离开频道,跨频道媒体流转发会自动停止。
返回
  • 0:方法调用成功。
  • < 0:方法调用失败

◆ getConnectionState()

virtual CONNECTION_STATE_TYPE agora::rtc::IChannel::getConnectionState ( )
pure virtual

获取当前网络连接状态。

返回
CONNECTION_STATE_TYPE