agora_rtc_api.h 文件参考

宏定义说明

agora_api

#define agora_api

AGORA_CERTIFICATE_MAX_LEN

#define AGORA_CERTIFICATE_MAX_LEN   1024

AGORA_CREDENTIAL_MAX_LEN

#define AGORA_CREDENTIAL_MAX_LEN   256

AGORA_LICENSE_VALUE_LEN

#define AGORA_LICENSE_VALUE_LEN   32

AGORA_RTC_CHANNEL_NAME_MAX_LEN

#define AGORA_RTC_CHANNEL_NAME_MAX_LEN   (64)

AGORA_RTC_PRODUCT_ID_MAX_LEN

#define AGORA_RTC_PRODUCT_ID_MAX_LEN   (63)

AGORA_RTC_USER_ID_MAX_LEN

#define AGORA_RTC_USER_ID_MAX_LEN   (255)

AGORA_RTM_DATA_MAX_LEN

#define AGORA_RTM_DATA_MAX_LEN   (32 * 1024)

AGORA_RTM_UID_MAX_LEN

#define AGORA_RTM_UID_MAX_LEN   64

CONNECTION_ID_ALL

#define CONNECTION_ID_ALL   ((connection_id_t)0)

当前创建的全部 Connection。

CONNECTION_ID_INVALID

#define CONNECTION_ID_INVALID   ((connection_id_t)-1)

无效的 Connection ID。

类型定义说明

connection_id_t

typedef uint32_t connection_id_t

Connection ID。

rdt_state_e

typedef enum rdt_state rdt_state_e

RDT 通道的连接状态。

rdt_status_info_t

typedef struct rdt_status_info rdt_status_info_t

RDT 通道的信息。

rdt_stream_type_e

typedef enum rdt_stream_type rdt_stream_type_e

RDT 消息类型。

video_frame_rate_e

typedef uint16_t video_frame_rate_e

（废弃）视频帧率。

agora_err_code_e

enum agora_err_code_e

错误码。

枚举键	描述
ERR_OKAY	0: 无错误。
ERR_FAILED	1: 通用错误。你可以根据日志文件排查问题。
ERR_NET_DOWN	14: 网络不可用。你需要检查系统网络连接状态。
ERR_JOIN_CHANNEL_REJECTED	17: 加入频道请求被拒绝，可能是因为本地用户已在频道内。你需要调整代码逻辑，避免用户加入同一频道。
ERR_INVALID_APP_ID	101: App ID 无效。你需要检查 App ID 是否符合要求。
ERR_INVALID_CHANNEL_NAME	102: 频道名无效。你需要检查频道名是否符合要求。
ERR_NO_SERVER_RESOURCES	103: 在当前的区域限制码条件下无可用服务器资源。
ERR_LOOKUP_CHANNEL_REJECTED	105: 声网服务器拒绝了查询频道的请求。你需要检查 RTC Token 是否有效。
ERR_OPEN_CHANNEL_REJECTED	107: 声网服务器拒绝了创建频道的请求。你需要检查 RTC Token 是否有效。
ERR_TOKEN_EXPIRED	109: 当前使用的 RTC Token 已过期。你需要重新在服务端申请生成 RTC Token 并调用 agora_rtc_join_channel 使用新生成的 RTC Token 重新加入频道。
ERR_INVALID_TOKEN	110: RTC Token 无效。你需要检查生成 Token 使用的 uid 是否和加入频道时使用的 uid 一致。
ERR_DYNAMIC_TOKEN_BUT_USE_STATIC_KEY	115: 你在声网控制台开启了 App 证书，但仍旧在代码里仅使用了 App ID。当启用了 App Certificate，必须使用 RTC Token。
ERR_SET_CLIENT_ROLE_NOT_AUTHORIZED	119: 切换用户角色失败，请尝试重新加入频道。
ERR_DECRYPTION_FAILED	120：解密失败。检查你的加密设置或重新加入频道。
ERR_OPEN_CHANNEL_INVALID_TICKET	121: 打开频道的信令错误。请尝试重新加入频道。
ERR_OPEN_CHANNEL_TRY_NEXT_VOS	122: 系统在尝试切换服务器。通常不需要额外处理，系统会自动尝试切换服务器以打开频道。
ERR_CLIENT_IS_BANNED_BY_SERVER	123: 该客户端被服务器禁用。你需要检查该用户是否被踢。
ERR_SEND_VIDEO_OVER_BANDWIDTH_LIMIT	200: 视频帧发送速率超过带宽限制。可能会造成丢包。你可以通过 on_target_bitrate_changed 回调带宽参数调整码率。
ERR_AUDIO_DECODER_NOT_MATCH_AUDIO_FRAME	201：设置的编码类型与实际编码类型不符导致 SDK 解码失败。你需要确认 SDK 设置的编码类型是否与实际传输的编码类型一致。
ERR_NO_AUDIO_DECODER_TO_HANDLE_AUDIO_FRAME	202: SDK 解码失败。SDK 内置的解码器仅支持 Opus、G722 和 PCMU 编码的音频帧。你需要确认对端发送的音频码流是否为 Opus 、G722 或 PCMU 编码格式。

