agora_rtc_api.h

Go to the documentation of this file.

/*************************************************************
 *
 * This is a part of the Agora RTC Service SDK.
 * Copyright (C) 2020 Agora IO
 * All rights reserved.
 *
 *************************************************************/
 
#ifndef __AGORA_RTC_API_H__
#define __AGORA_RTC_API_H__
 
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#if defined(_MSC_VER)
#if defined(__BUILDING_AGORA_SDK__)
#define __agora_api__ __declspec(dllexport)
#else
#define __agora_api__ __declspec(dllimport)
#endif
#else
#define __agora_api__
#endif
 
#define AGORA_RTC_CHANNEL_NAME_MAX_LEN (64)
#define AGORA_RTC_USER_ID_MAX_LEN (255)
#define AGORA_RTC_PRODUCT_ID_MAX_LEN (63)
#define AGORA_RTM_UID_MAX_LEN 64
#define AGORA_RTM_DATA_MAX_LEN (32 * 1024)
#define AGORA_CREDENTIAL_MAX_LEN 256
#define AGORA_CERTIFICATE_MAX_LEN 1024
#define AGORA_LICENSE_VALUE_LEN 32
 
  typedef enum
  {
    ERR_OKAY = 0,
 
    ERR_FAILED = 1,
 
    ERR_NET_DOWN = 14,
 
    ERR_JOIN_CHANNEL_REJECTED = 17,
 
    ERR_INVALID_APP_ID = 101,
 
    ERR_INVALID_CHANNEL_NAME = 102,
 
    ERR_NO_SERVER_RESOURCES = 103,
 
    ERR_LOOKUP_CHANNEL_REJECTED = 105,
 
    ERR_OPEN_CHANNEL_REJECTED = 107,
 
    ERR_TOKEN_EXPIRED = 109,
 
    ERR_INVALID_TOKEN = 110,
 
    ERR_DYNAMIC_TOKEN_BUT_USE_STATIC_KEY = 115,
 
    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,
 
    ERR_SEND_VIDEO_OVER_BANDWIDTH_LIMIT = 200,
 
    ERR_AUDIO_DECODER_NOT_MATCH_AUDIO_FRAME = 201,
 
    ERR_NO_AUDIO_DECODER_TO_HANDLE_AUDIO_FRAME = 202,
  } agora_err_code_e;
 
  typedef enum
  {
    USER_OFFLINE_QUIT = 0,
    USER_OFFLINE_DROPPED = 1,
  } user_offline_reason_e;
 
  typedef enum
  {
    VIDEO_DATA_TYPE_YUV420 = 0,
    VIDEO_DATA_TYPE_H264 = 2,
    VIDEO_DATA_TYPE_H265 = 3,
    VIDEO_DATA_TYPE_GENERIC = 6,
    VIDEO_DATA_TYPE_GENERIC_JPEG = 20,
  } video_data_type_e;
 
  typedef enum
  {
    VIDEO_FRAME_AUTO_DETECT = 0,
    VIDEO_FRAME_KEY = 3,
    VIDEO_FRAME_DELTA = 4,
  } video_frame_type_e;
 
  typedef enum
  {
    VIDEO_FRAME_RATE_FPS_1 = 1,
    VIDEO_FRAME_RATE_FPS_7 = 7,
    VIDEO_FRAME_RATE_FPS_10 = 10,
    VIDEO_FRAME_RATE_FPS_15 = 15,
    VIDEO_FRAME_RATE_FPS_24 = 24,
    VIDEO_FRAME_RATE_FPS_30 = 30,
    VIDEO_FRAME_RATE_FPS_60 = 60,
  } video_frame_rate_e;
 
  typedef enum
  {
    VIDEO_STREAM_HIGH = 0,
    VIDEO_STREAM_LOW = 1,
  } video_stream_type_e;
 
  typedef struct
  {
    video_data_type_e data_type;
    video_stream_type_e stream_type;
    video_frame_type_e frame_type;
    video_frame_rate_e frame_rate;
  } video_frame_info_t;
 
  typedef enum
  {
    AUDIO_CODEC_DISABLED = 0,
    AUDIO_CODEC_TYPE_OPUS = 1,
    AUDIO_CODEC_TYPE_G722 = 2,
    AUDIO_CODEC_TYPE_G711A = 3,
    AUDIO_CODEC_TYPE_G711U = 4,
  } audio_codec_type_e;
 
  typedef enum
  {
    AUDIO_DATA_TYPE_OPUS = 1,
    AUDIO_DATA_TYPE_OPUSFB = 2,
    AUDIO_DATA_TYPE_PCMA = 3,
    AUDIO_DATA_TYPE_PCMU = 4,
    AUDIO_DATA_TYPE_G722 = 5,
    AUDIO_DATA_TYPE_AACLC = 8,
    AUDIO_DATA_TYPE_HEAAC = 9,
    AUDIO_DATA_TYPE_PCM = 100,
    AUDIO_DATA_TYPE_GENERIC = 253,
  } audio_data_type_e;
 
  typedef struct
  {
    audio_data_type_e data_type;
  } audio_frame_info_t;
 
  typedef enum
  {
    RTC_LOG_DEFAULT = 0, // the same as RTC_LOG_NOTICE
    RTC_LOG_EMERG,
    RTC_LOG_ALERT, // action must be taken immediately
    RTC_LOG_CRIT, // critical conditions
    RTC_LOG_ERROR, // error conditions
    RTC_LOG_WARNING, // warning conditions
    RTC_LOG_NOTICE, // normal but significant condition, default level
    RTC_LOG_INFO, // informational
    RTC_LOG_DEBUG, // debug-level messages
  } rtc_log_level_e;
 
  typedef enum
  {
    AREA_CODE_DEFAULT = 0x00000000,
    AREA_CODE_CN = 0x00000001,
    AREA_CODE_NA = 0x00000002,
    AREA_CODE_EU = 0x00000004,
    AREA_CODE_AS = 0x00000008,
    AREA_CODE_JP = 0x00000010,
    AREA_CODE_IN = 0x00000020,
    AREA_CODE_OC = 0x00000040,
    AREA_CODE_SA = 0x00000080,
    AREA_CODE_AF = 0x00000100,
    AREA_CODE_KR = 0x00000200,
    AREA_CODE_OVS = 0xFFFFFFFE,
    AREA_CODE_GLOB = (0xFFFFFFFF),
  } area_code_e;
 
  typedef struct
  {
    bool log_disable;
    bool log_disable_desensitize;
    rtc_log_level_e log_level;
    const char *log_path;
  } log_config_t;
 
  typedef struct
  {
    uint32_t area_code;
    char product_id[AGORA_RTC_PRODUCT_ID_MAX_LEN + 1];
    log_config_t log_cfg;
    char license_value[AGORA_LICENSE_VALUE_LEN + 1];
  } rtc_service_option_t;
 
  typedef struct
  {
    audio_codec_type_e audio_codec_type;
    int pcm_sample_rate;
    int pcm_channel_num;
  } audio_codec_option_t;
 
  typedef struct
  {
    bool auto_subscribe_audio;
    bool auto_subscribe_video;
    bool subscribe_local_user;
    bool enable_audio_jitter_buffer;
    bool enable_audio_mixer;
    audio_codec_option_t audio_codec_opt;
    bool enable_aut_encryption;
  } rtc_channel_options_t;
 
  typedef enum
  {
    CLOUD_PROXY_NONE = 0,
    CLOUD_PROXY_UDP = 1,
    CLOUD_PROXY_TCP = 3,
    CLOUD_PROXY_AUTO = 100,
  } cloud_proxy_type_e;
 
  typedef enum
  {
    NETWORK_EVENT_DOWN = 0,
    NETWORK_EVENT_UP,
    NETWORK_EVENT_CHANGE,
  } network_event_type_e;
 
  typedef uint32_t connection_id_t;
 
