agora_rtc_api.h 文件参考

宏定义说明Copy Anchor Link

agora_apiCopy Anchor Link

#define agora_api

AGORA_CERTIFICATE_MAX_LENCopy Anchor Link

#define AGORA_CERTIFICATE_MAX_LEN(1024)

AGORA_CREDENTIAL_MAX_LENCopy Anchor Link

#define AGORA_CREDENTIAL_MAX_LEN(256)

AGORA_LICENSE_VALUE_LENCopy Anchor Link

#define AGORA_LICENSE_VALUE_LEN(32)

AGORA_RTC_CHANNEL_NAME_MAX_LENCopy Anchor Link

#define AGORA_RTC_CHANNEL_NAME_MAX_LEN(64)

AGORA_RTC_DATA_STREAM_MAX_LENCopy Anchor Link

#define AGORA_RTC_DATA_STREAM_MAX_LEN(1024)

AGORA_RTC_PRODUCT_ID_MAX_LENCopy Anchor Link

#define AGORA_RTC_PRODUCT_ID_MAX_LEN(63)

AGORA_RTC_USER_ACCOUNT_MAX_LENCopy Anchor Link

#define AGORA_RTC_USER_ACCOUNT_MAX_LEN(256)

AGORA_RTM_DATA_MAX_LENCopy Anchor Link

#define AGORA_RTM_DATA_MAX_LEN(31 * 1024)

AGORA_RTM_UID_MAX_LENCopy Anchor Link

#define AGORA_RTM_UID_MAX_LEN(64)

CONNECTION_ID_ALLCopy Anchor Link

#define CONNECTION_ID_ALL((connection_id_t)0)

当前创建的全部 Connection。

CONNECTION_ID_INVALIDCopy Anchor Link

#define CONNECTION_ID_INVALID((connection_id_t)-1)

无效的 Connection ID。

类型定义说明Copy Anchor Link

connection_id_tCopy Anchor Link

typedef uint32_t connection_id_t

Connection ID。

rdt_state_eCopy Anchor Link

typedef enum rdt_state rdt_state_e

RDT 通道的连接状态。

rdt_status_info_tCopy Anchor Link

typedef struct rdt_status_info rdt_status_info_t

RDT 通道的信息。

rdt_stream_type_eCopy Anchor Link

typedef enum rdt_stream_type rdt_stream_type_e

RDT 消息类型。

user_info_tCopy Anchor Link

typedef struct user_info_s user_info_t

用户信息。适用于使用 String 型用户 ID 的场景。

video_frame_rate_eCopy Anchor Link

typedef uint16_t video_frame_rate_e

（废弃）视频帧率。

agora_err_code_eCopy Anchor Link

enum agora_err_code_e

错误码。

area_code_eCopy Anchor Link

enum area_code_e

访问区域。

audio_codec_type_eCopy Anchor Link

enum audio_codec_type_e

SDK 内置的音频编解码器。

audio_data_type_eCopy Anchor Link

enum audio_data_type_e

音频编码格式。

crypto_mode_eCopy Anchor Link

enum crypto_mode_e

加密模式。

建议使用 AES_128_GCM2 或 AES_256_GCM2 加密模式。这两种模式支持使用盐，安全性更高。

license_err_reason_eCopy Anchor Link

enum license_err_reason_e

设备 License 验证失败的错误码。

rdt_stateCopy Anchor Link

enum rdt_state

RDT 通道的连接状态。

rdt_stream_typeCopy Anchor Link

enum rdt_stream_type

RDT 消息类型。

rtc_log_level_eCopy Anchor Link

enum rtc_log_level_e

日志输出级别。

rtm_err_code_eCopy Anchor Link

enum rtm_err_code_e

RTM 错误码。

rtm_event_type_eCopy Anchor Link

enum rtm_event_type_e

RTM RTM 事件类型。

rtm_message_type_eCopy Anchor Link

enum rtm_message_type_e

RTM 消息类型。

rtm_msg_state_eCopy Anchor Link

enum rtm_msg_state_e

RTM 消息的发送状态。

user_offline_reason_eCopy Anchor Link

enum user_offline_reason_e

远端用户下线的原因。

video_data_type_eCopy Anchor Link

enum video_data_type_e

视频编码格式。

video_frame_type_eCopy Anchor Link

enum video_frame_type_e

视频帧类型。

video_orientation_eCopy Anchor Link

enum video_orientation_e

已编码视频帧的旋转角度。

video_stream_type_eCopy Anchor Link

enum video_stream_type_e

视频流类型。

函数说明Copy Anchor Link

agora_rtc_config_log()Copy Anchor Link

agora_api int agora_rtc_config_log(int size_per_file, int max_file_count)

配置 SDK 的日志文件。

返回值

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

agora_rtc_create_connection()Copy Anchor Link

