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 (31 * 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_INVALID_PARAM	2: 方法中设置无效的参数，例如指定的频道命中含有非法字符。请重新设置参数
ERR_INVALID_STATE	3: 当前状态下调用 API 无效，例如关闭本地采集后就无法发布音视频。
ERR_NOT_SUPPORTED	4: 当前状态下不支持该操作。
ERR_NOT_IN_CHANNEL	6: 当前连接状态是未成功加入频道。
ERR_NOT_INITIALIZED	7: 服务未完成初始化。请先调用 agora_rtc_init 方法。
ERR_NOT_EXIST_CONNECTION	8: 连接不存在。
ERR_TIMEDOUT	10: API 调用超时。有些方法调用需要 SDK 返回结果，如果处理时间过长（超过 10 秒），SDK 会返回该错误。
ERR_NO_MEMORY	11: 内存不足。
ERR_CALL_FAILED	12: API 调用失败。
ERR_NET_DOWN	14: 当前网络不可用。你需要检查系统网络连接状态。
ERR_JOIN_CHANNEL_REJECTED	17: 加入频道请求被拒绝，可能是因为本地用户已在频道内。你需要调整代码逻辑，避免用户加入同一频道。
ERR_LEAVE_CHANNEL_REJECTED	18: 离开频道被拒。如果本地用户已经不在频道内，试图调用 API 离开频道时会返回该错误。
ERR_LICENSE_VERIFICATION_FAILURE	23: License 未通过验证导致的 SDK 初始化失败。该错误码仅在老版本的 License 下会反馈。
ERR_ENCRYPTION	30: 加密错误。
ERR_DECRYPTION	31: 解密错误。
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 重新加入频道。 Token 过期可能的原因有：授权时间戳过期：Token 一旦生成，用户需要在 5 分钟内使用该 Token 加入频道，否则 Token 会失效。通话有效时间戳过期：通话有效时间戳指用户不再能使用声网服务（如被强制离开当前通话）的时间戳。这种情况下，Token 没有过期，但是用户也会被踢出频道。
ERR_INVALID_TOKEN	110: RTC Token 无效。可能的原因是：在控制台中启用了 Token 鉴权，但调用 API 时没有传入 Token。用户加入频道时使用的 `uid` 和生成 Token 时传入的 `uid` 不一致。
ERR_DYNAMIC_TOKEN_BUT_USE_STATIC_KEY	115: 在控制台中启用了 Token 鉴权，但调用 `join` 加入频道时传入的是 App ID。
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: 该客户端被服务器禁用。你需要检查 License 是否正确。
ERR_AUDIO_CODEC_NOT_SUPPORT	200: SDK 不支持当前使用的音频编解码器。
ERR_AUDIO_INVALID_PCM_LEN	201: PCM 音频数据长度无效。
ERR_AUDIO_INVALID_CODEC_PARAM	202: 音频编解码器参数无效。
ERR_AUDIO_DECODER_NOT_MATCH	221: 音频解码器和输入的音频数据类型不匹配。音频编解码器的发送和接收格式必需一致。
ERR_AUDIO_DECODER_NOT_ENABLE	222: 音频解码器模块未开启。
ERR_VIDEO_SEND_OVER_BANDWIDTH_LIMIT	300: 视频数据发送太快，且超出了宽带限制。当前发送速度下很可能发生丢包。
ERR_VIDEO_SEND_PACKETIZE_FAILED	301: 视频包打包失败。
ERR_RDT_USER_NOT_EXIST	600: 用户不存在。
ERR_RDT_USER_NOT_READY	601: 用户状态未准备好。
ERR_RDT_DATA_BLOCKED	602: 数据被拦截。
ERR_RDT_CMD_EXCEED_LIMIT	603: 指令超出限制。
ERR_RDT_DATA_EXCEED_LIMIT	604: 数据消息大小超出限制。
ERR_RTM_NOT_LOGINED	1001: 未登录 RTM 系统。
ERR_RTM_HAD_LOGINED	1002: 已登录 RTM 系统。
ERR_RTM_SEND_TO_SELF	1003: 在 `rtmUid` 参数中误填了自己的用户 ID。
ERR_RTM_EXCEED_MSG_SIZE	1004: RTM 消息长度超出限制。消息长度至多为 31 KB。
ERR_RTM_EXCEED_MSG_CNT	1005: RTM 消息发送频率超出限制。每秒至多发送 60 条消息。
ERR_RTM_EXCEED_TCP_SKB	1006: 消息通道已满。等待一秒后重新发送。

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。

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: 内部原因。

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_LOCAL_NETDOWN	8: 检测到网卡出现故障
ERR_RTM_LOCAL_INTERRUPT	9: 本地用户网络中断。你需要检查网络是否正常。
ERR_RTM_LOCAL_TIMEOUT	10: 本地用户没有收到服务端响应的心跳包。
ERR_RTM_SERVER_TIMEOUT	11: 服务器没有收到本地用户发动的心跳包。
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: 用户被踢出。可能的原因是 UID 重复。
RTM_EVENT_TYPE_EXIT	2: 用户退出 RTM 服务。可能得原因是： `ERR_RTM_SERVER_TIMEOUT`：服务器没有收到本地客户端发送的心跳包。 `ERR_RTM_LOCAL_INTERRUPT`：本地用户网络中断。 `ERR_RTM_LOCAL_TIMEOUT`：本地客户端没收到服务端响应的心跳包。 `ERR_RTM_LOCAL_NETDOWN`：检测到网卡出现故障。在该状态下，SDK 会自动尝试重连，如果重连成功，则可以恢复登录。

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`: 消息到达了服务端，但是不确定是否到达了远端用户。
RTM_MSG_STATE_TIMEOUT	服务端 10 秒内没有响应，SDK 会删除这条未知状态的消息。

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_strerror()

agora_api const char * agora_rtc_license_strerror ( int err )

获取 Licence 错误描述。

参数

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

返回值

表示错误描述的字符串。

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_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_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 消息：

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

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

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

注解

每条连接限制传输 4 Mbps。如果超出，会返回如下错误码：

ERR_RDT_CMD_EXCEED_LIMIT(603)，控制消息的数量超过限制。
ERR_RDT_DATA_EXCEED_LIMIT(604): 数据数据大小超出限制。

参数

参数名	描述
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(600): 频道内不存在该远端用户。
- RTC_ERR_RDT_USER_NOT_READY(601): 未成功与远端用户建立连接。你需要等 RDT 通道的连接状态变为 RDT_STATE_OPENED 后重新调用该方法。
- RTC_ERR_RDT_DATA_BLOCKED(602): 发送缓冲区已满。你需要等 RDT 通道的连接状态变为 RDT_STATE_OPENED 后重新调用该方法。
- RTC_ERR_RDT_CMD_EXCEED_LIMIT(603): 控制消息的数量超过限制。每秒发送的控制消息包不能超过 4 Mbps。 . - ERR_RDT_DATA_EXCEED_LIMIT(604): 数据数据大小超出限制。

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_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	(	connection_id_t	conn_id,
		const char *	params )

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

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

参数

参数名	描述
connid [in]	Connection ID。如果设为 CONNECTION_ID_ALL(0) 则表示所有 Connection。
params [in]	JSON 字符串形式的参数。

返回值

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

宏定义说明​

agora_api​

AGORA_CERTIFICATE_MAX_LEN​

AGORA_CREDENTIAL_MAX_LEN​

AGORA_LICENSE_VALUE_LEN​

AGORA_RTC_CHANNEL_NAME_MAX_LEN​

AGORA_RTC_PRODUCT_ID_MAX_LEN​

AGORA_RTC_USER_ID_MAX_LEN​

AGORA_RTM_DATA_MAX_LEN​

AGORA_RTM_UID_MAX_LEN​

CONNECTION_ID_ALL​

CONNECTION_ID_INVALID​

类型定义说明​

connection_id_t​

rdt_state_e​

rdt_status_info_t​

rdt_stream_type_e​

video_frame_rate_e​

agora_err_code_e

area_code_e

audio_codec_type_e

audio_data_type_e

crypto_mode_e

license_err_reason_e

rdt_state

rdt_stream_type

rtc_log_level_e

rtm_err_code_e

rtm_event_type_e

rtm_msg_state_e

user_offline_reason_e

video_data_type_e

video_frame_type_e

video_orientation_e

video_stream_type_e

函数说明​

agora_rtc_config_log()

参数​

返回值​

agora_rtc_create_connection()

参数​

返回值​

agora_rtc_destroy_connection()

参数​

返回值​

agora_rtc_err_2_str()

参数​

返回值​

agora_rtc_fini()

返回值​

agora_rtc_get_connection_info()

参数​

返回值​

agora_rtc_get_rdt_status_info()

参数​

返回值​

agora_rtc_get_version()

返回值​

agora_rtc_init()

参数​

返回值​

agora_rtc_join_channel()

参数​

返回值​

agora_rtc_leave_channel()

参数​

返回值​

agora_rtc_license_gen_credential()

参数​

返回值​

agora_rtc_license_strerror()

参数​

返回值​

agora_rtc_license_verify()

参数​

返回值​

agora_rtc_login_rtm()

参数​

返回值​

agora_rtc_logout_rtm()

宏定义说明

agora_api

AGORA_CERTIFICATE_MAX_LEN

AGORA_CREDENTIAL_MAX_LEN

AGORA_LICENSE_VALUE_LEN

AGORA_RTC_CHANNEL_NAME_MAX_LEN

AGORA_RTC_PRODUCT_ID_MAX_LEN

AGORA_RTC_USER_ID_MAX_LEN

AGORA_RTM_DATA_MAX_LEN

AGORA_RTM_UID_MAX_LEN

CONNECTION_ID_ALL

CONNECTION_ID_INVALID

类型定义说明

connection_id_t

rdt_state_e

rdt_status_info_t

rdt_stream_type_e

video_frame_rate_e

函数说明

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值