IGameRTCService

public interface GameRTC.IGameRTCService

提供即时通讯的能力（参考某5v5moba手游的队内语音交流）；

Defined in : IGameRTCService.cs

成员变量

类型	名称
event	OnJoinRoomResultEvent
event	OnLeaveRoomEvent
event	OnUserJoinedEvent
event	OnUserLeaveEvent
event	OnMicrophoneEnabledEvent
event	OnAudioSendEnabledEvent
event	OnSpeakerphoneEnabledEvent
event	OnAudioVolumeIndicationEvent
event	OnConnectionStateChangedEvent
event	OnNetworkQualityEvent
event	OnEngineWarningEvent
event	OnRoomWarningEvent
event	OnRoomErrorEvent

成员函数

返回	名称
void	Initialize
void	Release
string	GetSdkVersion
int	JoinRoom
int	LeaveRoom
int	UpdateToken
int	UpdateReceiveRange
int	UpdatePosition
int	EnableMicrophone
int	EnableAudioSend
int	EnableSpeakerphone
int	EnableAudioReceive
int	SetRecordingVolume
int	SetPlaybackVolume
int	SetRemoteAudioPlaybackVolume
int	SetAudioScenario
int	GetRecordingDeviceCount
int	SetRecordingDevice
int	GetCurrentRecordingDevice
int	GetAllRecordingDevices
int	GetPlaybackDeviceCount
int	SetPlaybackDevice
int	GetCurrentPlaybackDevice
int	GetAllPlaybackDevices

变量说明

OnJoinRoomResultEvent

event GameRTC.IGameRTCService.OnJoinRoomResultEventHandler

进房成功回调

OnLeaveRoomEvent

event GameRTC.IGameRTCService.OnLeaveRoomEventHandler

退房成功回调

OnUserJoinedEvent

event GameRTC.IGameRTCService.OnUserJoinedEventHandler

远端用户加入房间回调

OnUserLeaveEvent

event GameRTC.IGameRTCService.OnUserLeaveEventHandler

远端用户离开房间回调

OnMicrophoneEnabledEvent

event GameRTC.IGameRTCService.OnMicrophoneEnabledEventHandler

远端用户开关麦克风回调

OnAudioSendEnabledEvent

event GameRTC.IGameRTCService.OnAudioSendEnabledEventHandler

远端用户启停音频数据发送回调

OnSpeakerphoneEnabledEvent

event GameRTC.IGameRTCService.OnSpeakerphoneEnabledEventHandler

远端用户启停音频数据接收回调

OnAudioVolumeIndicationEvent

event GameRTC.IGameRTCService.OnAudioVolumeIndicationEventHandler

音量统计信息回调

OnConnectionStateChangedEvent

event GameRTC.IGameRTCService.OnConnectionStateChangedEventHandler

网络状态改变的回调

OnNetworkQualityEvent

event GameRTC.IGameRTCService.OnNetworkQualityEventHandler

网络质量回调

OnEngineWarningEvent

event GameRTC.IGameRTCService.OnEngineWarningEventHandler

引擎警告回调

OnRoomWarningEvent

event GameRTC.IGameRTCService.OnRoomWarningEventHandler

房间警告回调

OnRoomErrorEvent

event GameRTC.IGameRTCService.OnRoomErrorEventHandler

房间错误回调

函数说明

Initialize

void GameRTC.IGameRTCService.Initialize(
    GameRTCEngineParams initParams)

创建 GameRTCEngine 实例。
GameRTCEngine 实例成功创建后，你才可以使用 SDK 提供的其他能力。

传入参数

参数名	类型	说明
initParams	GameRTCEngineParams	引擎初始化参数，参看 GameRTCEngineParams。

Release

void GameRTC.IGameRTCService.Release();

销毁由 Initialize 所创建引擎实例，并释放所有相关资源。

注意

你必须在所有业务场景的最后阶段调用该方法。该方法在调用之后，会销毁所有 SDK 相关的内存，并且停止与媒体服务器的任何交互。
本方法为阻塞调用，会阻塞当前线程直到 SDK 彻底完成退出逻辑。因此，不可在回调线程中直接调用本方法；也不可在回调方法中等待主线程的执行而同时在主线程调用本方法，否则会造成死锁。

