# agora_rtc_api.h 文件参考 (/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## 宏定义说明 [#宏定义说明]
### __agora_api__ [#agora_api]
枚举值
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](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a6187076d897f0b56cb20942368c15aaa) 方法。
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](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a6c29ff27f04623526a164cf6e5dcd738) 使用新生成的 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_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_TOO_MANY_DATA_STREAMS
621: 创建了太多的数据流。
ERR_DATA_STREAM_SIZE_TOO_LARGE
622: 创建的数据流大小超过了 1 KB。
ERR_NOT_EXIST_STREAM_ID
623: 指定的数据流 ID 不存在。
ERR_DATA_STREAM_BITRATE_LIMIT
624: 数据流的发送码率超过了 6 Kbps 的限制。
ERR_DATA_STREAM_SEND_TOO_OFTEN
625: 数据流发送太频繁,超过了每秒 60 个数据包的限制。
ERR_DATA_STREAM_TIME_OUT
626: 接收数据流的远端用户连接超时。
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_SND_BUFFER
1006: 消息通道已满。等待一秒后重新发送。
`ERR_RTM_CUSTOM_TYPE_OUT_OF_LENGTH`
1007: 自定义消息类型长度超出限制。
`ERR_RTM_CHANNEL_EXCEED_LIMIT`
1008: RTM 频道订阅数量超过限制。
`ERR_RTM_CHANNEL_ALREADY_JOINED`
1009: 已订阅该 RTM 频道。
`ERR_RTM_CHANNEL_NOT_JOINED`
1010: 未订阅该 RTM 频道。
`ERR_RTM_CHANNEL_SUBSCRIBE_TIMEOUT`
1011: RTM 频道订阅超时。
枚举值
AREA_CODE_DEFAULT
同 AREA_CODE_GLOB 全球。
AREA_CODE_CN
中国大陆。
AREA_CODE_NA
北美。
AREA_CODE_EU
欧洲。
AREA_CODE_AS
亚洲(除中国大陆)。
AREA_CODE_JP
日本。
AREA_CODE_IN
印度。
AREA_CODE_GLOB
全球 (默认)。
枚举值
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_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_HEAAC2
10: HEAAC2,采样率为 48000 Hz。
AUDIO_DATA_TYPE_AACLC_8K_2CH
11: AACLC3,采样率为 8000 Hz,双声道。
AUDIO_DATA_TYPE_AACLC_16K_2CH
12: AACLC2,采样率为 16000 Hz,双声道。
AUDIO_DATA_TYPE_AACLC_2CH
13: AACLC,采样率为 48000 Hz,双声道。
AUDIO_DATA_TYPE_HEAAC_2CH
14: HEAAC,采样率为 48000 Hz,双声道。
AUDIO_DATA_TYPE_HEAAC2_2CH
15: HEAAC2,采样率为 48000 Hz,双声道。
AUDIO_DATA_TYPE_AACLC1
16: AACLC1,采样率为 44100 Hz。
AUDIO_DATA_TYPE_AACLC1_2CH
17: AACLC1_2CH,采样率为 48000 Hz,双声道。
AUDIO_DATA_TYPE_HWAAC
18: HWAAC,采样率为 32000 Hz。
AUDIO_DATA_TYPE_OPUSSWB
20: OPUSSWB,采样率为 32000 Hz。
AUDIO_DATA_TYPE_OPUSFB_2CH
21: OPUSFB,采样率为 48000 Hz,双声道。
AUDIO_DATA_TYPE_PCM
100: 用于传输的 PCM 数据。
AUDIO_DATA_TYPE_GENERIC
253: Generic。
AUDIO_DATA_TYPE_UNKNOW
254: 音频数据类型未知。
枚举值
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
枚举值边界。
枚举值
ERR_LICENSE_INVALID
1: 无效 License。你需要重新调用 [agora_rtc_init](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a6187076d897f0b56cb20942368c15aaa) 并在 [rtc_service_option_t](/zh-CN/api-reference/rtsa/c/structrtc-service-option-t) 的 license_value 参数中填入正确的 License。
ERR_LICENSE_EXPIRE
2: License 过期。你需要联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 进行续费。
ERR_LICENSE_MINUTES_EXCEED
3: License 包含的通话时长已用完。你需要联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 购买通话时长更长的 License。
ERR_LICENSE_LIMITED_PERIOD
4: 当前时间段受 License 限制,不能进行通话。你需要换一个 License 允许的时间段进行通话,或联系 [sales@shengwang.cn](mailto:sales@shengwang.cn) 购买通话时间段更长的 License。
ERR_LICENSE_DIFF_DEVICES
5: License 已在其他设备中使用。一个 License 只允许在一台设备中使用,你需要重新调用 [agora_rtc_init](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a6187076d897f0b56cb20942368c15aaa) 并在 [rtc_service_option_t](/zh-CN/api-reference/rtsa/c/structrtc-service-option-t) 的 license_value 参数中填入一个新的 License。
ERR_LICENSE_INTERNAL
99: 内部原因。
枚举值
RDT_STATE_CLOSED
初始状态,未连接 RDT 通道。该状态下用户不可以收发 RDT 消息。
RDT_STATE_OPENED
已连接 RDT 通道。该状态下用户可以收发 RDT 消息。
RDT_STATE_BLOCKED
RDT 通道中的发送缓冲区已满。该状态下用户不可以发送数据消息 ([RDT_STREAM_DATA](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a39c4148522dd2ce2d729b8f264e7b955a04654c2c006244086c3b455375d10766)),但可以发送控制消息 ([RDT_STREAM_CMD](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a39c4148522dd2ce2d729b8f264e7b955a7f3a2a89aa98975482c02131bd224b46))。
RDT_STATE_PENDING
正在重新连接 RDT 通道。
- 如果重新连接成功,则连接状态会变为 [RDT_STATE_OPENED](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a29a5e8defc6abf737109eb0b5349ac84ae07e035ba0878b81839416a8fde5cf1c),SDK 会保留 RDT 通道中发送和接收缓冲区中的历史数据。
- 如果重新连接失败,则连接状态会变为 [RDT_STATE_CLOSED](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a29a5e8defc6abf737109eb0b5349ac84a757c5096332a339fdfe10488a955d6f5),SDK 会清除 RDT 通道中发送和接收缓冲区中的历史数据。
RDT_STATE_BROKEN
与 RDT 通道的连接已损坏,SDK 会尝试重新连接。SDK 不论能否成功连接,都会清空 RDT 通道中发送和接收缓冲区中的历史数据。
枚举值
RDT_STREAM_CMD
控制消息。发送优先级高,不受拥塞控制策略影响,不会阻塞发送。每秒至多发送 100 个消息包,每个消息包的长度至多为 256 B。
RDT_STREAM_DATA
数据消息。发送优先级低,受拥塞控制策略影响,如果缓冲区满了,则消息会发送失败。不限制发送的消息包数量,每个消息包的长度至多为 128 KB。
RDT_STREAM_COUNT
枚举值边界。
枚举值
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 日志信息。如果你想获取最完整的日志,可以将日志级别设为该等级。
枚举值
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_LOGIN
0: 用户成功登录 RTM 服务。
RTM_EVENT_TYPE_KICKOFF
1: 用户被踢出。可能的原因是 UID 重复。
RTM_EVENT_TYPE_EXIT
2: 用户退出 RTM 服务。可能得原因是:
- [ERR_RTM_SERVER_TIMEOUT](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a67e13664c08581f85cd18c0e36299395a86dfec717916e6a4390117d20a4fe93e):服务器没有收到本地客户端发送的心跳包。
- [ERR_RTM_LOCAL_INTERRUPT](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a67e13664c08581f85cd18c0e36299395a42ee38fc588f057ffa1d6cce5f1a8590):本地用户网络中断。
- [ERR_RTM_LOCAL_TIMEOUT](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a67e13664c08581f85cd18c0e36299395a81c8a98baffacb7cef2555975fa91c9d):本地客户端没收到服务端响应的心跳包。
- [ERR_RTM_LOCAL_NETDOWN](/zh-CN/api-reference/rtsa/c/agora-rtc-api-8h#a67e13664c08581f85cd18c0e36299395aff3cd211a9e47d717330db875292c2c0):检测到网卡出现故障。
在该状态下,SDK 会自动尝试重连,如果重连成功,则可以恢复登录。
枚举值
RTM_MESSAGE_TYPE_BINARY
0: 二进制消息。
RTM_MESSAGE_TYPE_STRING
1: 字符串消息。
枚举值
RTM_MSG_STATE_INIT
0: 初始状态。
RTM_MSG_STATE_RECEIVED
1: 消息已接收。
RTM_MSG_STATE_UNREACHABLE
2: 消息到达了服务端,但是不确定是否到达了远端用户。
RTM_MSG_STATE_TIMEOUT
服务端 10 秒内没有响应,SDK 会删除这条未知状态的消息。
枚举值
USER_OFFLINE_QUIT
0: 远端用户主动离开频道。
USER_OFFLINE_DROPPED
1: 因过长时间收不到远端用户的数据包,SDK 判定该远端用户超时掉线。注意:在网络连接不稳定时,该判定可能会有误。建议使用云信令 SDK 来做可靠的掉线检测。
USER_OFFLINE_BECOME_AUDIENCE
2: 远端用户的角色从主播切换为观众。
枚举值
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_AUTO_DETECT
0: 未知。SDK 会自行判断帧类型。
VIDEO_FRAME_KEY
3: 关键帧。
VIDEO_FRAME_DELTA
4: Delta 帧,例如 P-Frame。
枚举值
VIDEO_ORIENTATION_0
0: (默认)顺时针旋转 0 度。
VIDEO_ORIENTATION_90
1: 顺时针旋转 90 度。
VIDEO_ORIENTATION_180
2: 顺时针旋转 180 度。
VIDEO_ORIENTATION_270
3: 顺时针旋转 270 度。
枚举值
VIDEO_STREAM_HIGH
0: 视频大流。分辨率和码率较高。
VIDEO_STREAM_LOW
1: 视频小流。分辨率和码率较低。