/*! @file trro_msg.h
 *
 * 点对点实时消息（peer msg）接口。
 *
 * 独立发布的对外头文件，不依赖 trro_remote.h / trro_field.h。
 * 一份头文件同时提供 controller 侧（TRRO_xxx）与 gateway 侧（TRROField_xxx）
 * 两组接口声明；两侧 SDK 使用同一份 trro_msg.h，实际可用符号由所链接的动态库决定。
 *
 * 仅提供给需要使用点对点实时消息能力的客户使用。
 *
 * 通道特性：
 *   - 点对点实时消息通道在 SDK 初始化后即可使用，不依赖视频会话连接；
 *   - 按发送消息量独立计费；
 *   - 区别于控制通道消息 sendControlData（依赖视频会话连接）；
 *   - 独立限流：单条消息上限 10KB，1s 累计上限 500KB。
 *
 * QoS 语义：
 *   0 = 单向不可靠；
 *   1 = 单向可靠（服务端可靠投递，不保证端到端）；
 *   2 = 端到端可靠。
 * 当前仅支持 qos=1，qos=0 / qos=2 暂未实现。
 *
 * 错误码：函数注释中引用的错误码（如 TRRO_MESSAGE_BYTE_EXCEED、
 *         TRRO_MESSAGE_CHANNEL、TRRO_INIT_ERROR、TRRO_INIT_PRM_ERROR 等）
 *         定义于 trro_error_enum.h，本头文件不直接包含该文件；
 *         如需使用错误码数值，请客户端自行包含 trro_error_enum.h。
 */
#ifndef TRRO_MSG_H
#define TRRO_MSG_H

/* ============================================================
 * 导出宏与调用约定 —— 本头文件自身声明，不依赖其他 TRRO 头文件
 *   - TRRO_MSG_EXPORT   : 与 TRRO_EXPORT / TRROFIELD_EXPORT 兼容
 *   - TRRO_MSG_STD_CALL : 与 STD_CALL 兼容（仅 Windows+USE_CSHARP 生效）
 * ============================================================ */
#if defined(_WIN32) || defined(_WIN64)
#  ifdef TRRO_EXPORTS
#    define TRRO_MSG_EXPORT __declspec(dllexport)
#  else
#    define TRRO_MSG_EXPORT __declspec(dllimport)
#  endif
#  ifdef USE_CSHARP
#    define TRRO_MSG_STD_CALL __stdcall
#  else
#    define TRRO_MSG_STD_CALL
#  endif
#else
#  define TRRO_MSG_EXPORT __attribute__((visibility("default")))
#  define TRRO_MSG_STD_CALL
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================
 * Controller 侧接口（链接 trro_remote SDK 时可用）
 * ============================================================ */

/*
 * @name  TRRO_onPeerMsg
 * @brief 接收远端设备通过点对点实时消息通道发送的消息回调。
 *        独立限流：单条上限 10KB，1s 累计 500KB。
 * @param context           回调上下文指针
 * @param source            消息来源设备id（gwid）
 * @param msg               消息体（已 base64 解码后的原始二进制透传）
 * @param len               消息体长度
 * @param qos               消息 qos（当前仅支持 1）
 * @param channel           通道号（当前仅支持 0）
 * @param custom_msg_tag    发送方在 sendPeerMsg 时提供的自定义消息标签
 * @return void
 */
typedef void TRRO_MSG_STD_CALL TRRO_onPeerMsg(void* context, const char* source, const char* msg, int len, int qos, int channel, long long custom_msg_tag);

/*
 * @name  TRRO_sendPeerMsg
 * @brief 向指定远端设备发送点对点实时消息。
 *        点对点实时消息通道在 SDK 初始化后即可使用，不依赖视频会话连接，
 *        按发送消息量独立计费；区别于控制通道消息 sendControlData（依赖视频会话连接）。
 *        限流：单条 msg 上限 10KB；累计 500KB/秒（超限返回 -TRRO_MESSAGE_BYTE_EXCEED）。
 *        QoS 语义：0=单向不可靠；1=单向可靠（服务端可靠投递，不保证端到端）；2=端到端可靠。
 *        当前仅支持 qos=1，qos=0/qos=2 暂未实现。
 * @param target             目标远端设备id
 * @param msg                消息体，二进制透传
 * @param len                消息体长度（<= 10*1024）
 * @param qos                消息 qos（当前仅支持 1）
 * @param channel            通道号（当前仅支持 0）
 * @param custom_msg_tag     客户提供的自定义消息标签（消息ID），会透传到对端 onPeerMsg 回调
 * @return 成功 TRRO_SUCCEED 失败 <= 0
 *         可能返回的错误码（数值定义见 trro_error_enum.h）：
 *         -TRRO_COMMON_ERROR                        SDK未初始化
 *         -TRRO_PARAM_INVALID / -TRRO_INIT_PRM_ERROR  入参非法
 *         -TRRO_MESSAGE_BYTE_EXCEED                 单条超过 10KB 或 1s 累计超过 500KB
 *         -TRRO_MESSAGE_CHANNEL                     实时消息通道异常
 */