GetSdkVersion

string GameRTC.IGameRTCService.GetSdkVersion();

获取 SDK 当前的版本号。

返回值 SDK 当前的版本号。

JoinRoom

int GameRTC.IGameRTCService.JoinRoom(
    string roomID,
    string userID,
    string token,
    GameRTCRoomConfig roomConfig)

加入实时语音房间。
在使用实时语音的通话功能时，必须先加入实时语音房间。
调用该方法后，会收到 OnJoinRoomResultEventHandler 回调通知。

传入参数

参数名	类型	说明
roomID	string	房间 ID，用户调用此接口加入的房间的房间 ID。房间 ID 为长度在 128 字节内的非空字符串，支持以下字符集范围: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线 "_"，at 符 "@"，减号 "-"。
userID	string	用户 ID，用户调用此接口加入的房间时使用的用户 ID 。用户 ID 为长度在 128 字节内的非空字符串，支持以下字符集范围: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线 "_"，at 符 "@"，减号 "-"。
token	string	动态密钥，用于对登录用户进行鉴权验证。进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在您的服务端生成并下发 Token。
roomConfig	GameRTCRoomConfig	房间配置参数，参看 GameRTCRoomConfig。

返回值 方法调用结果

0: 成功；
<0: 失败。

注意

使用不同 App ID 的 App 是不能互通的。
请务必保证生成 Token 使用的 App ID 和创建引擎时使用的 App ID 相同，否则会导致加入房间失败。
用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本端会收到 OnJoinRoomResultEventHandler 回调通知，其 isRejoined 参数为 true。
同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后加入房间的用户会将先加入房间的用户踢出房间，并且先加入房间的用户会收到 OnRoomErrorEventHandler 回调通知，错误类型为重复登录 DuplicateLogin。

LeaveRoom

int GameRTC.IGameRTCService.LeaveRoom(
    string roomID)

离开房间。
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
调用 JoinRoom 方法加入房间后，在通话结束时必须调用此方法，并收到 OnLeaveRoomEventHandler 回调确认结束通话，否则无法开始下一次通话。
无论当前是否在房间中，都可以调用此方法。重复调用此方法不会有负面影响。

传入参数

参数名	类型	说明
roomID	string	房间 ID，用户调用此接口离开的房间的房间 ID。房间 ID 为长度在 128 字节内的非空字符串，支持以下字符集范围: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线 "_"，at 符 "@"，减号 "-"。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

UpdateToken

int GameRTC.IGameRTCService.UpdateToken(
    string roomID,
    string token)

更新进房 token。
在进房时如果收到错误码为 kJoinRoomInvalidToken 的 OnJoinRoomResultEventHandler 回调，表示 token 过期导致进房失败。
此时，你应调用此接口，以新 token 进房。

传入参数

参数名	类型	说明
roomID	string	房间 ID，用户调用此接口加入的房间的房间 ID。房间 ID 为长度在 128 字节内的非空字符串，支持以下字符集范围: 1. 26 个大写字母 A ~ Z 。 2. 26 个小写字母 a ~ z 。 3. 10 个数字 0 ~ 9 。 4. 下划线 "_"，at 符 "@"，减号 "-"。
token	string	动态密钥，用于对登录用户进行鉴权验证。进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在您的服务端生成并下发 Token。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

UpdateReceiveRange

int GameRTC.IGameRTCService.UpdateReceiveRange(
    string roomID,
    GameRTCReceiveRange range)

在世界房间中，使用范围语音功能时，设定语音的接收范围和衰减信息。

传入参数

参数名	类型	说明
roomID	string	房间 ID
range	GameRTCReceiveRange	语音的收听范围，参看 GameRTCReceiveRange。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

注意你应在加入房间时，通过参数设置，加入世界房间，并开启范围语音: - 关于世界房间，参看 RoomType 中的 World。

关于范围语音，参看 GameRTCRoomConfig。

UpdatePosition

int GameRTC.IGameRTCService.UpdatePosition(
    string roomID,
    GameRTCPositionInfo pos)

