简介面向海康摄像头二次开发的工程师这款开箱即用的调试客户端能快速验证视频取流、录像回放、云台控制、报警联动等核心能力节省项目前期的环境搭建成本尤其适合有编程基础、需要先跑通设备再深入定制的场景。压缩包共52个文件以35个动态库和7个静态库为主是接入所需的SDK核心组件另有CHM/PDF格式的接口与使用手册、可直接运行的示例程序、参数配置文件和日志文件整体约37.9MB结构便于按需查找。目前已有3333人学习下载可作为正式开发前的快速参考。内置海康SDK无需单独下载配置开发者可直接登录设备调整实时预览的分辨率、帧率、编码格式测试录像倍速回放、云台预置点巡航、报警联动策略、网络参数设置与用户权限管理并通过完整日志定位对接问题。配套的PDF/CHM文档和Demo覆盖常用接口的调用方式、参数和返回值能帮助把调试验证结果迁移到自有项目中。1. ClientDemo 到底是什么海康摄像头的接入调试绕不开一套叫 ClientDemo 的客户端工具。它是海康威视设备网络 SDK 分发包里附带的可执行示例对外表现是一个能登录设备、看预览、查录像、做云台控制的程序但对做集成的人来说它是「SDK 怎么被正确调用」的最直接证据。很多团队拿到 SDK 后的第一件事是跑 ClientDemo不是拿它当成品用而是给后续的平台接入定一个参照基线网络通不通、账号密码对不对、取流走私有通道还是 RTSP在这个工具上都能先验一遍。下面把 ClientDemo 背后的调用链、参数和排错方法讲透适合正在对接海康摄像头、又不想翻完几百页 API 文档的开发者。2. ClientDemo 能调什么海康摄像头 SDK 调用链与调试边界2.1 先分清 ClientDemo 与 SDK 的关系ClientDemo 是一个按 SDK 接口顺序拼出来的最小客户端不是官方上位机的平替。它的界面布局基本按 API 能力分组本地配置、登录、实时预览、回放、云台、报警、对讲、远程配置。每个按钮背后对应一次或一组 SDK 调用比如点「预览」时程序先通过NET_DVR_Login_V40拿到用户 ID再用NET_DVR_RealPlay_V40申请预览句柄最后注册回调接收码流。这个顺序在文档里是按章节写的在 demo 里是按按钮写的调试时直接看按钮的触发函数就能理清依赖关系。提到调试边界是因为很多人会把 SDK 当成万能层。SDK 的职责到码流回调为止解码、渲染、存储、转封装都是调用方自己处理。预览窗口黑屏但回调数据在涨问题大概率在解码器不在登录与取流。还有一个很容易误判的点海康 4G 监控摄像头在夜间全彩模式下灵敏度偏低这类问题归设备图像策略SDK 层能改的只有码流类型、分辨率和帧率不要试图在 ClientDemo 里找夜间画质参数。出图效果不满足需求时先调整的是设备端补光策略和日夜转换阈值而不是接入代码。2.2 SDK 包目录结构与动态库依赖拿到设备网络 SDK 压缩包后常见做法是先用包里的 ClientDemo 做连通性验证然后才把自己项目的工程文件链到 HCNetSDK 上。Windows 分发包里有HCNetSDK.dll、HCCore.dll、PlayCtrl.dll、AudioRender.dll以及一堆HCNetSDKCom目录下的组件库Linux 分发版则提供libhcnetsdk.so和对应.so依赖。下表列出最容易出问题的几个文件。文件作用缺失或错版本时的现象HCNetSDK.dll / libhcnetsdk.so登录、取流、报警、设备配置等核心接口进程启动时报找不到动态库或登录返回负值HCCore.dll网络传输与线程基础组件初始化失败日志停在 NET_DVR_Init 步骤PlayCtrl.dll本地解码与画面渲染预览窗口黑屏但码流回调有数据AudioRender.dll音频播放与对讲采集对讲无声音、音频设备初始化失败HCNetSDKCom 下的插件库部分加密设备和特殊编码格式登录成功但取流失败或取流后解码异常把这些库放在可执行文件同一目录是最省事的做法。Windows 上不要图方便把 SDK 的 bin 加到系统 PATH多个项目用不同 SDK 版本时PATH 里的版本会先被加载造成错版本加载。Linux 下用LD_LIBRARY_PATH指到 SDK 的 so 目录即可。# Windows 下确认 bin 目录里关键库齐全 dir HCNetSDK*.dll HCCore.dll PlayCtrl.dll 2nul | findstr /i .dll # Linux 下指定 SDK 库目录后启动 ClientDemo export LD_LIBRARY_PATH$PWD/HCNetSDKCom:/opt/hik/libs ./ClientDemo启动后如果立刻报缺少HCNetSDK.dll先确认 SDK 包解压目录层级是否正确。官方压缩包常见一层顶层目录直接解压到桌面有时会把 lib 放到子目录里而 ClientDemo 启动时只会在自己的可执行目录下找库。2.3 登录 ClientDemo 前先验证设备可达ClientDemo 的登录窗口只有 IP、端口、用户名、密码四项很多人填完点登录没反应就先去改代码。实际上多数登录失败在填密码之前就已经定了网络不通。海康设备默认使用 8000 端口做 SDK 信令554 留给 RTSP80 给网页。设备在另一个网段时先确认三层路由可达4G 摄像头拨号后拿到的地址可能定期变化ClientDemo 适合在现场直连环境下调试跨公网调试不如直接看设备注册平台的状态。# 检查目标设备 8000 端口是否在监听 nc -zv 192.168.1.64 8000 -w 3 # 若设备开启了网页服务可通过 HTTP 状态码判断设备存活 curl -s -o /dev/null -w %{http_code}\n http://192.168.1.64/端口通了再登录。如果端口不通先 ping 一下设备ICMP 通但端口不通往往是防火墙策略ICMP 不通就要查 IP 掩码和路由表。这里有一个经验ClientDemo 登录超时的默认表现是转圈十几秒然后弹出失败这时候去看NET_DVR_GetLastError()的返回值比反复改密码有用得多。3. 用 ClientDemo 跑通海康摄像头接入的最小流程3.1 环境准备SDK 位数、运行库与设备版本开始写代码前先把 SDK 版本和编译器位数对齐。海康设备网络 SDK 同时提供 32 位和 64 位库C/C 工程编译成多少位就加载对应位数的动态库。位数不一致时链接阶段能过运行阶段会出现函数指针调用失败或结构体大小不匹配表现是登录返回负值但错误码没有任何明确信息。下表是环境检查清单。检查项建议做法踩坑点编译器位数与 SDK 库位数保持一致混合位数会产生结构体对齐问题SDK 版本用与设备固件发布时间接近的版本旧 SDK 可能不支持新固件的加密登录可执行文件路径把 DLL/SO 放到 exe 同目录依赖 PATH 会出现版本串用设备通道号登录后读取设备信息结构体中的通道字段在界面里写死 0 常导致预览失败IPC 一般只有一个视频通道录像机则有多路通道号从设备信息结构体里的通道起始字段开始按顺序排。ClientDemo 的设备信息栏里能看到通道总数调平台对接时应该读这个字段而不是写死 1 或写死 0。3.2 最小登录代码与错误码判断下面的片段是登录的最小闭环也是 ClientDemo 登录按钮背后实际做的事NET_DVR_Init(); NET_DVR_SetConnectTime(5000, 2); NET_DVR_SetReconnect(10000, TRUE); NET_DVR_USER_LOGIN_INFO loginInfo { 0 }; NET_DVR_DEVICEINFO_V40 deviceInfo { 0 }; strcpy(loginInfo.sDeviceAddress, 192.168.1.64); // 局域网直接填设备 IP loginInfo.wPort 8000; // 设备默认 SDK 端口 strcpy(loginInfo.sUserName, admin); strcpy(loginInfo.sPassword, my_password); LONG userId NET_DVR_Login_V40(loginInfo, deviceInfo); if (userId 0) { printf(NET_DVR_Login_V40 failed: %d\n, NET_DVR_GetLastError()); NET_DVR_Cleanup(); return -1; }NET_DVR_Init只需要调用一次进程结束前调用NET_DVR_Cleanup收尾。每次登录用独立的userId多设备循环登录时不要复用同一个用户 ID。NET_DVR_SetConnectTime第一个参数是单次连接超时毫秒数第二个参数是重试次数平台接入时超时给 3000 到 5000 毫秒比较合适太短容易在弱网下误报离线太长会拖慢故障切换。NET_DVR_SetReconnect是设备断线后 SDK 自动重连的开关参数分别为重连间隔毫秒数和是否启用。GetLastError 返回值含义排查方向7网络不可达或连接超时按前一章步骤检查 8000 端口确认设备未被平台长连接占用9用户名或密码错误在设备网页或 SADP 里重置注意密码大小写和特殊字符其他以 SDK 头文件中 ERROR_ 开头的宏定义为准直接查当前 SDK 版本配套的错误码说明设备被另一个平台长连接占用时也可能出现登录失败这类问题从错误码表面看不出来需要抓包确认连接是被拒绝还是被重置。3.3 实时预览与码流回调的参数设置登录成功后的下一步是申请预览句柄。ClientDemo 的预览按钮把窗口句柄直接传给 SDK让 SDK 自己去渲染平台接入时通常不想要渲染而是把码流交给回调函数做转发或转封装。NET_DVR_PREVIEWINFO previewInfo { 0 }; previewInfo.lChannel 1; // 通道号按设备信息里的起始通道来填 previewInfo.dwStreamType 0; // 0 主码流1 子码流 previewInfo.hPlayWnd NULL; // 平台取流时留空用回调接裸流 LONG previewHandle NET_DVR_RealPlay_V40(userId, previewInfo, NULL, NULL); if (previewHandle 0) { printf(NET_DVR_RealPlay_V40 failed: %d\n, NET_DVR_GetLastError()); return -1; } NET_DVR_SetRealDataCallBack(previewHandle, OnRealData, NULL);回调函数长这样void CALLBACK OnRealData(LONG lRealHandle, DWORD dwDataType, BYTE *pBuffer, DWORD dwBufSize, void *pUser) { if (dwDataType NET_DVR_STREAMDATA) { // 回调里拿到的是封装后的码流需要按 PS 或裸 H.264 解析后交给编码器 // pBuffer 是 SDK 内部缓冲区回调返回后内容会被覆盖必须拷贝 } }hPlayWnd传NULL时 SDK 不做本地渲染只把数据交给回调。平台对接通常用这种方式拿裸流再自己封装成 PS/MP4 或推到流媒体服务。回调里先收到系统头之后才是连续的流数据系统头是解码器初始化的重要前提丢失会导致花屏或解码失败。3.4 从 ClientDemo 迁移到平台时的四个坑ClientDemo 是单机调试思路搬到平台项目里至少有四件事不能照抄。第一句柄释放顺序。退出预览时先调用NET_DVR_StopRealPlay再登出最后NET_DVR_Cleanup反过来会拿到句柄失效的错误。第二自动重连的语义。NET_DVR_SetReconnect只能保证 SDK 内部尝试重连平台侧要额外处理设备状态回调才能感知断线否则平台数据库里的设备状态会一直显示在线。第三回调线程模型。SDK 工作线程负责调用回调不要在回调里直接操作界面控件UI 线程和 SDK 线程互相等会造成假死。第四回调缓冲生命周期。上一次回调里没拷贝缓冲区下一次回调到来时旧数据已经被覆盖许多预览花屏和视频锯齿都是这个原因。注意预览句柄和用户句柄都要做生命周期管理平台侧重连逻辑必须幂等同一路通道不要重复申请预览。4. 从 ClientDemo 到平台接入RTSP 取流、报警布防与安全加固4.1 平台取流优先走 RTSP海康摄像头 rtsp 地址拼法与验证SDK 取流适合需要信令配合的场景比如报警联动录像、云台控制、对讲。平台在做视频接入时很多团队更喜欢让流媒体服务直接通过 RTSP 拉流减少对 SDK 动态库的依赖。海康摄像头的 RTSP 地址格式相对固定rtsp://admin:password192.168.1.64:554/Streaming/Channels/101101代表第一通道的主码流102是同一通道的子码流多通道录像机按201、202递增。用户名密码与登录参数一致。用下面的命令验证地址可拉流ffprobe -rtsp_transport tcp \ -i rtsp://admin:password192.168.1.64:554/Streaming/Channels/101 \ -show_entries streamcodec_name,width,height,avg_frame_rate -of csv能看到编码参数和分辨率就说明地址与鉴权都对。RTSP 方式拿到的流不带海康私有结构直接用 FFmpeg 处理比较方便缺点是报警、云台、设备重启这些信令能力需要另一套通道补偿一般做法是再挂一个 SDK 服务专门处理信令。4.2 跨网段与 4G 摄像头接入平台的方式局域网调试没什么好说的。跨网段时平台服务器和设备不在同一广播域需要三层路由可达平台服务器上能 ping 通设备ClientDemo 里的 8000 端口测试也通过再开始对接。没有固定公网地址的 4G 摄像头走不了公网直连这一套常见做法是设备主动注册到平台按 GB/T 28181 的 SIP 信令让设备作为下级平台注册上来平台服务器只做被动接入。这种模式下 ClientDemo 的用武之地在现场用笔记本电脑直连摄像头先确认码流、参数、账号没问题再让设备切到 4G 拨号模式看注册状态。还有一类做法是把设备放到录像机后面由录像机做统一出口。平台向上对接录像机海康摄像头只需要被录像机以私有协议或 ONVIF 发现。这类部署里 ClientDemo 调试的是摄像头本身平台侧看到的是录像机的转发流带宽要按最终拉流路数来算而不是按摄像头数量算。4.3 报警布防回调的最小实现报警接入是平台项目里 SDK 不可替代的部分。RTSP 拉流解决不了设备报警消息必须走 SDK 的消息回调。最小布防流程是注册回调、打开布防通道、处理报警类型NET_DVR_SETUPALARM_PARAM alarmParams { 0 }; alarmParams.dwSize sizeof(alarmParams); alarmParams.byLevel 1; // 布防等级按设备能力选择 alarmParams.byAlarmInfoType 1; // 报警信息带扩展类型 LONG alarmHandle -1; if (!NET_DVR_SetupAlarmChan_V41(userId, alarmParams, alarmHandle)) { printf(SetupAlarm failed: %d\n, NET_DVR_GetLastError()); return -1; } NET_DVR_SetDVRMessageCallBack_V50(0, OnAlarmMessage, 0);回调里根据命令字分类再按报警结构体解析具体内容。布防通道在退出时要对应关闭否则下次登录时可能出现报警重复上报。报警回调里的信息结构体比较长解析时要忽略头部的保留字段直接按设备型号对应的结构体版本读取。4.4 调试阶段的安全整改海康设备历史上多次被安全研究团队披露过远程访问漏洞多数利用链路依赖默认密码和未升级固件。ClientDemo 调试阶段要做的最小安全操作有这几项设备侧改掉出厂默认密码网页、8000、554 端口尽量只对平台服务器 IP 开放不需要的远程登录方式直接关掉去官网确认当前固件是否有安全更新。ClientDemo 如果保存过账号密码调试完成后清掉本地配置目录不要把生产设备的账号留在公共电脑上。夜间全彩模式灵敏度偏低、补光灯光强弱这类问题属于设备端图像调优不在 SDK 接入范围内ClientDemo 和能力集里翻不到对应参数直接找设备侧配置。注意平台对接完成后建议把调试用的 ClientDemo 从生产环境卸载或者至少关闭它的自动登录选项避免留下可直达设备的调试后门。5. 用 SDK 日志和抓包验证海康摄像头 ClientDemo 的接入是否干净代码写完了逻辑看起来也对但设备行为不按预期走的时候先用两个手段确认现状打开 SDK 自带日志抓包看信令和码流。这两个手段都不需要改业务代码几分钟就能把问题归位到网络层、SDK 层还是业务层。5.1 打开 SDK 内部日志在NET_DVR_Init之后调用下面的接口SDK 会把每次登录、连接超时、断线重连、取流错误都记录下来// 日志目录必须存在否则写不进去 NET_DVR_SetLogToFile(4, D:/hik_sdk_log, TRUE);第一个参数是日志级别级别越高输出越全调试期给 4正常跑用 2 或 3 即可第二个参数是日志目录Windows 下用绝对路径Linux 下先确认目录可写第三个参数表示是否自动按时间归档传TRUE时日志文件按日期切分避免单个日志文件无限膨胀。打开后 ClientDemo 的界面只显示一个登录结果日志能看到过程比如连接在哪一步超时、重连触发了多少次这些信息比界面提示值钱得多。5.2 抓包和回调计数双重验证调试机上抓与设备交互的全量包tshark -i eth0 -f host 192.168.1.64 and (port 8000 or port 554) \ -w /tmp/client_demo.pcapng -c 5000抓完看三件事TCP 握手是否到达 8000登录成功后有没有持续的心跳包RTSP 的 DESCRIBE 和 SETUP 是否正常返回 200。如果握手都看不到回到第 2 章查网络如果能看到 SYN 但没有回包查防火墙和路由。RTSP 返回码异常时重点查 URL 路径和鉴权格式。除了抓包回调计数是很快的复验手段。写几行统计代码把每秒收到的回调字节数和帧数打出来和主码流设置的码率上限对比volatile unsigned long long g_streamBytes 0; volatile unsigned int g_frames 0; void CALLBACK CountData(LONG lRealHandle, DWORD dwDataType, BYTE *pBuffer, DWORD dwBufSize, void *pUser) { if (dwDataType NET_DVR_STREAMDATA) { g_streamBytes dwBufSize; g_frames; } } // 每秒打印一次 printf(rate%.2f MB/s frames%u\n, g_streamBytes / 1048576.0, g_frames); g_streamBytes 0; g_frames 0;回调里的字节数带封装头和码流设置会有少量偏差。如果统计到的码率明显低于设备配置的码率上限先查网线协商速率和交换机端口是否跑在百兆半双工再确认是不是拉到了子码流上。这两点确认完海康摄像头这块接入链路的问题基本就能归位了。本文还有配套的精品资源点击获取
海康摄像头ClientDemo调试与SDK接入实战指南
简介面向海康摄像头二次开发的工程师这款开箱即用的调试客户端能快速验证视频取流、录像回放、云台控制、报警联动等核心能力节省项目前期的环境搭建成本尤其适合有编程基础、需要先跑通设备再深入定制的场景。压缩包共52个文件以35个动态库和7个静态库为主是接入所需的SDK核心组件另有CHM/PDF格式的接口与使用手册、可直接运行的示例程序、参数配置文件和日志文件整体约37.9MB结构便于按需查找。目前已有3333人学习下载可作为正式开发前的快速参考。内置海康SDK无需单独下载配置开发者可直接登录设备调整实时预览的分辨率、帧率、编码格式测试录像倍速回放、云台预置点巡航、报警联动策略、网络参数设置与用户权限管理并通过完整日志定位对接问题。配套的PDF/CHM文档和Demo覆盖常用接口的调用方式、参数和返回值能帮助把调试验证结果迁移到自有项目中。1. ClientDemo 到底是什么海康摄像头的接入调试绕不开一套叫 ClientDemo 的客户端工具。它是海康威视设备网络 SDK 分发包里附带的可执行示例对外表现是一个能登录设备、看预览、查录像、做云台控制的程序但对做集成的人来说它是「SDK 怎么被正确调用」的最直接证据。很多团队拿到 SDK 后的第一件事是跑 ClientDemo不是拿它当成品用而是给后续的平台接入定一个参照基线网络通不通、账号密码对不对、取流走私有通道还是 RTSP在这个工具上都能先验一遍。下面把 ClientDemo 背后的调用链、参数和排错方法讲透适合正在对接海康摄像头、又不想翻完几百页 API 文档的开发者。2. ClientDemo 能调什么海康摄像头 SDK 调用链与调试边界2.1 先分清 ClientDemo 与 SDK 的关系ClientDemo 是一个按 SDK 接口顺序拼出来的最小客户端不是官方上位机的平替。它的界面布局基本按 API 能力分组本地配置、登录、实时预览、回放、云台、报警、对讲、远程配置。每个按钮背后对应一次或一组 SDK 调用比如点「预览」时程序先通过NET_DVR_Login_V40拿到用户 ID再用NET_DVR_RealPlay_V40申请预览句柄最后注册回调接收码流。这个顺序在文档里是按章节写的在 demo 里是按按钮写的调试时直接看按钮的触发函数就能理清依赖关系。提到调试边界是因为很多人会把 SDK 当成万能层。SDK 的职责到码流回调为止解码、渲染、存储、转封装都是调用方自己处理。预览窗口黑屏但回调数据在涨问题大概率在解码器不在登录与取流。还有一个很容易误判的点海康 4G 监控摄像头在夜间全彩模式下灵敏度偏低这类问题归设备图像策略SDK 层能改的只有码流类型、分辨率和帧率不要试图在 ClientDemo 里找夜间画质参数。出图效果不满足需求时先调整的是设备端补光策略和日夜转换阈值而不是接入代码。2.2 SDK 包目录结构与动态库依赖拿到设备网络 SDK 压缩包后常见做法是先用包里的 ClientDemo 做连通性验证然后才把自己项目的工程文件链到 HCNetSDK 上。Windows 分发包里有HCNetSDK.dll、HCCore.dll、PlayCtrl.dll、AudioRender.dll以及一堆HCNetSDKCom目录下的组件库Linux 分发版则提供libhcnetsdk.so和对应.so依赖。下表列出最容易出问题的几个文件。文件作用缺失或错版本时的现象HCNetSDK.dll / libhcnetsdk.so登录、取流、报警、设备配置等核心接口进程启动时报找不到动态库或登录返回负值HCCore.dll网络传输与线程基础组件初始化失败日志停在 NET_DVR_Init 步骤PlayCtrl.dll本地解码与画面渲染预览窗口黑屏但码流回调有数据AudioRender.dll音频播放与对讲采集对讲无声音、音频设备初始化失败HCNetSDKCom 下的插件库部分加密设备和特殊编码格式登录成功但取流失败或取流后解码异常把这些库放在可执行文件同一目录是最省事的做法。Windows 上不要图方便把 SDK 的 bin 加到系统 PATH多个项目用不同 SDK 版本时PATH 里的版本会先被加载造成错版本加载。Linux 下用LD_LIBRARY_PATH指到 SDK 的 so 目录即可。# Windows 下确认 bin 目录里关键库齐全 dir HCNetSDK*.dll HCCore.dll PlayCtrl.dll 2nul | findstr /i .dll # Linux 下指定 SDK 库目录后启动 ClientDemo export LD_LIBRARY_PATH$PWD/HCNetSDKCom:/opt/hik/libs ./ClientDemo启动后如果立刻报缺少HCNetSDK.dll先确认 SDK 包解压目录层级是否正确。官方压缩包常见一层顶层目录直接解压到桌面有时会把 lib 放到子目录里而 ClientDemo 启动时只会在自己的可执行目录下找库。2.3 登录 ClientDemo 前先验证设备可达ClientDemo 的登录窗口只有 IP、端口、用户名、密码四项很多人填完点登录没反应就先去改代码。实际上多数登录失败在填密码之前就已经定了网络不通。海康设备默认使用 8000 端口做 SDK 信令554 留给 RTSP80 给网页。设备在另一个网段时先确认三层路由可达4G 摄像头拨号后拿到的地址可能定期变化ClientDemo 适合在现场直连环境下调试跨公网调试不如直接看设备注册平台的状态。# 检查目标设备 8000 端口是否在监听 nc -zv 192.168.1.64 8000 -w 3 # 若设备开启了网页服务可通过 HTTP 状态码判断设备存活 curl -s -o /dev/null -w %{http_code}\n http://192.168.1.64/端口通了再登录。如果端口不通先 ping 一下设备ICMP 通但端口不通往往是防火墙策略ICMP 不通就要查 IP 掩码和路由表。这里有一个经验ClientDemo 登录超时的默认表现是转圈十几秒然后弹出失败这时候去看NET_DVR_GetLastError()的返回值比反复改密码有用得多。3. 用 ClientDemo 跑通海康摄像头接入的最小流程3.1 环境准备SDK 位数、运行库与设备版本开始写代码前先把 SDK 版本和编译器位数对齐。海康设备网络 SDK 同时提供 32 位和 64 位库C/C 工程编译成多少位就加载对应位数的动态库。位数不一致时链接阶段能过运行阶段会出现函数指针调用失败或结构体大小不匹配表现是登录返回负值但错误码没有任何明确信息。下表是环境检查清单。检查项建议做法踩坑点编译器位数与 SDK 库位数保持一致混合位数会产生结构体对齐问题SDK 版本用与设备固件发布时间接近的版本旧 SDK 可能不支持新固件的加密登录可执行文件路径把 DLL/SO 放到 exe 同目录依赖 PATH 会出现版本串用设备通道号登录后读取设备信息结构体中的通道字段在界面里写死 0 常导致预览失败IPC 一般只有一个视频通道录像机则有多路通道号从设备信息结构体里的通道起始字段开始按顺序排。ClientDemo 的设备信息栏里能看到通道总数调平台对接时应该读这个字段而不是写死 1 或写死 0。3.2 最小登录代码与错误码判断下面的片段是登录的最小闭环也是 ClientDemo 登录按钮背后实际做的事NET_DVR_Init(); NET_DVR_SetConnectTime(5000, 2); NET_DVR_SetReconnect(10000, TRUE); NET_DVR_USER_LOGIN_INFO loginInfo { 0 }; NET_DVR_DEVICEINFO_V40 deviceInfo { 0 }; strcpy(loginInfo.sDeviceAddress, 192.168.1.64); // 局域网直接填设备 IP loginInfo.wPort 8000; // 设备默认 SDK 端口 strcpy(loginInfo.sUserName, admin); strcpy(loginInfo.sPassword, my_password); LONG userId NET_DVR_Login_V40(loginInfo, deviceInfo); if (userId 0) { printf(NET_DVR_Login_V40 failed: %d\n, NET_DVR_GetLastError()); NET_DVR_Cleanup(); return -1; }NET_DVR_Init只需要调用一次进程结束前调用NET_DVR_Cleanup收尾。每次登录用独立的userId多设备循环登录时不要复用同一个用户 ID。NET_DVR_SetConnectTime第一个参数是单次连接超时毫秒数第二个参数是重试次数平台接入时超时给 3000 到 5000 毫秒比较合适太短容易在弱网下误报离线太长会拖慢故障切换。NET_DVR_SetReconnect是设备断线后 SDK 自动重连的开关参数分别为重连间隔毫秒数和是否启用。GetLastError 返回值含义排查方向7网络不可达或连接超时按前一章步骤检查 8000 端口确认设备未被平台长连接占用9用户名或密码错误在设备网页或 SADP 里重置注意密码大小写和特殊字符其他以 SDK 头文件中 ERROR_ 开头的宏定义为准直接查当前 SDK 版本配套的错误码说明设备被另一个平台长连接占用时也可能出现登录失败这类问题从错误码表面看不出来需要抓包确认连接是被拒绝还是被重置。3.3 实时预览与码流回调的参数设置登录成功后的下一步是申请预览句柄。ClientDemo 的预览按钮把窗口句柄直接传给 SDK让 SDK 自己去渲染平台接入时通常不想要渲染而是把码流交给回调函数做转发或转封装。NET_DVR_PREVIEWINFO previewInfo { 0 }; previewInfo.lChannel 1; // 通道号按设备信息里的起始通道来填 previewInfo.dwStreamType 0; // 0 主码流1 子码流 previewInfo.hPlayWnd NULL; // 平台取流时留空用回调接裸流 LONG previewHandle NET_DVR_RealPlay_V40(userId, previewInfo, NULL, NULL); if (previewHandle 0) { printf(NET_DVR_RealPlay_V40 failed: %d\n, NET_DVR_GetLastError()); return -1; } NET_DVR_SetRealDataCallBack(previewHandle, OnRealData, NULL);回调函数长这样void CALLBACK OnRealData(LONG lRealHandle, DWORD dwDataType, BYTE *pBuffer, DWORD dwBufSize, void *pUser) { if (dwDataType NET_DVR_STREAMDATA) { // 回调里拿到的是封装后的码流需要按 PS 或裸 H.264 解析后交给编码器 // pBuffer 是 SDK 内部缓冲区回调返回后内容会被覆盖必须拷贝 } }hPlayWnd传NULL时 SDK 不做本地渲染只把数据交给回调。平台对接通常用这种方式拿裸流再自己封装成 PS/MP4 或推到流媒体服务。回调里先收到系统头之后才是连续的流数据系统头是解码器初始化的重要前提丢失会导致花屏或解码失败。3.4 从 ClientDemo 迁移到平台时的四个坑ClientDemo 是单机调试思路搬到平台项目里至少有四件事不能照抄。第一句柄释放顺序。退出预览时先调用NET_DVR_StopRealPlay再登出最后NET_DVR_Cleanup反过来会拿到句柄失效的错误。第二自动重连的语义。NET_DVR_SetReconnect只能保证 SDK 内部尝试重连平台侧要额外处理设备状态回调才能感知断线否则平台数据库里的设备状态会一直显示在线。第三回调线程模型。SDK 工作线程负责调用回调不要在回调里直接操作界面控件UI 线程和 SDK 线程互相等会造成假死。第四回调缓冲生命周期。上一次回调里没拷贝缓冲区下一次回调到来时旧数据已经被覆盖许多预览花屏和视频锯齿都是这个原因。注意预览句柄和用户句柄都要做生命周期管理平台侧重连逻辑必须幂等同一路通道不要重复申请预览。4. 从 ClientDemo 到平台接入RTSP 取流、报警布防与安全加固4.1 平台取流优先走 RTSP海康摄像头 rtsp 地址拼法与验证SDK 取流适合需要信令配合的场景比如报警联动录像、云台控制、对讲。平台在做视频接入时很多团队更喜欢让流媒体服务直接通过 RTSP 拉流减少对 SDK 动态库的依赖。海康摄像头的 RTSP 地址格式相对固定rtsp://admin:password192.168.1.64:554/Streaming/Channels/101101代表第一通道的主码流102是同一通道的子码流多通道录像机按201、202递增。用户名密码与登录参数一致。用下面的命令验证地址可拉流ffprobe -rtsp_transport tcp \ -i rtsp://admin:password192.168.1.64:554/Streaming/Channels/101 \ -show_entries streamcodec_name,width,height,avg_frame_rate -of csv能看到编码参数和分辨率就说明地址与鉴权都对。RTSP 方式拿到的流不带海康私有结构直接用 FFmpeg 处理比较方便缺点是报警、云台、设备重启这些信令能力需要另一套通道补偿一般做法是再挂一个 SDK 服务专门处理信令。4.2 跨网段与 4G 摄像头接入平台的方式局域网调试没什么好说的。跨网段时平台服务器和设备不在同一广播域需要三层路由可达平台服务器上能 ping 通设备ClientDemo 里的 8000 端口测试也通过再开始对接。没有固定公网地址的 4G 摄像头走不了公网直连这一套常见做法是设备主动注册到平台按 GB/T 28181 的 SIP 信令让设备作为下级平台注册上来平台服务器只做被动接入。这种模式下 ClientDemo 的用武之地在现场用笔记本电脑直连摄像头先确认码流、参数、账号没问题再让设备切到 4G 拨号模式看注册状态。还有一类做法是把设备放到录像机后面由录像机做统一出口。平台向上对接录像机海康摄像头只需要被录像机以私有协议或 ONVIF 发现。这类部署里 ClientDemo 调试的是摄像头本身平台侧看到的是录像机的转发流带宽要按最终拉流路数来算而不是按摄像头数量算。4.3 报警布防回调的最小实现报警接入是平台项目里 SDK 不可替代的部分。RTSP 拉流解决不了设备报警消息必须走 SDK 的消息回调。最小布防流程是注册回调、打开布防通道、处理报警类型NET_DVR_SETUPALARM_PARAM alarmParams { 0 }; alarmParams.dwSize sizeof(alarmParams); alarmParams.byLevel 1; // 布防等级按设备能力选择 alarmParams.byAlarmInfoType 1; // 报警信息带扩展类型 LONG alarmHandle -1; if (!NET_DVR_SetupAlarmChan_V41(userId, alarmParams, alarmHandle)) { printf(SetupAlarm failed: %d\n, NET_DVR_GetLastError()); return -1; } NET_DVR_SetDVRMessageCallBack_V50(0, OnAlarmMessage, 0);回调里根据命令字分类再按报警结构体解析具体内容。布防通道在退出时要对应关闭否则下次登录时可能出现报警重复上报。报警回调里的信息结构体比较长解析时要忽略头部的保留字段直接按设备型号对应的结构体版本读取。4.4 调试阶段的安全整改海康设备历史上多次被安全研究团队披露过远程访问漏洞多数利用链路依赖默认密码和未升级固件。ClientDemo 调试阶段要做的最小安全操作有这几项设备侧改掉出厂默认密码网页、8000、554 端口尽量只对平台服务器 IP 开放不需要的远程登录方式直接关掉去官网确认当前固件是否有安全更新。ClientDemo 如果保存过账号密码调试完成后清掉本地配置目录不要把生产设备的账号留在公共电脑上。夜间全彩模式灵敏度偏低、补光灯光强弱这类问题属于设备端图像调优不在 SDK 接入范围内ClientDemo 和能力集里翻不到对应参数直接找设备侧配置。注意平台对接完成后建议把调试用的 ClientDemo 从生产环境卸载或者至少关闭它的自动登录选项避免留下可直达设备的调试后门。5. 用 SDK 日志和抓包验证海康摄像头 ClientDemo 的接入是否干净代码写完了逻辑看起来也对但设备行为不按预期走的时候先用两个手段确认现状打开 SDK 自带日志抓包看信令和码流。这两个手段都不需要改业务代码几分钟就能把问题归位到网络层、SDK 层还是业务层。5.1 打开 SDK 内部日志在NET_DVR_Init之后调用下面的接口SDK 会把每次登录、连接超时、断线重连、取流错误都记录下来// 日志目录必须存在否则写不进去 NET_DVR_SetLogToFile(4, D:/hik_sdk_log, TRUE);第一个参数是日志级别级别越高输出越全调试期给 4正常跑用 2 或 3 即可第二个参数是日志目录Windows 下用绝对路径Linux 下先确认目录可写第三个参数表示是否自动按时间归档传TRUE时日志文件按日期切分避免单个日志文件无限膨胀。打开后 ClientDemo 的界面只显示一个登录结果日志能看到过程比如连接在哪一步超时、重连触发了多少次这些信息比界面提示值钱得多。5.2 抓包和回调计数双重验证调试机上抓与设备交互的全量包tshark -i eth0 -f host 192.168.1.64 and (port 8000 or port 554) \ -w /tmp/client_demo.pcapng -c 5000抓完看三件事TCP 握手是否到达 8000登录成功后有没有持续的心跳包RTSP 的 DESCRIBE 和 SETUP 是否正常返回 200。如果握手都看不到回到第 2 章查网络如果能看到 SYN 但没有回包查防火墙和路由。RTSP 返回码异常时重点查 URL 路径和鉴权格式。除了抓包回调计数是很快的复验手段。写几行统计代码把每秒收到的回调字节数和帧数打出来和主码流设置的码率上限对比volatile unsigned long long g_streamBytes 0; volatile unsigned int g_frames 0; void CALLBACK CountData(LONG lRealHandle, DWORD dwDataType, BYTE *pBuffer, DWORD dwBufSize, void *pUser) { if (dwDataType NET_DVR_STREAMDATA) { g_streamBytes dwBufSize; g_frames; } } // 每秒打印一次 printf(rate%.2f MB/s frames%u\n, g_streamBytes / 1048576.0, g_frames); g_streamBytes 0; g_frames 0;回调里的字节数带封装头和码流设置会有少量偏差。如果统计到的码率明显低于设备配置的码率上限先查网线协商速率和交换机端口是否跑在百兆半双工再确认是不是拉到了子码流上。这两点确认完海康摄像头这块接入链路的问题基本就能归位了。本文还有配套的精品资源点击获取