TRRO_MSG_EXPORT int TRRO_sendPeerMsg(const char* target, const char* msg, int len, int qos, int channel, long long custom_msg_tag);

/*
 * @name  TRRO_registerPeerMsgCallback
 * @brief 注册接收点对点实时消息的回调函数
 * @param context   上下文指针，回调时会返回注册时传入的该指针
 * @param callback  回调函数
 * @return void
 */
TRRO_MSG_EXPORT void TRRO_registerPeerMsgCallback(void* context, TRRO_onPeerMsg* callback);


/* ============================================================
 * Gateway 侧接口（链接 trro_field SDK 时可用）
 * ============================================================ */

/*
 * @name  TRROField_onPeerMsg
 * @brief 接收远端设备通过点对点实时消息通道发送的消息回调。
 *        独立限流：单条上限 10KB，1s 累计 500KB。
 * @param context           上下文指针，返回注册时传入的 context
 * @param source            远端设备ID（controller 侧）
 * @param msg               消息体内容（已 base64 解码后的原始二进制透传）
 * @param len               消息体长度
 * @param qos               消息 qos（当前仅支持 1）
 * @param channel           通道号（当前仅支持 0）
 * @param custom_msg_tag    发送方在 sendPeerMsg 时提供的自定义消息标签
 * @return void
 */
typedef void TRROField_onPeerMsg(void* context, const char* source, const char* msg, int len, int qos, int channel, long long custom_msg_tag);

/*
 * @name  TRROField_sendPeerMsg
 * @brief 向指定远端设备发送点对点实时消息。
 *        点对点实时消息通道在 SDK 初始化后即可使用，不依赖视频会话连接，
 *        按发送消息量独立计费；区别于控制通道消息 sendControlData（依赖视频会话连接）。
 *        限流：单条 msg 上限 10KB；累计 500KB/秒（超限返回 -TRRO_MESSAGE_BYTE_EXCEED）。
 *        QoS 语义：0=单向不可靠；1=单向可靠（服务端可靠投递，不保证端到端）；2=端到端可靠。
 *        当前仅支持 qos=1，qos=0/qos=2 暂未实现。
 * @param target             目标设备id，不可为空
 * @param msg                消息体，二进制透传
 * @param len                消息体长度（<= 10*1024）
 * @param qos                消息 qos（当前仅支持 1）
 * @param channel            通道号（当前仅支持 0）
 * @param custom_msg_tag     客户提供的自定义消息标签（消息ID），会透传到对端 onPeerMsg 回调
 * @return 1 for success, other failed
 *         可能返回的错误码（数值定义见 trro_error_enum.h）：
 *         -TRRO_INIT_ERROR                          SDK未初始化
 *         -TRRO_INIT_PRM_ERROR                      target 为空
 *         -TRRO_MESSAGE_BYTE_EXCEED                 单条超过 10KB 或 1s 累计超过 500KB
 *         -TRRO_MESSAGE_CHANNEL                     实时消息通道异常
 */
TRRO_MSG_EXPORT int TRROField_sendPeerMsg(const char* target, const char* msg, int len, int qos, int channel, long long custom_msg_tag);

/*
 * @name  TRROField_registerPeerMsgCallback
 * @brief 注册接收点对点实时消息的回调函数
 * @param context   上下文指针，回调时会返回该上下文指针
 * @param callback  回调函数
 * @return 1 for success, other failed
 *         可能返回的错误码（数值定义见 trro_error_enum.h）：
 *         -TRRO_INIT_ERROR                          SDK未处于初始化或运行状态
 */
TRRO_MSG_EXPORT int TRROField_registerPeerMsgCallback(void* context, TRROField_onPeerMsg* callback);

#ifdef __cplusplus
}
#endif

#endif /* TRRO_MSG_H */
