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