#define CONNECTION_ID_ALL ((connection_id_t)0)
#define CONNECTION_ID_INVALID ((connection_id_t)-1)
 
  typedef struct
  {
    // Connection ID.
    connection_id_t conn_id;
    // User ID.
    uint32_t uid;
    // RTC channel name.
    char channel_name[AGORA_RTC_CHANNEL_NAME_MAX_LEN + 1];
  } connection_info_t;
 
  typedef struct
  {
    void (*on_join_channel_success)(connection_id_t conn_id, uint32_t uid, int elapsed_ms);
 
    void (*on_connection_lost)(connection_id_t conn_id);
 
    void (*on_rejoin_channel_success)(connection_id_t conn_id, uint32_t uid, int elapsed_ms);
 
    void (*on_error)(connection_id_t conn_id, int code, const char *msg);
 
    void (*on_user_joined)(connection_id_t conn_id, uint32_t uid, int elapsed_ms);
 
    void (*on_user_offline)(connection_id_t conn_id, uint32_t uid, int reason);
 
    void (*on_user_mute_audio)(connection_id_t conn_id, uint32_t uid, bool muted);
 
#ifndef CONFIG_AUDIO_ONLY
    void (*on_user_mute_video)(connection_id_t conn_id, uint32_t uid, bool muted);
 
#endif
    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);
 
    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);
 
#ifndef CONFIG_AUDIO_ONLY
    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);
 
    void (*on_target_bitrate_changed)(connection_id_t conn_id, uint32_t target_bps);
 
    void (*on_key_frame_gen_req)(connection_id_t conn_id, uint32_t uid, video_stream_type_e stream_type);
 
#endif
 
#ifdef CONFIG_RTC_STRING_UID
    void (*on_local_user_registered)(const char *uname, uint32_t uid);
 
    void (*on_remote_user_registered)(const char *uname, uint32_t uid);
#endif // End of CONFIG_RTC_STRING_UID
 
    void (*on_token_privilege_will_expire)(connection_id_t conn_id, const char *token);
 
#ifdef CONFIG_RTCM
    void (*on_media_ctrl_receive)(connection_id_t conn_id, uint32_t uid, const void *payload, size_t length);