area_code_e

enum area_code_e

访问区域。

枚举键	描述
AREA_CODE_DEFAULT	中国大陆
AREA_CODE_CN	中国大陆
AREA_CODE_NA	北美
AREA_CODE_EU	欧洲
AREA_CODE_AS	亚洲（除中国大陆）
AREA_CODE_JP	日本
AREA_CODE_IN	印度
AREA_CODE_OC	大洋洲
AREA_CODE_SA	南美
AREA_CODE_AF	非洲
AREA_CODE_KR	韩国
AREA_CODE_HKMC	香港和澳门
AREA_CODE_US	美国
AREA_CODE_RU	俄罗斯
AREA_CODE_OVS	全球（除中国）
AREA_CODE_GLOB	全球 (默认)

audio_codec_type_e

enum audio_codec_type_e

SDK 内置的音频编解码器。

枚举键	描述
AUDIO_CODEC_DISABLED	0: 关闭 SDK 内置音频编解码器。
AUDIO_CODEC_TYPE_OPUS	1: 使用 SDK 内置的 Opus 编解码器进行音频编、解码。在 Opus 编码下， SDK 对单个声道支持 16 KHz 或 48 KHz 采样率。
AUDIO_CODEC_TYPE_G722	2: 使用 SDK 内置的 G722 编解码器进行音频编、解码。在 G722 编码下， 目前 SDK 对单个声道支持 16 KHz 采样率。
AUDIO_CODEC_TYPE_G711A	3: 使用 SDK 内置的 G711A（PCMU）编解码器进行音频编、解码。在 G711 编码下， 目前 SDK 对单个声道支持 8 KHz 采样率。
AUDIO_CODEC_TYPE_G711U	4: 使用 SDK 内置的 G711U（PCMU）编解码器进行音频编、解码。在 G711 编码下， 目前 SDK 对单个声道支持 8 KHz 采样率。

audio_data_type_e

enum audio_data_type_e

音频编码格式。

枚举键	描述
AUDIO_DATA_TYPE_OPUS	1: Opus
AUDIO_DATA_TYPE_OPUSFB	2: OPUSFB
AUDIO_DATA_TYPE_PCMA	3: PCMA
AUDIO_DATA_TYPE_PCMU	4: PCMU
AUDIO_DATA_TYPE_G722	5: G722
AUDIO_DATA_TYPE_AACLC_8K	6: AAC-LC (采样率为 8000 Hz)
AUDIO_DATA_TYPE_AACLC_16K	7: AAC-LC (采样率为 16000 Hz)
AUDIO_DATA_TYPE_AACLC	8: AAC-LC (采样率为 48000 Hz)
AUDIO_DATA_TYPE_HEAAC	9: HE-AAC
AUDIO_DATA_TYPE_PCM	100: 用于传输的 PCM 数据
AUDIO_DATA_TYPE_GENERIC	253: Generic

cloud_proxy_type_e

enum cloud_proxy_type_e

云代理类型

枚举键	描述
CLOUD_PROXY_NONE	0：不开启云代理。
CLOUD_PROXY_UDP	1：开启 UDP 协议的云代理。
CLOUD_PROXY_TCP	3：开启 TCP 协议的云代理。
CLOUD_PROXY_AUTO	100：自动模式。在该模式下，SDK 优先连接 SD-RTN™，如果连接失败，自动切换到 TCP 协议的云代理。

crypto_mode_e

enum crypto_mode_e

媒体流加密模式。

建议使用 AES_128_GCM2 或 AES_256_GCM2 加密模式。这两种模式支持使用盐，安全性更高。