使用范围语音功能时，设置玩家的坐标。

传入参数

参数名	类型	说明
roomID	string	房间 ID
pos	GameRTCPositionInfo	玩家坐标值，参看 GameRTCPositionInfo。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

EnableMicrophone

int GameRTC.IGameRTCService.EnableMicrophone(
    string roomID,
    bool enable)

控制本地音频采集和发布状态。
改变该状态后，房间内其他用户会收到 OnMicrophoneEnabledEventHandler 回调。

传入参数

参数名	类型	说明
roomID	string	房间 ID
enable	bool	本地音频采集和发布状态： • true：开始采集本地音频，并向房间内发布。 • false：停止采集本地音频，并停止发布。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

EnableAudioSend

int GameRTC.IGameRTCService.EnableAudioSend(
    string roomID,
    bool enable)

控制本地语音的发送状态：发送/不发送。
使用此方法后，房间中的其他用户会收到 OnAudioSendEnabledEventHandler 回调。

传入参数

参数名	类型	说明
roomID	string	房间 ID
enable	bool	发送状态，标识是否发送语音： • true: 发布语音 • false: 不发布语音

返回值 方法调用结果

0: 成功
<0: 失败

注意

初次调用本方法发送本地语音时，会开启本地音频采集功能。
之后再次调用本方法时，仅控制本地音频流的发送状态，不会影响本地音频采集状态。

EnableSpeakerphone

int GameRTC.IGameRTCService.EnableSpeakerphone(
    string roomID,
    bool enable)

设置对来自远端的语音的接收状态。
使用此方法后，房间中的其他用户会收到 OnSpeakerphoneEnabledEventHandler 回调。

传入参数

参数名	类型	说明
roomID	string	房间 ID
enable	bool	接收状态： • true: 接收 • false: 不接收

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

注意本方法只控制本地是否接收远端音频流，并不影响本地音频播放设备的工作状态。

EnableAudioReceive

int GameRTC.IGameRTCService.EnableAudioReceive(
    string roomID,
    string userID,
    bool enable)

设置对来自指定远端用户的语音的接收状态。

传入参数

参数名	类型	说明
roomID	string	房间 ID
userID	string	指定远端用户的 ID
enable	bool	接收状态： • true: 接收 • false: 不接收

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

注意本方法只控制本地是否接收远端音频流，并不影响本地音频播放设备的工作状态。

SetRecordingVolume

int GameRTC.IGameRTCService.SetRecordingVolume(
    int volume)

调节音频采集音量。

传入参数

参数名	类型	说明
volume	int	音频采集音量，调节范围: [0,400]，单位: % • 0: 静音 • 100: 原始音量 • 400: 最大可为原始音量的 4 倍(自带溢出保护，防止音量放大可能导致的爆音等问题)。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

注意为保证更好的通话质量，建议将 volume 值设为 [0,100]。

SetPlaybackVolume

int GameRTC.IGameRTCService.SetPlaybackVolume(
    int volume)

调节本地播放的所有远端用户混音后的音量。

传入参数

参数名	类型	说明
volume	int	音频播放音量，调节范围: [0,400]，单位: % • 0: 静音 • 100: 原始音量 • 400: 最大可为原始音量的 4 倍(自带溢出保护，防止音量放大可能导致的爆音等问题)。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

注意为保证更好的通话质量，建议将 volume 值设为 [0,100]。

SetRemoteAudioPlaybackVolume

int GameRTC.IGameRTCService.SetRemoteAudioPlaybackVolume(
    string roomID,
    string userID,
    int volume)

调节来自指定远端用户的音频播放音量

传入参数

参数名	类型	说明
roomID	string	房间 ID
userID	string	指定远端用户的 ID
volume	int	播放音量，调节范围: [0,400]，单位: % • 0: 静音 • 100: 原始音量 • 400: 最大可为原始音量的 4 倍(自带溢出保护，防止音量放大可能导致的爆音等问题)。

返回值 方法调用结果

0: 成功；
-1: 失败，引擎已经被销毁或者未创建，或者是房间 ID 为空。

注意开启范围语音后，此接口不生效。

