ECat Windows SDK使用文档#

ECat Windows SDK使用文档
- 一、接入步骤
- 二、API说明

一、接入步骤#

1.1 SDK文件说明#

libs：
- x86_64
  - ECat.dll：SDK
  - ECatHandler.dll：进程外dump程序
- x86
  - ECat.dll：SDK
  - ECatHandler.dll：进程外dump程序
include
- CrashReport.h：API头文件
- ECatHandler.hpp：用于捕获InvalidParameter和PureCall类型的异常

1.2 SDK集成#

添加VS工程属性

在工程属性->C/C++->常规->附加包含目录，添加SDK include所在路径；

在工程属性->链接器->常规->附加库目录，添加SDK libs所在路径；

在工程属性->链接器->输入->附加依赖项，添加ECat.lib;
初始化

#include "CrashReport.h"
#include "ECatHandler.hpp" //可选

int main() {
    
    //初始化配置(必须)
    ECat::Config config;
    config.enableDebugMode = true;//是否启用调试模式（默认：false，正式发布的版本请设置为false）
    config.appVersion = "2.0"; //应用版本
    config.userId = "uid01";	//用户id
    config.appChannel = "test";
    
    //初始化(必须，使用平台分配的AppId)
	ECat::initCrashReport("1234567890", config);
    
    //注册invalid_parameter_handler和purecall_handler(可选)
    ECat::SetExceptionHandler();
   	//...
}

关于CRT异常捕获的说明：

在运行库的配置为[MT](/MD、-MT、-LD（使用运行时库） | Microsoft Learn)时，由于ECat.dll与其他模块有不同的C运行时(CRT)环境，对于invalid_parameter和purecall两类异常，在一个CRT环境注册的异常捕获句柄不能捕获到其他CRT环境的异常。

因此需要在exe或其他dll的代码中调用_set_invalid_parameter_handler和_set_purecall_handler，将这两种异常抛出，ECat才能捕获异常并生成minidump。否则，ECat无法捕获此类崩溃。

关于invalid_parameter和purecall异常的说明：

_set_invalid_parameter_handler、_set_thread_local_invalid_parameter_handler | Microsoft Learn

_get_purecall_handler、_set_purecall_handler | Microsoft Learn

1.3 符号文件上传#

有关符号文件的说明见《符号文件上传工具使用文档》

二、API说明#

namespace ECat {

    // 崩溃发生时的自定义回调
    typedef bool (*CrashCallback)(const char* crashInfo);

    //初始化配置
    struct Config {
        char* appVersion;
        char* appChannel;
        char* userId;
        bool enableDebugMode;
        char* serverUrl;
        unsigned int reportDelay;  //开启应用后上传本地未发送异常的延迟时间，单位:秒
        unsigned int lagThreshold; //卡顿阈值（单位：ms，有效值：2000-10000，默认：5000）

        char* dataAbsolutePath;  //生成文件的绝对路径，若该路径不存在或无权限，默认使用可执行程序所在路径
        CrashCallback callback;

        Config(): appVersion(nullptr), appChannel(nullptr), userId(nullptr),
        enableDebugMode(false), serverUrl(nullptr), reportDelay(0),
        lagThreshold(5000), dataAbsolutePath(nullptr), callback(nullptr) {}
    };

    //使能接口，初始化前设置为false可使之后的操作失效，不调用时默认为true
    ECatAPI void enable(bool enableFlag);

    /* 初始化
     * @param appId 注册时申请的APPID
     * @param config 初始化配置
     */
    ECatAPI void initCrashReport(const char* appId, const Config* config);

    //上传自定义异常
    ECatAPI void postException(const int crashType,
                                        const char* crashSignal,
                                        const char* crashMessage,
                                        const char* stackTrace);

    //获取SDK版本
    ECatAPI const char* getSdkVersion();

    //设置用户Id
    ECatAPI void setUserId(const char* userId);

    //设置AppVersion
    ECatAPI void setAppVersion(const char* appVersion);

    //设置卡顿阈值（单位：ms，有效值：2000-10000，默认：5000）
    ECatAPI void setLagThreshold(unsigned int lagThreshold);

    //开启卡顿检测 (调用停止卡顿接口后使用)
    ECatAPI void startLagMonitor();

    //停止检测卡顿
    //duration: 停止持续时间（单位：秒），duration > 0时，经过duration时间后卡顿检测再次开启，否则不再开启
    ECatAPI void stopLagMonitor(unsigned int duration);
    
    //设置场景tag
    ECatAPI void setSceneTag(const int tag);

    //崩溃测试
    ECatAPI void testNativeCrash();

    /* 设置自定义的键值对（最多64对）
     * @param key 自定义键（以字母开头的数字字母组合，最大长度32）
     * @param value 值（最大长度1024）
     */
    ECatAPI void putUserData(const char* key, const char* value);
    
    //删除键值对
    ECatAPI void removeUserData(const char* key);

    //获取内部设备id
    ECatAPI const char* getDeviceId();

    /**
     * 获取应用上次退出信息
     * @return 上次退出信息(json格式)，示例：{"type":"","crashUuid":"","crashTime":0,"finishCrashCallback":false}
     * 字段说明：
     * type：退出类型。取值范围：
     *      ""：无崩溃
     *      "NativeCrash"：Native崩溃
     * crashUuid：崩溃id。若上次退出类型为崩溃，则为该崩溃数据的id
     * crashTime：崩溃时间(单位：毫秒)。若上次退出类型为崩溃，则为该崩溃的时间
     * finishCrashCallback：是否完成CrashCallback崩溃回调。若上次崩溃后，执行了回调函数并且回调函数返回值为true，则为true，否则为false
     */
    ECatAPI const char* getLastExitInfo();

    /**
     * 设置崩溃回调函数
     * 由于崩溃回调会阻塞崩溃线程，因此若在回调中执行异步逻辑，可能会执行失败。
     * @param callback
     * 崩溃回调的参数（json字符串），参数说明：
     * 示例：{"type":"NativeCrash","crashUuid":"7A9A5EB7-8705-4C68-BAAA-3C1DA35E3409"}
     * type：崩溃类型，取值范围：
     *     "NativeCrash"：Native崩溃
     * crashUuid：崩溃id，与对应异常数据的id相同
     *
     * 返回值，true代表回调成功
     */
    ECatAPI void setCrashCallback(const CrashCallback callback);
}