枚举键	描述
AES_128_XTS	1: 128 位 AES 加密，XTS 模式。
AES_128_ECB	2: 128 位 AES 加密，ECB 模式。
AES_256_XTS	3: 256 位 AES 加密，XTS 模式。
SM4_128_ECB	4: 128 位 SM4 加密，ECB 模式。
AES_128_GCM	5: 128 位 AES 加密，GCM 模式。
AES_256_GCM	6: 256 位 AES 加密，GCM 模式。
AES_128_GCM2	7: 128 位 AES 加密，GCM 模式。该加密模式需要设置盐（salt）。
AES_256_GCM2	8: 256 位 AES 加密，GCM 模式。该加密模式需要设置盐（salt）。
CRYPTO_MODE_END	枚举值边界。

license_err_reason_e

enum license_err_reason_e

设备 License 验证失败的错误码。

枚举键	描述
ERR_LICENSE_INVALID	1: 无效 License。你需要重新调用 agora_rtc_init 并在 rtc_service_option_t 的 license_value 参数中填入正确的 License。
ERR_LICENSE_EXPIRE	2: License 过期。你需要联系 sales.nosp@m.@she.nosp@m.ngwan.nosp@m.g.cn 进行续费。
ERR_LICENSE_MINUTES_EXCEED	3: License 包含的通话时长已用完。你需要联系 sales.nosp@m.@she.nosp@m.ngwan.nosp@m.g.cn 购买通话时长更长的 License。
ERR_LICENSE_LIMITED_PERIOD	4: 当前时间段受 License 限制，不能进行通话。你需要换一个 License 允许的时间段进行通话，或联系 sales.nosp@m.@she.nosp@m.ngwan.nosp@m.g.cn 购买通话时间段更长的 License。
ERR_LICENSE_DIFF_DEVICES	5: License 已在其他设备中使用。一个 License 只允许在一台设备中使用，你需要重新调用 agora_rtc_init 并在 rtc_service_option_t 的 license_value 参数中填入一个新的 License。
ERR_LICENSE_INTERNAL	99: 内部原因。

network_event_type_e

enum network_event_type_e

网络事件类型。

枚举键	描述
NETWORK_EVENT_DOWN	网络连接失败。SDK 会尝试重新加入 RTC 频道和登录 RTM 系统。
NETWORK_EVENT_UP	网络连接成功。
NETWORK_EVENT_CHANGE	网络事件类型变更。SDK 会尝试重新加入 RTC 频道和登录 RTM 系统。

rdt_state

enum rdt_state

RDT 通道的连接状态。

枚举键	描述
RDT_STATE_CLOSED	初始状态，未连接 RDT 通道。该状态下用户不可以收发 RDT 消息。
RDT_STATE_OPENED	已连接 RDT 通道。该状态下用户可以收发 RDT 消息。
RDT_STATE_BLOCKED	RDT 通道中的发送缓冲区已满。该状态下用户不可以发送数据消息 (RDT_STREAM_DATA)，但可以发送控制消息 (RDT_STREAM_CMD)。
RDT_STATE_PENDING	正在重新连接 RDT 通道。 如果重新连接成功，则连接状态会变为 RDT_STATE_OPENED，SDK 会保留 RDT 通道中发送和接收缓冲区中的历史数据。 如果重新连接失败，则连接状态会变为 RDT_STATE_CLOSED，SDK 会清除 RDT 通道中发送和接收缓冲区中的历史数据。
RDT_STATE_BROKEN	与 RDT 通道的连接已损坏，SDK 会尝试重新连接。SDK 不论能否成功连接，都会清空 RDT 通道中发送和接收缓冲区中的历史数据。

rdt_stream_type

enum rdt_stream_type

RDT 消息类型。

枚举键	描述
RDT_STREAM_CMD	控制消息。发送优先级高，不受拥塞控制策略影响，不会阻塞发送。每秒至多发送 100 个消息包，每个消息包的长度至多为 256 B。
RDT_STREAM_DATA	数据消息。发送优先级低，受拥塞控制策略影响，如果缓冲区满了，则消息会发送失败。不限制发送的消息包数量，每个消息包的长度至多为 128 KB。
RDT_STREAM_COUNT	枚举值边界。

rtc_log_level_e

enum rtc_log_level_e

日志输出级别。