SetAudioScenario

int GameRTC.IGameRTCService.SetAudioScenario(
    AudioScenarioType scenario)

设置音频场景类型。
你可以根据你的应用所在场景，选择合适的音频场景类型。选择音频场景后，RTC 会自动根据客户端音频路由和发布订阅状态，适用通话音量/媒体音量。
在进房前和进房后设置均可生效。

传入参数

参数名	类型	说明
scenario	AudioScenarioType	音频场景类型，参见 AudioScenarioType

注意

通话音量更适合通话，会议等对信息准确度要求更高的场景。通话音量会激活系统硬件信号处理，使通话声音会更清晰。此时，音量无法降低到 0。
媒体音量更适合娱乐场景，因其声音的表现力会更强。媒体音量下，音量最低可以降低到 0。

GetRecordingDeviceCount

int GameRTC.IGameRTCService.GetRecordingDeviceCount();

获取音频采集设备的数量

返回值

获取成功则返回实际的音频采集设备数量；
获取失败返回 -1，失败的原因可能是引擎未初始化。

注意该接口仅适用于 PC 平台，不适用于移动平台。

SetRecordingDevice

int GameRTC.IGameRTCService.SetRecordingDevice(
    string deviceID)

指定音频采集设备

传入参数

参数名	类型	说明
deviceID	string	设备 ID

返回值 方法调用结果

0: 成功；
<0: 失败，需要检查 deviceID 是否为空，以及引擎是否存在。

注意该接口仅适用于 PC 平台，不适用于移动平台。

GetCurrentRecordingDevice

int GameRTC.IGameRTCService.GetCurrentRecordingDevice(
    ref string deviceID)

获取当前音频采集设备

传入参数

参数名	类型	说明
deviceID	ref string	设备 ID

返回值 方法调用结果

0: 成功；
<0: 失败，需要检查 deviceID 是否为空，以及引擎是否存在。

注意该接口仅适用于 PC 平台，不适用于移动平台。

GetAllRecordingDevices

int GameRTC.IGameRTCService.GetAllRecordingDevices(
    ref List<AudioDeviceInfo> audioDeviceList)

获取全部音频采集设备信息

传入参数

参数名	类型	说明
audioDeviceList	ref List	音频设备信息列表

返回值

0: 成功；
<0: 失败，你需要检查 audioDeviceInfo 是否为空，以及引擎是否存在。

注意该接口仅适用于 PC 平台，不适用于移动平台。

GetPlaybackDeviceCount

int GameRTC.IGameRTCService.GetPlaybackDeviceCount();

获取音频播放设备的数量

返回值

获取成功则返回实际的播放设备数量；
获取失败返回 -1，失败的原因可能是引擎未初始化。

注意该接口仅适用于 PC 平台，不适用于移动平台。

SetPlaybackDevice

int GameRTC.IGameRTCService.SetPlaybackDevice(
    string deviceID)

指定音频播放设备

传入参数

参数名	类型	说明
deviceID	string	设备ID

返回值 方法调用结果

0: 成功；
<0: 失败，需要检查 deviceID 是否为空，以及引擎是否存在。

注意该接口仅适用于 PC 平台，不适用于移动平台。

GetCurrentPlaybackDevice

int GameRTC.IGameRTCService.GetCurrentPlaybackDevice(
    ref string deviceID)

获取当前音频播放设备

传入参数

参数名	类型	说明
deviceID	ref string	设备ID

返回值 方法调用结果

0: 成功；
<0: 失败，需要检查 deviceID 是否为空，以及引擎是否存在。

注意该接口仅适用于 PC 平台，不适用于移动平台。

GetAllPlaybackDevices

int GameRTC.IGameRTCService.GetAllPlaybackDevices(
    ref List<AudioDeviceInfo> audioDeviceList)

获取全部音频播放设备信息

传入参数

参数名	类型	说明
audioDeviceList	ref List	音频设备信息列表

返回值

0: 成功；
<0: 失败，你需要检查 audioDeviceInfo 是否为空，以及引擎是否存在。

注意该接口仅适用于 PC 平台，不适用于移动平台。