C# 封裝海康威視 DVR 客戶端 SDK 完整指南

前言

海康威視作為安防監控領域的領導品牌，其 DVR/NVR 設備廣泛應用於各類項目。雖然官方提供 C++ 版本的 HCNetSDK，但在 .NET 生態下開發若能直接使用 C# 封裝的 SDK，將大幅提升開發效率。本文提供一個完整的 C# 封裝類 Hik_HCNetSDK，涵蓋設備登入、預覽、回放、雲台控制、語音對講、透明通道等核心功能，並對常見結構體、委託、錯誤碼進行了詳細定義，方便開發者快速集成。

核心結構體定義

封裝中定義了與 SDK 交互所需的關鍵結構體，確保記憶體佈局與原生 DLL 一致：

• NET_DVR_DEVICEINFO：設備資訊，包含序列號、報警輸入/輸出數、硬盤數、通道數等。
• NET_DVR_DISKSTATE：硬盤狀態，記錄容量、剩餘空間、工作狀態。
• NET_DVR_TIME：時間結構，用於錄像檔案查詢、回放定位。
• NET_DVR_FIND_DATA：尋找檔案返回資料，含檔案名、起止時間、大小。
• NET_DVR_CHANNELSTATE：通道狀態，涵蓋錄像、信號、硬體狀態、碼率、連接客戶端 IP。
• NET_DVR_WORKSTATE：設備整體工作狀態，彙總硬盤、通道、報警輸入輸出狀態。
• NET_DVR_ETHERNET / NET_DVR_NETCFG：網路配置結構，支援雙網卡、PPPoE、DDNS、NTP 等參數。
• NET_DVR_CLIENTINFO：預覽參數，指定通道、碼流類型、播放窗口句柄、多播地址。

關鍵委託與回調

為了接收異步數據，定義了以下委託類型：

• fVoiceDataCallBack：語音對講數據回調。
• SerialDataCallBack：透明通道（串口）數據回調。
• DrawFun：預覽繪圖回調，可在視頻幀上繪製圖形。
• RealDataCallBack：實時流數據回調（系統頭、流數據）。
• PlayDataCallBack：回放流數據回調。

常用功能封裝

初始化與登入

// 初始化 SDK
bool init = Hik_HCNetSDK.NET_DVR_Init();

// 登入設備
NET_DVR_DEVICEINFO deviceInfo = new NET_DVR_DEVICEINFO();
int userId = Hik_HCNetSDK.NET_DVR_Login("192.168.1.64", 8000, "admin", "12345", ref deviceInfo);
if (userId < 0) {
    uint err = Hik_HCNetSDK.NET_DVR_GetLastError();
    // 處理錯誤
}

實時預覽

NET_DVR_CLIENTINFO clientInfo = new NET_DVR_CLIENTINFO {
    lChannel = 1,
    lLinkMode = 0, // TCP 主碼流
    hPlayWnd = pictureBox1.Handle,
    sMultiCastIP = ""
};
int realHandle = Hik_HCNetSDK.NET_DVR_RealPlay(userId, ref clientInfo);

// 設置碼流回調
Hik_HCNetSDK.NET_DVR_SetRealDataCallBack(realHandle, RealDataCallBack, 0);

// 停止預覽
Hik_HCNetSDK.NET_DVR_StopRealPlay(realHandle);

錄像回放

// 按時間回放
NET_DVR_TIME start = new NET_DVR_TIME { dwYear = 2024, dwMonth = 1, dwDay = 1, dwHour = 0, dwMinute = 0, dwSecond = 0 };
NET_DVR_TIME stop = new NET_DVR_TIME { dwYear = 2024, dwMonth = 1, dwDay = 1, dwHour = 23, dwMinute = 59, dwSecond = 59 };
int playHandle = Hik_HCNetSDK.NET_DVR_PlayBackByTime(userId, 1, ref start, ref stop, pictureBox1.Handle);

// 控制播放：暫停、繼續、倍速、定位
Hik_HCNetSDK.NET_DVR_PlayBackControl(playHandle, Hik_HCNetSDK.NET_DVR_PLAYPAUSE, 0, 0);

雲台控制 (PTZ)

// 以速度控制雲台移動
Hik_HCNetSDK.NET_DVR_PTZControlWithSpeed(realHandle, Hik_HCNetSDK.TILT_UP, 0, 4); // 速度 4 向上
// 預置點操作
Hik_HCNetSDK.NET_DVR_PTZPreset(realHandle, Hik_HCNetSDK.SET_PRESET, 1); // 設置預置點 1
Hik_HCNetSDK.NET_DVR_PTZPreset(realHandle, Hik_HCNetSDK.GOTO_PRESET, 1); // 轉至預置點 1

語音對講與廣播

// 開始語音對講
int voiceHandle = Hik_HCNetSDK.NET_DVR_StartVoiceCom(userId, VoiceDataCallback, 0);
Hik_HCNetSDK.NET_DVR_SetVoiceComClientVolume(voiceHandle, 5000); // 設置音量
// 停止
Hik_HCNetSDK.NET_DVR_StopVoiceCom(voiceHandle);

透明通道 (RS232/RS485)

int serialHandle = Hik_HCNetSDK.NET_DVR_SerialStart(userId, 1, SerialDataCallback, 0); // 串口 1
byte[] cmd = Encoding.ASCII.GetBytes("AT\r\n");
Hik_HCNetSDK.NET_DVR_SerialSend(serialHandle, 1, cmd, (uint)cmd.Length);
Hik_HCNetSDK.NET_DVR_SerialStop(serialHandle);

錯誤碼對照表

封裝中完整定義了 NET_DVR_NOERROR (0) 至 NET_DVR_DDRAWDEVICENOSUPPORT (58) 共 59 個常見錯誤碼，並包含尋找檔案返回碼 (NET_DVR_FILE_SUCCESS 等) 及設備能力集位掩碼 (NET_DVR_SUPPORT_DDRAW 等)，方便調試時快速定位問題。

注意事項

1. DLL 依賴：確保 HCNetSDK.dll 及其依賴項（如 PlayCtrl.dll、StreamTransClient.dll）放置於程式運行目錄或系統 PATH 中。
2. 平台目標：SDK 多為 32 位，專案建議勾選「Prefer 32-bit」或明確設定 x86 編譯。
3. 資源釋放：程式退出前務必調用 NET_DVR_Logout 及 NET_DVR_Cleanup，避免設備端連接數洩漏。
4. 回調線程：所有回調均在 SDK 內部線程觸發，UI 操作需用 Control.Invoke 跨線程處理。

總結

本封裝類將海康威視 HCNetSDK 的核心介面以強類型、物件導向方式暴露給 C# 開發者，消除了手寫 P/Invoke 的繁瑣與易錯環節。結合上述範例，可快速構建預覽、回放、雲台控制、語音對講等功能模組，適用於中小型安防監控平台的二次開發。後續可根據項目需求擴展智能分析、人臉識別、門禁對接等高階介面。