枚举键	描述
RTC_LOG_DEFAULT	0：（默认）输出 EMERG、ALERT、CRIT、ERROR、WARNING、NOTICE 级别的日志。
RTC_LOG_EMERG	1：输出 EMERG 级别的日志。
RTC_LOG_ALERT	2：输出 EMERG、ALERT 级别的日志。
RTC_LOG_CRIT	3：输出 EMERG、ALERT、CRIT 级别的日志。
RTC_LOG_ERROR	4：输出 EMERG、ALERT、CRIT、ERROR 级别的日志。
RTC_LOG_WARNING	5：输出 EMERG、ALERT、CRIT、ERROR、WARNING 级别的日志。
RTC_LOG_NOTICE	6：（默认）输出 EMERG、ALERT、CRIT、ERROR、WARNING、NOTICE 级别的日志。
RTC_LOG_INFO	7：输出 EMERG、ALERT、CRIT、ERROR、WARNING、NOTICE、INFO 级别的日志。
RTC_LOG_DEBUG	8：输出所有 API 日志信息。如果你想获取最完整的日志，可以将日志级别设为该等级。

rtm_err_code_e

enum rtm_err_code_e

RTM 错误码。

枚举键	描述
ERR_RTM_OK	0: 方法调用成功或登录成功。
ERR_RTM_FAILED	1: 通用错误。你可以根据日志文件排查问题。
ERR_RTM_LOGIN_REJECTED	2: 声网服务器拒绝了登录云信令 (原 RTM) 的请求。你需要检查 RTM Token、App ID、User ID 是否符合要求。
ERR_RTM_INVALID_RTM_UID	3: 云信令 (原 RTM) 用户 ID 无效。你需要检查 User ID 是否符合要求。
ERR_RTM_LOGIN_INVALID_TOKEN	5: 云信令 (原 RTM) Token 无效。你需要检查 Token 是否符合要求。
ERR_RTM_LOGIN_NOT_AUTHORIZED	7: 未经授权的登录。你需要先进行登录，再进行其他操作。
ERR_RTM_NOTICE_KICKED_OUT	8: 被踢出频道。你需要确保用户 ID 的唯一性。
ERR_RTM_NOTICE_INTERRUPT	9: 服务器连接中断。你需要检查网络是否正常。
ERR_RTM_INVALID_APP_ID	101: 云信令 (原 RTM) App ID 无效。你需要检查 App ID 是否符合要求。
WARN_RTM_LOOKUP_CHANNEL_REJECTED	105: 声网服务器拒绝了查询云信令 (原 RTM) 频道的请求。你需要检查 RTM Token 是否符合要求。
ERR_RTM_TOKEN_EXPIRED	109: 云信令 (原 RTM) Token 已过期。你需要重新生成 RTM Token。
ERR_RTM_INVALID_TOKEN	110: 云信令 (原 RTM) Token 无效。你需要检查 Token 是否符合要求。

rtm_event_type_e

enum rtm_event_type_e

RTM 云信令 (原 RTM) 事件类型。

枚举键	描述
RTM_EVENT_TYPE_LOGIN	0: 用户成功登录云信令 (原 RTM) 服务。
RTM_EVENT_TYPE_KICKOFF	1: 用户被踢出。
RTM_EVENT_TYPE_EXIT	2: 用户成功登出云信令 (原 RTM) 服务。

rtm_msg_state_e

enum rtm_msg_state_e

RTM 消息的发送状态。

枚举键	描述
RTM_MSG_STATE_INIT	0: 初始状态。
RTM_MSG_STATE_RECEIVED	1: 消息已接收。
RTM_MSG_STATE_UNREACHABLE	2: 消息未送达。

user_offline_reason_e

enum user_offline_reason_e

远端用户下线的原因。

枚举键	描述
USER_OFFLINE_QUIT	0: 远端用户主动离开频道。
USER_OFFLINE_DROPPED	1: 因过长时间收不到远端用户的数据包，SDK 判定该远端用户超时掉线。注意：在网络连接不稳定时，该判定可能会有误。建议使用云信令 SDK 来做可靠的掉线检测。
USER_OFFLINE_BECOME_AUDIENCE	2: 远端用户的角色从主播切换为观众。

video_data_type_e

enum video_data_type_e

视频编码格式。

枚举键	描述
VIDEO_DATA_TYPE_YUV420	0: YUV420 （暂不支持）
VIDEO_DATA_TYPE_H264	2: H264
VIDEO_DATA_TYPE_H265	3: H265
VIDEO_DATA_TYPE_GENERIC	6: Generic
VIDEO_DATA_TYPE_GENERIC_JPEG	20: Generic JPEG

video_frame_type_e

enum video_frame_type_e

视频帧类型。

枚举键	描述
VIDEO_FRAME_AUTO_DETECT	0: 未知。SDK 会自行判断帧类型。
VIDEO_FRAME_KEY	3: 关键帧。
VIDEO_FRAME_DELTA	4: Delta 帧，例如 P-Frame。

video_orientation_e

enum video_orientation_e

已编码视频帧的旋转角度。