agora_api int agora_rtc_create_connection(connection_id_t * conn_id)

创建 Connection。

你需要在加入频道前调用该方法创建 Connection。如需使用同一个用户 ID 加入不同频道，或者使用不同用户 ID 加入同一个频道，则你需要多次调用该方法创建多个 Connection，然后再使用对应的 Connection ID 加入频道。

返回值

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

agora_rtc_create_data_stream()Copy Anchor Link

agora_api int agora_rtc_create_data_stream(connection_id_t conn_id, int * stream_id, bool reliable, bool ordered)

创建数据流。

在 Connection 生命周期内，每个用户最多可以创建五条数据流。

返回值

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

agora_rtc_destroy_connection()Copy Anchor Link

agora_api int agora_rtc_destroy_connection(connection_id_t conn_id)

销毁 Connection。

返回值

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

agora_rtc_err_2_str()Copy Anchor Link

agora_api const char * agora_rtc_err_2_str(int err)

将错误码转为静态字符串，以便查看错误描述。

返回值

静态字符串。

agora_rtc_fini()Copy Anchor Link

agora_api int agora_rtc_fini(void)

释放所有由 agora_rtc_init 方法分配给 RTSA 服务的资源。

返回值

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

agora_rtc_get_connection_info()Copy Anchor Link

agora_api int agora_rtc_get_connection_info(connection_id_t conn_id, connection_info_t * conn_info)

获取 Connection 信息。

返回值

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

agora_rtc_get_rdt_status_info()Copy Anchor Link

agora_api int agora_rtc_get_rdt_status_info(connection_id_t conn_id, uint32_t remote_uid, rdt_status_info_t * info)

获取 RDT 通道的信息。

该方法可以获取当前 RDT 通道的连接状态和缓冲区长度，从而判断远端用户是否成功接收 RDT 消息、本地用户是否可以继续发送 RDT 消息。例如，发送缓冲区长度 (send_queue_size) 为 0 表示远端用户已接收完 RDT 消息。

返回值

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

agora_rtc_get_user_info_by_uid()Copy Anchor Link

agora_api int agora_rtc_get_user_info_by_uid(connection_id_t conn_id, uint32_t uid, user_info_t * user)

通过用户 ID 获取用户信息。

返回值

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

agora_rtc_get_user_info_by_user_account()Copy Anchor Link

agora_api int agora_rtc_get_user_info_by_user_account(connection_id_t conn_id, const char * user_account, user_info_t * user)

通过用户 User account 获取用户信息。

返回值

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

agora_rtc_get_version()Copy Anchor Link

const char * agora_rtc_get_version(void)

获取 SDK 版本。

返回值

包含 SDK 版本信息的静态字符串。

agora_rtc_init()Copy Anchor Link

agora_api int agora_rtc_init(const char * app_id, const agora_rtc_event_handler_t * event_handler, rtc_service_option_t * option)

初始化 RTSA 服务。

返回值

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

agora_rtc_join_channel()Copy Anchor Link

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 的用户可以互相传输数据。

返回值

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

agora_rtc_join_channel_with_user_account()Copy Anchor Link

agora_api int agora_rtc_join_channel_with_user_account(connection_id_t conn_id, const char * channel_name, const char * user_account, const char * token, rtc_channel_options_t * options)

使用用户 User account 加入指定 Connection 所关联的 RTC 频道。

该方法让本地用户加入指定频道。同一个频道内使用相同 App ID 的用户可以互相传输数据。

返回值

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

agora_rtc_leave_channel()Copy Anchor Link

agora_api int agora_rtc_leave_channel(connection_id_t conn_id)

离开指定 Connection 所关联的 RTC 频道。

停止在某频道传输数据后需要离开该频道。

返回值

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

agora_rtc_license_gen_credential()Copy Anchor Link

agora_api int agora_rtc_license_gen_credential(char * credential, unsigned int * credential_len)

生成设备唯一标识 Credential。

返回值

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

agora_rtc_license_strerror()Copy Anchor Link

agora_api const char * agora_rtc_license_strerror(int err)

获取 Licence 错误描述。

返回值

表示错误描述的字符串。

agora_rtc_license_verify()Copy Anchor Link

agora_api int agora_rtc_license_verify(const char * certificate, int certificate_len, const char * credential, int credential_len)

认证 SDK。

启用了声网 License 机制后，安装了 SDK 的设备只有通过 Certificate 验证 才能加入声网频道、使用数据传输功能。

返回值

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

agora_rtm_login()Copy Anchor Link

agora_api int agora_rtm_login(const char * rtm_uid, const char * rtm_token, const agora_rtm_handler_t * handler)

登录 RTM。

返回值

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

agora_rtm_logout()Copy Anchor Link

agora_api int agora_rtm_logout(void)

登出 RTM。

