agora_rtc_event_handler_t结构体 参考
包含事件处理回调的结构体。
结构体成员变量说明
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 [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 远端用户的用户 ID。 |
sent_ts [in] | Unix 时间戳(ms)。标识远端用户调用 agora_rtc_send_audio_data 的时间。 |
data_ptr [in] | 音频包数据。 |
data_len [in] | 音频包数据长度(字节)。 |
info_ptr [in] | 音频帧信息。详见 audio_frame_info_t 。 |
on_connection_lost
void(* on_connection_lost) (connection_id_t conn_id) |
当 SDK 与服务器断开连接超过 10 秒时,SDK 会触发该回调。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
on_error
void(* on_error) (connection_id_t conn_id, int code, const char *msg) |
该回调方法表示 SDK 运行时出现了(网络或媒体相关的)错误。 通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
code [in] | 错误码,详见 agora_err_code_e 。 |
msg [in] | 错误描述。 |
on_join_channel_success
void(* on_join_channel_success) (connection_id_t conn_id, uint32_t uid, int elapsed_ms) |
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 本地用户 ID。 |
elapsed_ms [in] | 从频道成功创建开始到发生此回调过去的时间(毫秒)。 |
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) |
收到此回调后,发送端需生成一个新的关键帧。
参数
参数名 | 描述 |
---|---|
channel [in] | 频道名。 |
uid [in] | 远端用户的用户 ID。 |
stream_type [in] | 需要生成关键帧的视频流类型。 |
on_license_validation_failure
void(* on_license_validation_failure) (connection_id_t conn_id, int error) |
加入频道时,声网服务器会验证你在 agora_rtc_init 中传入的 License。如果 License 验证失败,则 SDK 会触发该回调,你可以根据收到的错误码处理问题。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
error [in] | 错误码。详见 license_err_reason_e 。 |
on_local_user_registered
void(* on_local_user_registered) (const char *uname, uint32_t uid) |
参数
参数名 | 描述 |
---|---|
uname [in] | 使用 agora_rtc_init 方法初始化时设置的 String 型用户名,该参数为必填,最大不超过 255 字节,不可设为 NULL。请确保用户名的唯一性。以下为支持的字符集范围(共 89 个字符):
|
uid [in] | 使用 agora_rtc_init 方法初始化时设置的用户 ID(32 位整型)。建议设置范围:1 到 (232-1),并保证唯一性。 0 是无效的 uid 。如果将 uid 设为 0,系统将自动分配一个 UID。 |
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) |
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
data_ptr [in] | 音频包数据。 |
data_len [in] | 音频包数据长度(字节)。 |
info_ptr [in] | 音频帧信息。详见 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) |
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。 |
uid [in] | 远端用户的用户 ID。 |
type [in] | RDT 消息类型。详见 rdt_stream_type 。 |
msg [in] | RDT 消息负载。 |
len [in] | RDT 消息长度。 |
on_rdt_state
void(* on_rdt_state) (connection_id_t conn_id, uint32_t uid, rdt_state_e state) |
当 RDT 通道的连接状态发生变化时,SDK 会触发该回调并报告当前的连接状态。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。 |
uid [in] | 远端用户的用户 ID。 |
state [in] | 连接状态。详见 rdt_state 。 |
on_reconnecting
void(* on_reconnecting) (connection_id_t conn_id) |
SDK 会在如下场景中触发该回调:
- SDK 与服务器断开连接超过 4 秒。
- 网络断开。
- 用户切换网络类型,例如 4G 网络切换成 Wi-Fi 网络。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
on_rejoin_channel_success
void(* on_rejoin_channel_success) (connection_id_t conn_id, uint32_t uid, int elapsed_ms) |
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 本地用户 ID。 |
elapsed_ms [in] | 从开始重连到重连成功的时间(毫秒)。 |
on_remote_user_registered
void(* on_remote_user_registered) (const char *uname, uint32_t uid) |
参数
参数名 | 描述 |
---|---|
uname [in] | 使用 agora_rtc_init 方法初始化时设置的 String 型用户名,该参数为必填,最大不超过 255 字节,不可设为 NULL。请确保用户名的唯一性。以下为支持的字符集范围(共 89 个字符):
|
uid [in] | 使用 agora_rtc_init 方法初始化时设置的用户 ID(32 位整型)。建议设置范围:1 到 (232-1),并保证唯一性。 0 是无效的 uid 。如果将 uid 设为 0,系统将自动分配一个 UID。 |
on_target_bitrate_changed
void(* on_target_bitrate_changed) (connection_id_t conn_id, uint32_t target_bps) |
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。 |
target_bps [in] | 码率需要更新到的目标值,单位为 bps。 |
on_token_privilege_will_expire
void(* on_token_privilege_will_expire) (connection_id_t conn_id, const char *token) |
在调用 agora_rtc_join_channel 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒应用程序更新 Token。当收到该回调时,用户需要重新在服务端生成新的 Token,然后调用 agora_rtc_renew_token 将新生成的 Token 传给 SDK。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。 |
token [in] | 即将服务失效的 Token。 |
on_user_joined
void(* on_user_joined) (connection_id_t conn_id, uint32_t uid, int elapsed_ms) |
该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
该回调在如下情况下会被触发:
- 远端用户加入频道。
- 远端用户网络中断后重新加入频道。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 用户 ID。 |
elapsed_ms [in] | 从频道成功创建开始到发生此回调过去的时间(毫秒)。 |
on_user_mute_audio
void(* on_user_mute_audio) (connection_id_t conn_id, uint32_t uid, bool muted) |
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 远端用户的用户 ID。 |
muted [in] | 远端用户是否发送音频流:
|
on_user_mute_video
void(* on_user_mute_video) (connection_id_t conn_id, uint32_t uid, bool muted) |
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 远端用户的用户 ID。 |
muted [in] | 远端用户是否发送视频流:
|
on_user_offline
void(* on_user_offline) (connection_id_t conn_id, uint32_t uid, int reason) |
SDK 会在如下场景触发该回调:
- 正常离开:远端用户会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:如果本地用户在 20 秒内没有收到远端用户的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。建议使用云信令 SDK 来做可靠的掉线检测。
参数
参数名 | 描述 |
---|---|
conn_id [in] | Connection ID。你可以通过 agora_rtc_create_connection 创建 Connection。 |
uid [in] | 离开频道的用户 ID。 |
reason [in] | 用户离开频道原因,详见 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 [in] | Connection ID。 |
uid [in] | 发送视频帧的远端用户的用户 ID。 |
sent_ts [in] | Unix 时间戳(ms)。标识远端用户调用 agora_rtc_send_video_data 的时间。 |
data_ptr [in] | 视频包数据。 |
data_len [in] | 视频包数据长度(字节)。 |
info_ptr [in] | 视频帧信息。详见 video_frame_info_t 。 |