枚举键	描述
VIDEO_ORIENTATION_0	0: （默认）顺时针旋转 0 度。
VIDEO_ORIENTATION_90	1: 顺时针旋转 90 度。
VIDEO_ORIENTATION_180	2: 顺时针旋转 180 度。
VIDEO_ORIENTATION_270	3: 顺时针旋转 270 度。

video_stream_type_e

enum video_stream_type_e

视频流类型。

枚举键	描述
VIDEO_STREAM_HIGH	0: 视频大流。分辨率和码率较高。
VIDEO_STREAM_LOW	1: 视频小流。分辨率和码率较低。

函数说明

agora_rtc_config_log()

agora_api int agora_rtc_config_log	(	int	size_per_file,
		int	max_file_count
	)

配置 SDK 的日志文件。

参数

参数名	描述
size_per_file [in]	每份日志文件的大小（字节）。取值范围为 [0,10 × 1024 × 1024]。默认值为 1 × 1024 × 1024，即 1 MB。如果你将此参数设为 0，则代表关闭日志功能。
max_file_count [in]	日志文件数。取值范围为 [0,100]。默认值为 10。如果你将此参数设为 0，则代表关闭日志功能。

返回值

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

agora_rtc_create_connection()

agora_api int agora_rtc_create_connection

(

connection_id_t *

conn_id

)

创建 Connection。

你需要在加入频道前调用该方法创建 Connection。如需使用同一个用户 ID 加入不同频道，或者使用不同用户 ID 加入同一个频道，则你需要多次调用该方法创建多个 Connection，然后再使用对应的 Connection ID 加入频道。

参数

参数名	描述
conn_id [out]	Connection ID。

返回值

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

agora_rtc_destroy_connection()

agora_api int agora_rtc_destroy_connection

(

connection_id_t

conn_id

)

销毁 Connection。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。

返回值

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

agora_rtc_err_2_str()

agora_api const char * agora_rtc_err_2_str

(

int

err

)

将错误码转为静态字符串，以便查看错误描述。

注解

使用后不必释放。

参数

参数名	描述
err [in]	错误码。

返回值

静态字符串。

agora_rtc_fini()

agora_api int agora_rtc_fini

(

void

)

释放所有由 agora_rtc_init 方法分配给 RTSA 服务的资源。

返回值

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

agora_rtc_get_connection_info()

agora_api int agora_rtc_get_connection_info	(	connection_id_t	conn_id,
		connection_info_t *	conn_info
	)

获取 Connection 信息。

参数

参数名	描述
conn_id [in]	Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。
conn_info [out]	Connection 信息。详见 connection_info_t 。

返回值

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

agora_rtc_get_rdt_status_info()

agora_api int agora_rtc_get_rdt_status_info	(	connection_id_t	conn_id,
		uint32_t	remote_uid,
		rdt_status_info_t *	info
	)

获取 RDT 通道的信息。

自从

v1.9.2

该方法可以获取当前 RDT 通道的连接状态和缓冲区长度，从而判断远端用户是否成功接收 RDT 消息、本地用户是否可以继续发送 RDT 消息。例如，发送缓冲区长度 (send_queue_size) 为 0 表示远端用户已接收完 RDT 消息。

参数

参数名	描述
conn_id [in]	Connection ID。
remote_uid [in]	远端用户的用户 ID。
info [out]	RDT 通道的信息。详见 rdt_status_info 。

返回值

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

agora_rtc_get_version()

const char * agora_rtc_get_version

(

void

)

获取 SDK 版本。

返回值

包含 SDK 版本信息的静态字符串。

agora_rtc_init()

agora_api int agora_rtc_init	(	const char *	app_id,
		const agora_rtc_event_handler_t *	event_handler,
		rtc_service_option_t *	option
	)

初始化 RTSA 服务。

注解

• 每条进程只能初始化一次。
• SDK 每次初始化时会在指定的目录下自动创建一个新文件夹（随机命名），用于存放此次运行的日志。 SDK 不负责回收上一次初始化时创建的文件夹。为了避免日志占用过多空间，建议每次初始化之前先清空日志文件夹。

参数

参数名	描述
app_id [in]	声网为 App 开发者签发的 APP ID。
event_handler [in]	用于处理 SDK 事件的一系列回调。详见 agora_rtc_event_handler_t 。
option [in]	服务配置选项，如果不需要设置则请置空。详见 rtc_service_option_t 。

返回值

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

agora_rtc_join_channel()