#endif
  } agora_rtc_event_handler_t;
 
  extern const char *agora_rtc_get_version(void);
 
  extern __agora_api__ const char *agora_rtc_err_2_str(int err);
 
#ifdef CONFIG_LICENSE
 
  extern __agora_api__ int agora_rtc_license_gen_credential(char *credential, unsigned int *credential_len);
 
  extern __agora_api__ int agora_rtc_license_verify(const char *certificate, int certificate_len, const char *credential,
                                                    int credential_len);
 
#endif // End CONFIG_LICENSE
  extern __agora_api__ int agora_rtc_init(const char *app_id, const agora_rtc_event_handler_t *event_handler,
                                          rtc_service_option_t *option);
  extern __agora_api__ int agora_rtc_fini(void);
 
  extern __agora_api__ int agora_rtc_set_log_level(rtc_log_level_e level);
 
  extern __agora_api__ int agora_rtc_config_log(int size_per_file, int max_file_count);
 
  extern __agora_api__ int agora_rtc_create_connection(connection_id_t *conn_id);
 
  extern __agora_api__ int agora_rtc_destroy_connection(connection_id_t conn_id);
 
  extern __agora_api__ int agora_rtc_get_connection_info(connection_id_t conn_id, connection_info_t *conn_info);
 
  extern __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);
 
  extern __agora_api__ int agora_rtc_leave_channel(connection_id_t conn_id);
 
  extern __agora_api__ int agora_rtc_renew_token(connection_id_t conn_id, const char *token);
 
  extern __agora_api__ int agora_rtc_notify_network_event(network_event_type_e event);
 
  extern __agora_api__ int agora_rtc_mute_local_audio(connection_id_t conn_id, bool mute);
 
#ifndef CONFIG_AUDIO_ONLY
  extern __agora_api__ int agora_rtc_mute_local_video(connection_id_t conn_id, bool mute);
#endif
  extern __agora_api__ int agora_rtc_mute_remote_audio(connection_id_t conn_id, uint32_t remote_uid, bool mute);
 
#ifndef CONFIG_AUDIO_ONLY
  extern __agora_api__ int agora_rtc_mute_remote_video(connection_id_t conn_id, uint32_t remote_uid, bool mute);
 
  extern __agora_api__ int agora_rtc_request_video_key_frame(connection_id_t conn_id, uint32_t remote_uid,
                                                             video_stream_type_e stream_type);
#endif
  extern __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);
 
#ifndef CONFIG_AUDIO_ONLY
  extern __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);
  extern __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);
 
#endif // End CONFIG_AUDIO_ONLY
 
#ifdef CONFIG_RTC_PROXY
  extern __agora_api__ int agora_rtc_set_cloud_proxy(cloud_proxy_type_e type);
#endif // End CONFIG_RTC_PROXY
 
  extern __agora_api__ int agora_rtc_set_params(const char *params);
 
#ifdef CONFIG_RTCM
  extern __agora_api__ int agora_rtc_send_media_ctrl_msg(connection_id_t conn_id, uint32_t remote_uid,
                                                         const void *payload, size_t length);
#endif // End of CONFIG_RTCM
 
#ifdef CONFIG_RTM
  typedef enum
  {
    RTM_EVENT_TYPE_LOGIN = 0,
    RTM_EVENT_TYPE_KICKOFF = 1,
    RTM_EVENT_TYPE_EXIT = 2,
  } rtm_event_type_e;
 
  typedef enum
  {
    ERR_RTM_OK = 0,
    ERR_RTM_FAILED = 1,
    ERR_RTM_LOGIN_REJECTED = 2,
    ERR_RTM_INVALID_RTM_UID = 3,
    ERR_RTM_LOGIN_INVALID_TOKEN = 5,
    ERR_RTM_LOGIN_NOT_AUTHORIZED = 7,
    ERR_RTM_INVALID_APP_ID = ERR_INVALID_APP_ID,
    WARN_RTM_LOOKUP_CHANNEL_REJECTED = ERR_LOOKUP_CHANNEL_REJECTED,
    ERR_RTM_TOKEN_EXPIRED = ERR_TOKEN_EXPIRED,
    ERR_RTM_INVALID_TOKEN = ERR_INVALID_TOKEN,
  } rtm_err_code_e;
 
  typedef struct
  {
    void (*on_rtm_data)(const char *rtm_uid, const void *msg, size_t msg_len);
    void (*on_rtm_event)(const char *rtm_uid, rtm_event_type_e event_type, rtm_err_code_e err_code);
    void (*on_send_rtm_data_result)(uint32_t msg_id, rtm_err_code_e error_code);
  } agora_rtm_handler_t;
 
  extern __agora_api__ int agora_rtc_login_rtm(const char *rtm_uid, const char *rtm_token,
                                               const agora_rtm_handler_t *handler);
 
  extern __agora_api__ int agora_rtc_logout_rtm(void);
 
  extern __agora_api__ int agora_rtc_send_rtm_data(const char *rtm_uid, uint32_t msg_id, const void *msg, size_t msg_len);
#endif // End CONFIG_RTM
 
#ifdef __cplusplus
}
#endif
 
#endif /* __AGORA_RTC_API_H__ */