返回值

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

agora_rtc_mute_local_audio()Copy Anchor Link

agora_api int agora_rtc_mute_local_audio(connection_id_t conn_id, bool mute)

对指定 Connection 所关联的 RTC 频道暂停/恢复发送本地音频流。

返回值

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

agora_rtc_mute_local_video()Copy Anchor Link

agora_api int agora_rtc_mute_local_video(connection_id_t conn_id, bool mute)

指定 Connection 所关联的 RTC 频道暂停/恢复发送本地视频流。

返回值

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

agora_rtc_mute_remote_audio()Copy Anchor Link

agora_api int agora_rtc_mute_remote_audio(connection_id_t conn_id, uint32_t remote_uid, bool mute)

暂停/恢复接收指定 Connection 所关联的 RTC 频道内的指定远端用户的音频流。

返回值

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

agora_rtc_mute_remote_video()Copy Anchor Link

agora_api int agora_rtc_mute_remote_video(connection_id_t conn_id, uint32_t remote_uid, bool mute)

暂停/恢复接收指定 Connection 所关联的 RTC 频道内的指定远端用户的视频流。

可以先暂停接收所有频道的视频流，然后恢复接收指定频道的视频流。

返回值

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

agora_rtc_renew_token()Copy Anchor Link

agora_api int agora_rtc_renew_token(connection_id_t conn_id, const char * token)

更新指定 Connection 所关联的 RTC 频道的 RTC Token。

返回值

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

agora_rtc_request_video_key_frame()Copy Anchor Link

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 频道内的指定远端用户为指定远端视频流生成关键帧。

返回值

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

agora_rtc_send_audio_data()Copy Anchor Link

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 频道发送音频帧。

返回值

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

agora_rtc_send_media_ctrl_msg()Copy Anchor Link

agora_api int agora_rtc_send_media_ctrl_msg(connection_id_t conn_id, uint32_t remote_uid, const void * payload, size_t length)

向所有频道或指定频道发送消息。

成功调用该方法后，远端会触发 on_media_ctrl_msg 回调，远端用户可以在该回调中获取接收到的消息。

返回值

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

agora_rtc_send_rdt_msg()Copy Anchor Link

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，可靠数据传输）消息。

在文件传输、文件下载等需要可靠传输的场景中，你可以参考如下步骤发送 RDT 消息：

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

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

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

返回值

• 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_rtm_send_data()Copy Anchor Link

agora_api int agora_rtm_send_data(const char * rtm_uid, const void * msg, size_t msg_len, uint32_t msg_id, rtm_message_type_e msg_type, const char * custom_type)

通过 RTM 服务发送消息。

RTM 默认开启基于 TLS 加密的传输层安全保护且不可关闭。

返回值

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

agora_rtc_send_stream_message()Copy Anchor Link

agora_api int agora_rtc_send_stream_message(connection_id_t conn_id, int stream_id, const char * data, size_t length)

向频道内的所有用户发送数据流。

调用 agora_rtc_create_data_stream 后，你可以调用该方法向频道内所有用户发送数据流消息。

成功调用该方法后，远端会触发 on_stream_message 回调，远端用户可以在该回调中获取接收到的流消息。

返回值

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

agora_rtc_send_video_data()Copy Anchor Link

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 频道发送视频帧。

返回值

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

agora_rtc_set_bwe_param()Copy Anchor Link

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) 参数。

返回值

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

agora_rtc_set_log_level()Copy Anchor Link

agora_api int agora_rtc_set_log_level(rtc_log_level_e level)

设置 SDK 的日志输出等级。

设置一个级别后，你可以看到该级别及之前所有级别的日志信息。

返回值

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

agora_rtc_set_params()Copy Anchor Link

agora_api int agora_rtc_set_params(connection_id_t conn_id, const char * params)

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

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

返回值

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

agora_rtm_publish()Copy Anchor Link

agora_api int agora_rtm_publish(const char * channel_name, const void * message, size_t length, uint32_t msg_id, rtm_message_type_e msg_type, const char * custom_type)

向 RTM 频道发布消息。

无需订阅该频道即可发布消息。最终发送结果通过 agora_rtm_handler_t::on_rtm_publish_result 回调报告。

返回值

• 0: 已接受发布请求。
• < 0: 方法调用失败。

agora_rtm_subscribe()Copy Anchor Link

agora_api int agora_rtm_subscribe(const char * channel_name)

异步订阅 RTM 频道。

订阅结果通过 agora_rtm_handler_t::on_rtm_subscribe_result 回调报告。

返回值

• 0: 已接受订阅请求。
• < 0: 方法调用失败。

agora_rtm_unsubscribe()Copy Anchor Link

agora_api int agora_rtm_unsubscribe(const char * channel_name)

同步取消订阅 RTM 频道。

返回值

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