hikvision-isup-client/include/platform.h

#ifndef PLATFORM_H
#define PLATFORM_H

/**
 * @file platform.h
 * @brief ISUP平台注册管理头文件
 * 
 * 本文件定义设备向ISUP平台(CMS)注册、心跳保活、
 * 登出等核心功能的接口。
 */

#include "common.h"
#include "config.h"

/* 设备注册状态回调数据类型 */
typedef enum {
    DEV_REG_TYPE_ON = 1,            /* 设备上线 */
    DEV_REG_TYPE_OFF,               /* 设备下线 */
    DEV_REG_TYPE_AUTH,              /* 设备认证 */
    DEV_REG_TYPE_SESSIONKEY,        /* 会话密钥 */
    DEV_REG_TYPE_ADDRESS_CHANGED,   /* 地址变更 */
    DEV_REG_TYPE_HEARTBEAT,         /* 心跳 */
    DEV_REG_TYPE_XMLCONFIG,        /* XML配置 */
    DEV_REG_TYPE_VTDU_STREAM,      /* VTDU流 */
} DevRegDataType;

/* 设备注册信息结构 */
typedef struct {
    char sDeviceSerial[64];         /* 设备序列号 */
    char sDeviceID[64];             /* 设备ID */
    char sDeviceName[128];          /* 设备名称 */
    char sDeviceType[32];           /* 设备类型 */
    char sDeviceModel[64];          /* 设备型号 */
    char sSoftwareVersion[32];      /* 软件版本 */
    char sHardwareVersion[32];      /* 硬件版本 */
    char sIPAddress[MAX_IP_SIZE];   /* 设备IP地址 */
    short sIPAddressType;           /* IP地址类型 */
    short sPort;                    /* 端口 */
    int   byChanNum;                /* 模拟通道数 */
    int   byIPChanNum;              /* 数字通道数 */
    int   byStartDChan;             /* 起始数字通道号 */
    int   bySubChanNum;             /* 子通道数 */
    int   bySupportSubChan;         /* 是否支持子通道 */
    time_t tOnlineTime;             /* 上线时间 */
} DevRegInfo;

/* 设备注册回调函数类型 */
/* 
 * 原型: void (*DEVICE_REGISTER_CB)(int iUserID, DWORD dwDataType, 
 *            void* pOutBuffer, DWORD dwOutLen, void* pInBuffer, DWORD dwInLen, void* pUser)
 * 
 * iUserID:       用户ID(登录成功后返回)
 * dwDataType:    数据类型(DEV_REG_TYPE_XXX)
 * pOutBuffer:    输出缓冲区(设备注册信息)
 * dwOutLen:      输出缓冲区长度
 * pInBuffer:     输入缓冲区
 * dwInLen:       输入缓冲区长度
 * pUser:         用户自定义参数
 */
typedef void (*DEVICE_REGISTER_CB)(int iUserID, int dwDataType, 
                                   void* pOutBuffer, int dwOutLen, 
                                   void* pInBuffer, int dwInLen, 
                                   void* pUser);

/* 设备状态回调 */
typedef void (*DeviceStatusCB)(const char* device_id, DeviceStatus status, void* user_data);

/**
 * @brief 初始化CMS库
 * @return 成功返回SUCCESS, 失败返回FAILURE
 * 
 * 说明: 必须在使用ISUP SDK任何其他接口之前调用此函数。
 *       初始化CMS库，分配SDK所需全局资源。
 */
int platform_cms_init(void);

/**
 * @brief 反初始化CMS库
 * 
 * 说明: 程序退出前调用，释放CMS库占用的资源。
 */
void platform_cms_cleanup(void);

/**
 * @brief 启动CMS监听(接收设备注册请求)
 * @param listen_ip 监听IP地址, "0.0.0.0"表示监听所有接口
 * @param listen_port 监听端口
 * @param reg_callback 设备注册回调函数
 * @param user_data 用户自定义数据
 * @return 成功返回SUCCESS, 失败返回FAILURE
 * 
 * 说明: 启动后CMS服务器开始监听来自设备的注册请求。
 *       当设备注册/上线/下线时，会回调reg_callback函数。
 */
int platform_cms_start_listen(const char* listen_ip, short listen_port,
                              DEVICE_REGISTER_CB reg_callback, void* user_data);

/**
 * @brief 停止CMS监听
 * 
 * 说明: 停止接收设备注册请求。
 */
void platform_cms_stop_listen(void);

/**
 * @brief 设备向CMS注册
 * @param server_ip CMS服务器IP地址
 * @param server_port CMS服务器端口
 * @param device_id 设备ID
 * @param protocol_version 协议版本
 * @param encrypt_key 加密密钥
 * @param user_data 用户自定义数据
 * @return 成功返回用户ID(>=0), 失败返回FAILURE
 * 
 * 说明: 设备主动向CMS服务器发起注册请求。
 *       注册成功后返回用户ID，后续操作使用此ID。
 */
int platform_device_register(const char* server_ip, short server_port,
                             const char* device_id, const char* protocol_version,
                             const char* encrypt_key, void* user_data);

/**
 * @brief 设备登出CMS
 * @param user_id 用户ID
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int platform_device_logout(int user_id);

/**
 * @brief 设置自动重连
 * @param user_id 用户ID
 * @param enable 是否启用自动重连
 * @param interval 重连间隔(秒)
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int platform_set_auto_reconnect(int user_id, int enable, int interval);

/**
 * @brief 发送心跳包
 * @param user_id 用户ID
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int platform_send_heartbeat(int user_id);

/**
 * @brief 注册设备状态回调
 * @param cb 状态回调函数
 * @param user_data 用户自定义数据
 */
void platform_register_status_callback(DeviceStatusCB cb, void* user_data);

/**
 * @brief 获取设备注册信息
 * @param device_id 设备ID
 * @param info 输出设备信息结构
 * @return 成功返回SUCCESS, 失败返回FAILURE
 */
int platform_get_device_info(const char* device_id, DevRegInfo* info);

/**
 * @brief 获取所有在线设备列表
 * @param devices 输出设备ID数组
 * @param max_devices 最大设备数
 * @return 返回在线设备数量
 */
int platform_get_online_devices(char devices[][MAX_DEVICE_ID], int max_devices);

#endif /* PLATFORM_H */