agora_api int agora_rtc_join_channel	(	connection_id_t	conn_id,
		const char *	channel_name,
		uint32_t	uid,
		const char *	token,
		rtc_channel_options_t *	options
	)

加入指定 Connection 所关联的 RTC 频道。

该方法让本地用户加入指定频道。同一个频道内使用相同 App ID 的用户可以互相传输数据。

注解

• 你可以同时加入多个频道，所有你加入的频道都能接收到你发送的音视频数据。
• 如需使用同一个用户 ID 加入不同频道，或者使用不同用户 ID 加入同一个频道，则你需要创建不同的 Connection 并在调用 agora_rtc_join_channel 方法时填入对应的 Connection ID。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
channel_name [in]	频道名，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）： 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
uid [in]	用户 ID。
token [in]	用于鉴权的 RTC Token。 如果你的声网项目启用的是 App ID 鉴权，可以将该值设为 NULL。 如果你的声网项目启用的是 App ID + Token 鉴权，你需要将该值设为应用服务端生成的 RTC Token。详见使用 RTC Token 鉴权。自 1.8.0 版本起，RTSA Lite SDK 支持 AccessToken2。1.8.0 之前的版本支持 AccessToken。
options [in]	频道设置选项。详见 rtc_channel_options_t 。

返回值

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

agora_rtc_leave_channel()

agora_api int agora_rtc_leave_channel

(

connection_id_t

conn_id

)

离开指定 Connection 所关联的 RTC 频道。

停止在某频道传输数据后需要离开该频道。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。

返回值

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

agora_rtc_license_gen_credential()

agora_api int agora_rtc_license_gen_credential	(	char *	credential,
		unsigned int *	credential_len
	)

弃用:

自 v1.9.0 废弃。

生成设备唯一标识 Credential。

注解

该方法仅用于声网 License 机制。如不使用 License，可忽略该方法。

参数

参数名	描述
credential [out]	用于存放 Credential 的缓冲区。
credential_len [in,out]	缓冲区大小（字节）。 输入值用于确认缓冲区的可用长度（字节），需大于 AGORA_CREDENTIAL_MAX_LEN。 输出值为 Credential 的实际长度（字节）。

返回值

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

agora_rtc_license_verify()

agora_api int agora_rtc_license_verify	(	const char *	certificate,
		int	certificate_len,
		const char *	credential,
		int	credential_len
	)

弃用:

自 v1.9.0 废弃。改用 on_license_validation_failure 回调获取 License 校验失败的错误码。

认证 SDK。

启用了声网 License 机制后，安装了 SDK 的设备只有通过 Certificate 验证 才能加入声网频道、使用数据传输功能。

注解

• 该方法仅用于声网 License 机制。如不使用 License，可忽略该方法。
• 该方法必须在 agora_rtc_init 前调用。认证通过后，你才能有效调用 RTSA SDK 的其他 API。

参数

参数名	描述
certificate [in]	许可证 Certificate。
certificate_len [in]	许可证长度。
credential [in]	凭证 Credential。
credential_len [in]	凭证长度。

返回值

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

agora_rtc_login_rtm()

agora_api int agora_rtc_login_rtm	(	const char *	rtm_uid,
		const char *	rtm_token,
		const agora_rtm_handler_t *	handler
	)

登录云信令 (原 RTM) 服务。

参数

参数名	描述
rtm_uid [in]	云信令 (原 RTM) 用户 ID。该字符串不可超过 64 字节。不可设为空、NULL 或 "NULL"。以下为支持的字符集范围: 26 个小写英文字母 a-z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
rtm_token [in]	用于登录云信令 (原 RTM) 系统的动态密钥。详见《校验用户权限》。如果你没有开启 Token 鉴权，此参数可设为 NULL。
handler [in]	云信令 (原 RTM) 回调。详见 agora_rtm_handler_t 。

返回值

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

agora_rtc_logout_rtm()

agora_api int agora_rtc_logout_rtm

(

void

)

登出云信令 (原 RTM) 服务。

返回值

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

agora_rtc_mute_local_audio()

agora_api int agora_rtc_mute_local_audio	(	connection_id_t	conn_id,
		bool	mute
	)

对指定 Connection 所关联的 RTC 频道暂停/恢复发送本地音频流。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
mute [in]	暂停/恢复发送本地音频流： 0:（默认）发送本地音频流。 其他值: 暂停发送本地音频流。

返回值

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

agora_rtc_mute_local_video()

agora_api int agora_rtc_mute_local_video	(	connection_id_t	conn_id,
		bool	mute
	)

