4. 海康威视SDK接入实战：设备搜索、登录、实时预览、抓图接口封装

4.1 原理概述

海康威视网络摄像机的设备接入通常依赖于其专有的SDK（HCNetSDK）。该SDK封装了设备发现、会话管理、码流传输和图像抓取等底层通信协议（如私有ISAPI或标准ONVIF的扩展），为开发者提供了一套C/C++风格的API接口。其核心工作流可概括为：

• 搜索阶段：通过UDP广播或基于Net DEVICE协议的局域网发现，获取设备的IP地址、端口、序列号及支持能力。
• 登录阶段：建立TCP长连接，通过用户名/密码认证，获取设备操作句柄（UserID）。
• 预览阶段：基于登录句柄申请实时流预览，返回播放句柄，随后通过回调或显式渲染展示视频。
• 抓图阶段：对播放中的实时流或通道截图，支持JPEG/PNG格式的直接回传或本地保存。

封装的目的在于将上述复杂且异步的SDK调用抽象为高内聚的类或模块，简化业务层的调用逻辑。

4.2 实现流程与接口设计

本节基于 C++ 实现，采用面向对象的封装思想，将 HikDevice 类作为核心接入单元。

4.3 核心代码实现与封装

以下为 HikDevice 类的关键片段，展示了搜索、登录、预览、抓图的集成模式。

// HikDevice.h —— 核心封装声明
#include <string>
#include <vector>
#include <functional>
#include "HCNetSDK.h"

struct DeviceInfo {
    std::string ip;
    unsigned short port;
    std::string serial;
    std::string deviceType;
};

class HikDevice {
public:
    // 静态初始化，仅调用一次
    static bool Initialize();
    static void Cleanup();

    // 搜索设备（异步结果通过回调返回）
    void SearchDevices(std::function<void(const std::vector<DeviceInfo>&)> onSearchDone);
    // 登录
    long Login(const std::string& ip, unsigned short port,
               const std::string& user, const std::string& pwd);
    // 实时预览，返回预览句柄
    long StartPreview(long loginID, int channel, HWND hWnd);
    // 抓图
    bool CapturePicture(long previewID, const std::string& filePath);
    // 资源清理
    void StopPreview(long previewID);
    void Logout(long loginID);

private:
    // 内部搜索回调（静态，用于适配SDK）
    static void CALLBACK SearchCallback(LONG lCommand, void* pUser);
    std::vector<DeviceInfo> deviceList_;
};

// HikDevice.cpp —— 搜索与登录实现片段
bool HikDevice::Initialize() {
    bool ret = NET_DVR_Init();
    if (ret) NET_DVR_SetLogToFile(3, nullptr, true);
    return ret;
}

void HikDevice::SearchDevices(std::function<void(const std::vector<DeviceInfo>&)> onSearchDone) {
    deviceList_.clear();
    // 发起搜索，注册回调
    NET_DVR_StartSearchDevice(SearchCallback, this);
    // 等待回调填充 deviceList_（实际需事件通知）
    // onSearchDone(deviceList_);  // 出于示例简化
}

long HikDevice::Login(const std::string& ip, unsigned short port,
                      const std::string& user, const std::string& pwd) {
    NET_DVR_USER_LOGIN_INFO loginInfo = {0};
    NET_DVR_DEVICEINFO_V40 deviceInfo;
    strcpy(loginInfo.sDeviceAddress, ip.c_str());
    loginInfo.wPort = port;
    strcpy(loginInfo.sUserName, user.c_str());
    strcpy(loginInfo.sPassword, pwd.c_str());
    long userID = NET_DVR_Login_V40(&loginInfo, &deviceInfo);
    return userID;
}

long HikDevice::StartPreview(long loginID, int channel, HWND hWnd) {
    NET_DVR_PREVIEWINFO previewInfo = {0};
    previewInfo.lChannel = channel;
    previewInfo.hPlayWnd = hWnd;          // 渲染窗口句柄
    previewInfo.dwStreamType = 0;         // 主码流
    previewInfo.bBlocked = true;          // 阻塞模式
    long realHandle = NET_DVR_RealPlay_V40(loginID, &previewInfo, nullptr, nullptr);
    return realHandle;
}

bool HikDevice::CapturePicture(long previewID, const std::string& filePath) {
    return NET_DVR_CapturePicture(previewID, (char*)filePath.c_str());
}

4.4 调试与部署要点

• SDK版本与架构：海康SDK区分32/64位，且不同版本（如V3.0/V5.0）部分API签名有差异，必须核对头文件版本。
• 日志启用：通过 NET_DVR_SetLogToFile 开启完整日志，可定位登录失败原因（如密码加密方式、端口设定错误）。
• 预览窗口句柄：若不在主线程传递窗口句柄（如纯服务器环境传NULL），需通过回调自行处理YUV/RGB数据，不能直接依赖SDK内部渲染。
• 抓图异步性：建议在抓图前通过 Sleep(200) 等待预览稳定，否则可能抓取黑帧或空白图片。

// 调试示例：登录后校验句柄有效性
long userID = device.Login("192.168.1.100", 8000, "admin", "abc123");
if (userID < 0) {
    printf("Login failed, error code: %d\n", NET_DVR_GetLastError());
    // -1 通常为网络不通或密码错误，-7 可能是SDK未初始化
} else {
    printf("Login success, UserID: %ld\n", userID);
    // 进一步调用预览
    long previewID = device.StartPreview(userID, 1, hWnd);
}

4.5 性能与稳定性优化

// RAII 资源封装示例
class PreviewGuard {
public:
    PreviewGuard(long previewID) : m_previewID(previewID) {}
    ~PreviewGuard() { if (m_previewID >= 0) NET_DVR_StopRealPlay(m_previewID); }
private:
    long m_previewID;
};

void SafePreview(HikDevice& dev, long loginID) {
    long previewID = dev.StartPreview(loginID, 1, nullptr); // 非渲染模式
    PreviewGuard guard(previewID);
    // 业务处理...
    // 作用域结束自动停止预览
}