agora_rtc_event_handler_t结构体 参考
- C
更新时间不可用
包含事件处理回调的结构体。
结构体成员变量说明
on_audio_data
void(* on_audio_data)(connection_id_t conn_id, uint32_t uid, uint16_t sent_ts, const void *data_ptr, size_t data_len, const audio_frame_info_t *info_ptr)收到频道内远端用户的音频帧回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 远端用户的用户 ID。 |
sent_ts | Unix 时间戳（ms）。标识远端用户调用 agora_rtc_send_audio_data 的时间。 |
data_ptr | 音频包数据。 |
data_len | 音频包数据长度（字节）。 |
info_ptr | 音频帧信息。详见 audio_frame_info_t 。 |
on_connection_lost
void(* on_connection_lost)(connection_id_t conn_id)连接丢失回调。
当 SDK 与服务器断开连接超过 10 秒时，SDK 会触发该回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
on_error
void(* on_error)(connection_id_t conn_id, int code, const char *msg)发生错误回调。
该回调方法表示 SDK 运行时出现了（网络或媒体相关的）错误。 通常情况下，SDK 上报的错误意味着 SDK 无法自动恢复，需要 App 干预或提示用户。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
code | 错误码，详见 agora_err_code_e 。 |
msg | 错误描述。 |
on_join_channel_success
void(* on_join_channel_success)(connection_id_t conn_id, uint32_t uid, int elapsed_ms)加入频道成功回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 本地用户 ID。 |
elapsed_ms | 从频道成功创建开始到发生此回调过去的时间（毫秒）。 |
on_key_frame_gen_req
void(* on_key_frame_gen_req)(connection_id_t conn_id, uint32_t uid, video_stream_type_e stream_type)频道内远端用户请求关键帧回调。
收到此回调后，发送端需生成一个新的关键帧。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 远端用户的用户 ID。 |
stream_type | 需要生成关键帧的视频流类型，详见 video_stream_type_e 。 |
on_license_validation_failure
void(* on_license_validation_failure)(connection_id_t conn_id, int error)设备 License 验证失败回调。
加入频道时，声网服务器会验证你在 agora_rtc_init 中传入的 License。如果 License 验证失败，则 SDK 会触发该回调，你可以根据收到的错误码处理问题。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
error | 错误码。详见 license_err_reason_e 。 |
on_local_user_registered
void(* on_local_user_registered)(const char *uname, uint32_t uid)本地用户注册回调。
| 参数名 | 描述 |
|---|---|
uname | 使用 agora_rtc_init 方法初始化时设置的 String 型用户名，该参数为必填，最大不超过 255 字节，不可设为 NULL。请确保用户名的唯一性。以下为支持的字符集范围（共 89 个字符）：
|
uid | 使用 agora_rtc_init 方法初始化时设置的用户 ID（32 位整型）。建议设置范围：1 到 (2³² - 1)，并保证唯一性。 0 是无效的 uid。如果将 uid 设为 0，系统将自动分配一个 UID。 |
on_media_ctrl_msg
void(* on_media_ctrl_msg)(connection_id_t conn_id, uint32_t uid, const void *payload, size_t length)收到远端用户发来的消息回调。
自从
v1.9.5
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID。 |
uid | 发送消息的用户 ID。 |
payload | 消息 Payload。 |
length | 消息 Payload 长度。 |
on_mixed_audio_data
void(* on_mixed_audio_data)(connection_id_t conn_id, const void *data_ptr, size_t data_len, const audio_frame_info_t *info_ptr)收到频道内本地用户和远端用户的混音数据回调。此回调每 20 ms 触发一次。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
data_ptr | 音频包数据。 |
data_len | 音频包数据长度（字节）。 |
info_ptr | 音频帧信息。详见 audio_frame_info_t 。 |
on_rdt_msg
void(* on_rdt_msg)(connection_id_t conn_id, uint32_t uid, rdt_stream_type_e type, const void *msg, size_t len)收到 RDT 消息回调。
自从
v1.9.2
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 远端用户的用户 ID。 |
type | RDT 消息类型。详见 rdt_stream_type 。 |
msg | RDT 消息负载。 |
len | RDT 消息长度。 |
on_rdt_state
void(* on_rdt_state)(connection_id_t conn_id, uint32_t uid, rdt_state_e state)RDT 通道的连接状态已改变回调。
自从
v1.9.2
当 RDT 通道的连接状态发生变化时，SDK 会触发该回调并报告当前的连接状态。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 远端用户的用户 ID。 |
state | 连接状态。详见 rdt_state 。 |
on_reconnecting
void(* on_reconnecting)(connection_id_t conn_id)正在重新连接回调。
SDK 会在如下场景中触发该回调：
- SDK 与服务器断开连接超过 4 秒。
- 网络断开。
- 用户切换网络类型，例如 4G 网络切换成 Wi-Fi 网络。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
on_rejoin_channel_success
void(* on_rejoin_channel_success)(connection_id_t conn_id, uint32_t uid, int elapsed_ms)重新加入频道成功回调。
有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 本地用户 ID。 |
elapsed_ms | 从开始重连到重连成功的时间（毫秒）。 |
on_remote_user_registered
void(* on_remote_user_registered)(const char *uname, uint32_t uid)远端用户注册回调。
| 参数名 | 描述 |
|---|---|
uname | 使用 agora_rtc_init 方法初始化时设置的 String 型用户名，该参数为必填，最大不超过 255 字节，不可设为 NULL。请确保用户名的唯一性。以下为支持的字符集范围（共 89 个字符）：
|
uid | 使用 agora_rtc_init 方法初始化时设置的用户 ID（32 位整型）。建议设置范围：1 到 (2³² - 1)，并保证唯一性。 0 是无效的 uid。如果将 uid 设为 0，系统将自动分配一个 UID。 |
on_stream_message
void(* on_stream_message)(connection_id_t conn_id, uint32_t uid, int stream_id, const char *data, size_t length, uint64_t sent_ts)接收到远端用户数据流消息的回调。
该回调表示本地用户收到了远端用户调用 agora_rtc_send_stream_message 方法发送的流消息。
自从
v1.9.5
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 发送消息的用户 ID。 |
stream_id | 接收到的消息的 Stream ID。 |
data | 接收到的数据。 |
length | 数据流大小。 |
sent_ts | 数据流发送的时间戳。 |
on_target_bitrate_changed
void(* on_target_bitrate_changed)(connection_id_t conn_id, uint32_t target_bps)编码器码率更新通知回调。你可以使用此回调提醒 App 更新编码器码率。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
target_bps | 码率需要更新到的目标值，单位为 bps。 |
on_token_privilege_will_expire
void(* on_token_privilege_will_expire)(connection_id_t conn_id, const char *token)Token 服务即将过期回调。
在调用 agora_rtc_join_channel 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒应用程序更新 Token。当收到该回调时，用户需要重新在服务端生成新的 Token，然后调用 agora_rtc_renew_token 将新生成的 Token 传给 SDK。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
token | 即将服务失效的 Token。 |
on_user_info_updated
void(* on_user_info_updated)(connection_id_t conn_id, const user_info_t *user)远端用户信息更新回调。
自从
v1.9.5
远端用户加入频道后，SDK 会获取到该远端用户的用户 ID 和 User account，然后缓存一个包含了远端用户 ID 和 User account 的映射表，并在本地触发该回调。
注解
收到该回调后，请确保根据新的映射关系更新相关的订阅逻辑。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
user | 远端用户的信息，详见 user_info_t 。 |
on_user_joined
void(* on_user_joined)(connection_id_t conn_id, uint32_t uid, int elapsed_ms)远端用户加入频道回调。
该回调提示有远端用户加入了频道。如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
该回调在如下情况下会被触发：
- 远端用户加入频道。
- 远端用户网络中断后重新加入频道。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 用户 ID。 |
elapsed_ms | 从频道成功创建开始到发生此回调过去的时间（毫秒）。 |
on_user_joined_with_user_account
void(* on_user_joined_with_user_account)(connection_id_t conn_id, const user_info_t *user, int elapsed_ms)远端用户使用 User Account 加入频道回调。
自从
v1.9.5
远端用户调用 agora_rtc_join_channel_with_user_account 方法成功加入频道后，会在本地触发该回调。
注解
调用该方法前，请确保 rtc_service_option_t 中的 use_string_uid 设为 true。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
user | 加入频道的远端用户的信息，详见 user_info_t 。 |
elapsed_ms | 从频道成功创建开始到发生此回调过去的时间（毫秒）。 |
on_user_mute_audio
void(* on_user_mute_audio)(connection_id_t conn_id, uint32_t uid, bool muted)频道内远端用户暂停/恢复发送音频流回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 远端用户的用户 ID。 |
muted | 远端用户是否发送音频流：
|
on_user_mute_video
void(* on_user_mute_video)(connection_id_t conn_id, uint32_t uid, bool muted)频道内远端用户暂停/恢复发送视频流回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 远端用户的用户 ID。 |
muted | 远端用户是否发送视频流：
|
on_user_offline
void(* on_user_offline)(connection_id_t conn_id, uint32_t uid, int reason)远端用户离开频道回调。
SDK 会在如下场景触发该回调：
- 正常离开：远端用户会发送类似“再见”的消息。接收此消息后，判断用户离开频道。
- 超时掉线：如果本地用户在 20 秒内没有收到远端用户的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。建议使用云信令 SDK 来做可靠的掉线检测。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 离开频道的用户 ID。 |
reason | 用户离开频道原因，详见 user_offline_reason_e 。 |
on_user_offline_with_user_account
void(* on_user_offline_with_user_account)(connection_id_t conn_id, const user_info_t *user, int reason)使用 User Account 场景下，远端用户离开频道回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
user | 离开频道的远端用户的信息，详见 user_info_t 。 |
reason | 用户离开频道原因，详见 user_offline_reason_e 。 |
on_video_data
void(* on_video_data)(connection_id_t conn_id, uint32_t uid, uint16_t sent_ts, const void *data_ptr, size_t data_len, const video_frame_info_t *info_ptr)收到频道内远端用户的视频帧回调。
| 参数名 | 描述 |
|---|---|
conn_id | Connection ID，详见 connection_id_t 。 |
uid | 发送视频帧的远端用户的用户 ID。 |
sent_ts | Unix 时间戳（ms）。标识远端用户调用 agora_rtc_send_video_data 的时间。 |
data_ptr | 视频包数据。 |
data_len | 视频包数据长度（字节）。 |
info_ptr | 视频帧信息。详见 video_frame_info_t 。 |
该结构体的文档由以下文件生成:
- agora_rtc_api.h