指定 Connection 所关联的 RTC 频道暂停/恢复发送本地视频流。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
mute [in]	暂停/恢复发送本地视频流： 0:（默认）发送本地视频流。 其他值: 暂停发送本地视频流。

返回值

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

agora_rtc_mute_remote_audio()

agora_api int agora_rtc_mute_remote_audio	(	connection_id_t	conn_id,
		uint32_t	remote_uid,
		bool	mute
	)

暂停/恢复接收指定 Connection 所关联的 RTC 频道内的指定远端用户的音频流。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
remote_uid [in]	远端用户 ID。设为 0 则停止接收频道内所有用户的音频流。
mute [in]	暂停/恢复接收远端音频流： false:（默认）接收远端音频流。 true: 暂停接收远端音频流。

返回值

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

agora_rtc_mute_remote_video()

agora_api int agora_rtc_mute_remote_video	(	connection_id_t	conn_id,
		uint32_t	remote_uid,
		bool	mute
	)

暂停/恢复接收指定 Connection 所关联的 RTC 频道内的指定远端用户的视频流。

可以先暂停接收所有频道的视频流，然后恢复接收指定频道的视频流。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
remote_uid [in]	远端用户 ID。设为 0 则停止接收频道内所有用户的视频流。
mute [in]	暂停/恢复接收远端视频流： 0: （默认）接收远端视频流。 其他值: 暂停接收远端视频流。

返回值

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

agora_rtc_notify_network_event()

agora_api int agora_rtc_notify_network_event

(

network_event_type_e

event

)

设置网络状态。

参数

参数名	描述
event	网络状态。详见 network_event_type_e 。

返回值

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

agora_rtc_renew_token()

agora_api int agora_rtc_renew_token	(	connection_id_t	conn_id,
		const char *	token
	)

更新指定 Connection 所关联的 RTC 频道的 RTC Token。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
token [in]	声网 RTC Token。

返回值

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

agora_rtc_request_video_key_frame()

agora_api int agora_rtc_request_video_key_frame	(	connection_id_t	conn_id,
		uint32_t	remote_uid,
		video_stream_type_e	stream_type
	)

请求指定 Connection 所关联的 RTC 频道内的指定远端用户为指定远端视频流生成关键帧。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
remote_uid [in]	远端用户 ID。如果为频道内的所有用户，则设为 0。
stream_type [in]	视频流类型。详见 video_stream_type_e 。

返回值

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

agora_rtc_send_audio_data()

agora_api int agora_rtc_send_audio_data	(	connection_id_t	conn_id,
		const void *	data_ptr,
		size_t	data_len,
		audio_frame_info_t *	info_ptr
	)

向指定 Connection 所关联的 RTC 频道发送音频帧。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
data_ptr [in]	音频包数据。
data_len [in]	音频包数据大小（字节）。
info_ptr [in]	音频帧配置，详见 audio_frame_info_t 。

返回值

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

agora_rtc_send_rdt_msg()

agora_api int agora_rtc_send_rdt_msg	(	connection_id_t	conn_id,
		uint32_t	remote_uid,
		rdt_stream_type_e	type,
		const void *	msg,
		size_t	length
	)

发送 RDT（Reliable Data Transmission，可靠数据传输）消息。

自从

v1.9.2

在文件传输、文件下载等需要可靠传输的场景中，你可以参考如下步骤发送 RDT 消息：

1. 在 RDT 通道中建立连接：在加入频道时，将 rtc_channel_options_t 中的 auto_connect_rdt 参数设置为 true，主动与频道内其他用户建立连接。
2. 获取 RDT 通道的连接状态：监听 on_rdt_state 回调。当在 RDT 通道中成功建立连接时，连接状态会变为 RDT_STATE_OPENED，此时才可进行下一步。
3. 调用 agora_rtc_send_rdt_msg 方法发送 RDT 消息：你可以根据需要发送控制消息 (RDT_STREAM_CMD) 或数据消息 (RDT_STREAM_DATA)，二者区别如下：

• 控制消息。发送优先级高，不受拥塞控制策略影响，不会阻塞发送。每秒至多发送 100 个消息包，每个消息包的长度至多为 256 B。
• 数据消息。发送优先级低，受拥塞控制策略影响，如果缓冲区满了，则消息会发送失败。不限制发送的消息包数量，每个消息包的长度至多为 128 KB。

成功发送 RDT 消息后，远端用户会收到 on_rdt_msg 回调。你可以调用 agora_rtc_get_rdt_status_info 方法获取远端用户是否接收完消息等信息。

参数

参数名	描述
conn_id [in]	Connection ID。
remote_uid [in]	远端用户的用户 ID。
type [in]	RDT 消息类型。详见 rdt_stream_type 。
msg [in]	RDT 消息负载。
length [in]	RDT 消息长度。

返回值

• 0: 方法调用成功。
• <0: 方法调用失败。
  • RTC_ERR_RDT_USER_NOT_EXIST (-8): 频道内不存在该远端用户。
  • RTC_ERR_RDT_USER_NOT_READY (-9): 未成功与远端用户建立连接。你需要等 RDT 通道的连接状态变为 RDT_STATE_OPENED 后重新调用该方法。
  • RTC_ERR_RDT_DATA_BLOCKED (-10): 发送缓冲区已满。你需要等 RDT 通道的连接状态变为 RDT_STATE_OPENED 后重新调用该方法。
  • RTC_ERR_RDT_CMD_EXCEED_LIMIT (-11): 控制消息的数量超过限制。每秒发送的控制消息包不能超过 100 个。

agora_rtc_send_rtm_data()

agora_api int agora_rtc_send_rtm_data	(	const char *	rtm_uid,
		const void *	msg,
		size_t	msg_len,
		uint32_t	msg_id
	)

通过云信令 (原 RTM) 服务发送消息。

RTM 默认开启基于 TLS 加密的传输层安全保护且不可关闭。

注解

成功登录云信令 (原 RTM) 服务并收到 on_rtm_event 回调时才可以发送消息。发送频率不能超过每秒 60 条。

参数

参数名	描述
rtm_uid [in]	云信令 (原 RTM) 用户 ID。
msg [in]	消息内容。仅支持 UTF-8 编码。
msg_len [in]	消息长度，单位是字节，取值至多为 31 KB。
msg_id [in]	消息 ID。

返回值

• 0: 方法调用成功。
• <0: 方法调用失败。
  • RTM_ERR_NOT_LOGINED (-1001): 未登录 RTM 系统
  • RTM_ERR_SEND_TO_SELF (-1002): 在 rtm_uid 参数中误填了自己的用户 ID。
  • RTM_ERR_EXCEED_MSG_SIZE (-1003): RTM 消息长度超出限制。消息长度至多为 31 KB。
  • RTM_ERR_EXCEED_MSG_CNT (-1004): 发送频率超出限制。每秒至多发送 60 条消息。
  • RTM_ERR_EXCEED_TCP_SKB (-1005): 消息通道已满。等待一秒后重新发送。

agora_rtc_send_video_data()

agora_api int agora_rtc_send_video_data	(	connection_id_t	conn_id,
		const void *	data_ptr,
		size_t	data_len,
		video_frame_info_t *	info_ptr
	)

向指定 Connection 所关联的 RTC 频道发送视频帧。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
data_ptr [in]	视频包数据。
data_len [in]	视频包数据大小（字节）。
info_ptr [in]	视频帧配置，详见 video_frame_info_t 。

返回值

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

agora_rtc_set_bwe_param()

agora_api int agora_rtc_set_bwe_param	(	connection_id_t	conn_id,
		uint32_t	min_bps,
		uint32_t	max_bps,
		uint32_t	start_bps
	)

设置 bandwidth estimation (BWE) 参数。

参数

参数名	描述
conn_id [in]	Connection ID。设为 CONNECTION_ID_ALL 表示针对当前创建的所有 Connection 。你可以通过 agora_rtc_create_connection 创建 Connection。
min_bps [in]	最小码率，单位为 bps。
max_bps [in]	最大码率，单位为 bps。
start_bps [in]	起始码率，单位为 bps。

返回值

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

agora_rtc_set_cloud_proxy()

agora_api int agora_rtc_set_cloud_proxy

(

cloud_proxy_type_e

type

)

设置声网云代理服务。

参数

参数名	描述
type [in]	云代理类型。参考 cloud_proxy_type_e 。

返回值

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

agora_rtc_set_log_level()

agora_api int agora_rtc_set_log_level

(

rtc_log_level_e

level

)

设置 SDK 的日志输出等级。

设置一个级别后，你可以看到该级别及之前所有级别的日志信息。

参数

参数名	描述
level [in]	日志输出等级。详见 rtc_log_level_e 。

返回值

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

agora_rtc_set_params()

agora_api int agora_rtc_set_params

(

const char *

params

)

通过 JSON 配置 SDK 提供技术预览或特别定制功能。

JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

参数

参数名	描述
params [in]	JSON 字符串形式的参数。

返回值

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