大华网络SDK编程手册VERSION 3.1.8(Build 070321)
2007-3-21
版权所有侵权必究
前言
非常感谢您使用我们公司的设备，我们将为您提供最好的服务。
本手册可能包含技术上不准确的地方或印刷错误，欢迎指正。我们将会定期更新手册的内容。
修订记录
目录
1 简介 (7)
1.1概述 (7)
1.2适用性 (7)
1.3特色功能 (7)
2 设计原则 (9)
2.1编程说明 (9)
2.2典型调用顺序 (10)
3 数据结构定义 (13)
3.1客户端数据结构 (13)
3.1.1 设备信息结构 (16)
3.1.2 时间信息 (17)
3.1.3 录像文件信息 (17)
3.1.4 设备状态信息 (17)
3.1.5 系统配置信息结构 (22)
4 接口定义 (22)
4.1SDK初始化 (22)
4.2状态侦听 (24)
4.3字符叠加 (26)
4.4设备注册 (27)
4.5实时监视 (29)
4.6音频控制 (32)
4.7数据保存 (33)
4.8视频抓图 (36)
4.9回放和下载 (37)
4.10回放控制 (47)
4.11云台控制 (50)
4.12实时预览 (52)
4.13系统配置 (53)
4.14日志管理 (57)
4.15透明串口 (59)
4.16远程控制 (61)
4.17录像控制 (62)
4.18系统时间 (63)
4.19用户管理 (64)
4.20语音对讲 (66)
4.21码流统计 (71)
4.22IO控制 (72)
4.23强制I帧 (73)
4.24设置限流 (73)
4.25获取设备状态 (74)
4.26修改通道名称 (75)
4.27DDNS查询IP (75)
4.28设备参数配置 (76)
5 示例功能实现 (90)
5.1连接设备 (90)
5.2报警信息获取 (90)
5.3系统配置 (91)
5.4实时监视 (91)
5.5数据保存 (91)
5.6回放/下载和进度指示 (92)
5.7播放控制 (92)
5.8预览 (92)
5.9字符叠加 (92)
1简介
1.1概述
欢迎使用大华网络SDK编程手册，网络客户端软件开发包（DVR客户端SDK）是大华网络硬盘录像机、网络视频服务器的配套产品，本文档详细描述了开发包中各个函数实现的功能、接口及其函数之间的调用关系和示例实现。
网络客户端软件开发包主要包括业务操作和设备管理两大部分：
业务操作：状态侦听、实时监视、实时预览、字符叠加、音频控制、录像回放和下载、数据保存、云台控制、语音对讲、透明串口、码流统计等功能。
设备管理：远程升级、远程重启/关闭、设备参数配置（系统通用配置、报警布/撤防设置、录像配置、串口配置、图像配置、日志管理、用户管理、设备校
时、动态检测配置、网络配置）等功能。
开发包所包括的文件有：
网络库：dhnetsdk.lib、dhnetsdk.dll、dhnetsdk.h
解码库：decode.dll、render.dll、dllh264.dll、audiorecord.dll、AudioRecordEx.dll、avcodec.dll
辅助库：dhdvr.dll、ParaTimer.dll、DetectAreaCtrl.ocx、SetDeviceConfigProj.ocx
1.2适用性
?支持所有大华网络硬盘录像机（DVR）、网络视频服务器（NVS）、网络报警
服务器（NAS）
?只支持TCP网络传输模式
?客户端可以采用多种分辨率进行图像预览，支持的分辨率包括：QCIF、CIF、
2CIF、、HalfD1、D1，VGA（640×480）等
?客户端支持多种图像编码，包括MPEG4和H.264等
1.3特色功能
支持设备的以下特色功能：
?多路预览
在窄带条件下，同时多路实时监视对带宽的要求比较高，一般的处理情况有两种，其一，轮巡。其二，多路预览。所谓多路预览，就是在一个通道上把所有通道的数据组织在一起传输，等同于多路同时监视。必要的时候，可以转单路监视。大华DVR 支持多路预览功能。
?支持标准的MP4数据
一般情况下，同一平台集成不同厂商的前端设备（如DVR），由于各厂商采用的视频压缩方法不同(包括算法、参数定义等)，导致解码端回放必须采用厂商特定的工
具，造成平台开发商无法自定义播放标准。本SDK能够解决这个问题。通过特定接口，应用层可以通过本SDK获取标准媒体数据（FOURCC(‘D’、‘I’、‘V’、‘X’)视频数据），要支持用各种通用播放器播放，有了提供标准数据，应用层只须打包标准数据到播放器支持的容器类型(也就是文件格式,如A VI标准)就可以了。
2设计原则
2.1编程说明
?初始化和清除
1、使用网络客户端软件包首先调用CLIENT_Init()对系统进行初始化，应用程序
退出时调用CLIENT_Cleanup()释放所有占用的资源。
2、大多数函数调用均应该在CLIENT_Init()之后，CLIENT_Cleanup()之前，除了
少数函数，譬如CLIENT_SetConnectTime()在CLIENT_Init()之前调用，而
CLIENT_GetSDKVersion()可以在任何时候调用等等。
?操作句柄
系统设计上多处使用了句柄概念，很多操作均针对句柄，如回放、下载以及语音对讲等。
?用户登录和注销
用户在访问前端设备之前必须通过调用CLIENT_Login ()登录到前端设备上，登录成功后返回一个全局唯一的句柄。此句柄就像一个会话通道，之后该用户可通过此句柄访问前端设备。退出该会话时则通过CLIENT_Logout ()函数在前端设备上注销此句柄以终止该会话通道的使用。建立连接与登录是同步的。
?心跳功能
在本开发包中提供自动心跳功能（20秒一次心跳）当设备断开能及时回调给客户端。
?同步与异步
异步以设置回调函数来响应网络数据，有些异步在设置后返回请求句柄，结束请求时将请求句柄提供给SDK以注销相关资源。
?SDK提供协议探测和转换
?回调函数
一般都有dwUser参数, 由用户自定义需要的数据, 一般用来传入类对象指针,
方便回调处理在类中实现,回调应用都可以采取这种方式。
2.2典型调用顺序
A.初始化
B.SDK功能设置或信息获取
C.登录连接设备
D.设备功能操作与信息获取
E.实时监视通道
F.多画面预览通道
G.回放/下载通道
H.针对显示图像的操作(监视/回放/多画面预览)
I.远程控制
J.注销断开设备
K.释放SDK资源
对D、E、F、G、H、I中的功能大部分之间没有调用先后顺序,当然对同一个功能还是应该按先打开再操作最后关闭的顺序。
3数据结构定义
3.1客户端数据结构
?通用云台控制命令
typedef enum _PTZ_ControlType
{
PTZ_UP_CONTROL = 0, //上
PTZ_DOWN_CONTROL, //下
PTZ_LEFT_CONTROL, //左
PTZ_RIGHT_CONTROL, //右
PTZ_ZOOM_ADD_CONTROL, //变倍+
PTZ_ZOOM_DEC_CONTROL, //变倍-
PTZ_FOCUS_ADD_CONTROL, //调焦+
PTZ_FOCUS_DEC_CONTROL, //调焦-
PTZ_APERTURE_ADD_CONTROL, //光圈+
PTZ_APERTURE_DEC_CONTROL, //光圈-
PTZ_POINT_MOVE_CONTROL, //转至预置点
PTZ_POINT_SET_CONTROL, //设置
PTZ_POINT_DEL_CONTROL, //删除
PTZ_POINT_LOOP_CONTROL, //点间轮循
PTZ_LAMP_CONTROL, //灯光雨刷
}PTZ_ControlType;
?云台控制扩展命令
typedef enum _EXTPTZ_ControlType{
EXTPTZ_LEFTTOP = 0X20, // 左上
EXTPTZ_RIGHTTOP , // 右上
EXTPTZ_LEFTDOWN , // 左下
EXTPTZ_RIGHTDOWN, // 右下
EXTPTZ_ADDTOLOOP, // 加入预置点到巡航巡航线路预置点值EXTPTZ_DELFROMLOOP, // 删除巡航中预置点巡航线路预置点值 EXTPTZ_CLOSELOOP, // 清除巡航巡航线路
EXTPTZ_STARTPANCRUISE, // 开始水平旋转
EXTPTZ_STOPPANCRUISE, // 停止水平旋转
EXTPTZ_SETLEFTBORDER, // 设置左边界
EXTPTZ_RIGHTBORDER , // 设置右边界
EXTPTZ_STARTLINESCAN, // 开始线扫
EXTPTZ_CLOSELINESCAN, // 停止线扫
EXTPTZ_SETMODESTART, // 设置模式开始模式线路
EXTPTZ_SETMODESTOP, // 设置模式结束模式线路EXTPTZ_RUNMODE, // 运行模式模式线路
EXTPTZ_STOPMODE, // 停止模式模式线路
EXTPTZ_DELETEMODE, // 清除模式模式线路
EXTPTZ_REVERSECOMM, // 翻转命令
EXTPTZ_FASTGOTO, // 快速定位水平坐标垂直坐标变倍EXTPTZ_AUXIOPEN, // x34 辅助开关开辅助点
EXTPTZ_AUXICLOSE, // 0x35辅助开关关辅助点
EXTPTZ_OPENMENU = 0X36, // 打开球机菜单
EXTPTZ_CLOSEMENU , // 关闭菜单
EXTPTZ_MENUOK, //菜单确定
EXTPTZ_MENUCANCEL, //菜单取消
EXTPTZ_MENUUP, //菜单上
EXTPTZ_MENUDOWN, //菜单下
EXTPTZ_MENULEFT, //菜单左
EXTPTZ_MENURIGHT, //菜单右
EXTPTZ_TOTAL, //最大命令值
}EXTPTZ_ControlType;
?I O控制命令
typedef enum _IOTYPE{
ALARMINPUT = 1, //报警输入
ALARMOUTPUT = 2, //报警输出
}IOTYPE;
?查询状态类型
#define DH_DEVSTATE_COMM_ALARM 0x0001 //查询普通报警
#define DH_DEVSTATE_SHELTER_ALARM 0x0002 //查询遮挡报警
#define DH_DEVSTATE_RECORDING 0x0003 //查询录象状态
#define DH_DEVSTATE_DISK 0x0004 //查询硬盘状态
?错误类型代号，用于GetLastError函数的返回
#define _EC(x) (0x80000000|x)
#define NET_NOERROR 0//没有错误
#define NET_ERROR -1//未知错误
#define NET_SYSTEM_ERROR _EC(1) //Windows系统出错
#define NET_NETWORK_ERROR _EC(2)//网络错误
#define NET_DEV_VER_NOMATCH _EC(3)//设备协议不匹配
#define NET_INVALID_HANDLE _EC(4)//句柄无效
#define NET_OPEN_CHANNEL_ERROR _EC(5)//打开通道失败
#define NET_CLOSE_CHANNEL_ERROR _EC(6)//关闭通道失败
#define NET_ILLEGAL_PARAM _EC(7)//用户参数不合法
#define NET_SDK_INIT_ERROR _EC(8)//SDK初始化出错
#define NET_SDK_UNINIT_ERROR _EC(9)//SDK清理出错
#define NET_RENDER_OPEN_ERROR _EC(10)//申请render资源出错
#define NET_DEC_OPEN_ERROR _EC(11)//打开解码库出错
#define NET_DEC_CLOSE_ERROR _EC(12)//关闭解码库出错
#define NET_MULTIPLAY_NOCHANNEL _EC(13)//多画面预览中检测到通道数为0 #define NET_TALK_INIT_ERROR _EC(14)//录音库初始化失败
#define NET_TALK_NOT_INIT _EC(15)//录音库未经初始化
#define NET_TALK_SENDDATA_ERROR _EC(16)//发送音频数据出错
#define NET_REAL_ALREADY_SAVING _EC(17)//实时数据已经处于保存状态
#define NET_NOT_SAVING _EC(18)//未保存实时数据
#define NET_OPEN_FILE_ERROR _EC(19)//打开文件出错
#define NET_PTZ_SET_TIMER_ERROR _EC(20)//启动云台控制定时器失败
#define NET_RETURN_DATA_ERROR _EC(21)//对返回数据的校验出错
#define NET_INSUFFICIENT_BUFFER _EC(22)//没有足够的缓存
#define NET_NOT_SUPPORTED _EC(23)//当前SDK未支持该功能
#define NET_NO_RECORD_FOUND _EC(24)//查询不到录象
#define NET_NOT_AUTHORIZED _EC(25)//无操作权限
#define NET_NOT_NOW _EC(26)//暂时无法执行
#define NET_NO_TALK_CHANNEL _EC(27)//未发现对讲通道
#define NET_NO_AUDIO _EC(28)//未发现音频
#define NET_AUDIOENCODE_NOTINI _EC(59)//音频编码接口没有成功初始化
#define NET_DATA_TOOLONGH _EC(60)//数据过长
#define NET_LOGIN_ERROR_PASSWORD _EC(100)//密码不正确
#define NET_LOGIN_ERROR_USER _EC(101)//帐户不存在
#define NET_LOGIN_ERROR_TIMEOUT _EC(102)//等待登录返回超时
#define NET_LOGIN_ERROR_RELOGGIN _EC(103)//帐号已登录
#define NET_LOGIN_ERROR_LOCKED _EC(104)//帐号已被锁定
#define NET_LOGIN_ERROR_BLACKLIST _EC(105)//帐号已被列为黑名单
#define NET_LOGIN_ERROR_BUSY _EC(106)//资源不足，系统忙
#define NET_LOGIN_ERROR_CONNECT _EC(107)//连接主机失败"
#define NET_LOGIN_ERROR_NETWORK _EC(108)//网络连接失败"
#define NET_RENDER_SOUND_ON_ERROR _EC(120)//Render库打开音频出错
#define NET_RENDER_SOUND_OFF_ERROR _EC(121)//Render库关闭音频出错
#define NET_RENDER_SET_VOLUME_ERROR _EC(122)//Render库控制音量出错
#define NET_RENDER_ADJUST_ERROR _EC(123)//Render库设置画面参数出错
#define NET_RENDER_PAUSE_ERROR _EC(124)//Render库暂停播放出错
#define NET_RENDER_SNAP_ERROR _EC(125)//Render库抓图出错
#define NET_RENDER_STEP_ERROR _EC(126)//Render库步进出错
#define NET_RENDER_FRAMERATE_ERROR _EC(127)//Render库设置帧率出错#define NET_CONFIG_DEVBUSY _EC(999)//暂时无法设置
#define NET_CONFIG_DATAILLEGAL _EC(1000) //配置数据不合法
?回调函数类型
#define COMM_ALARM 0x1100 //常规报警信息
#define SHELTER_ALARM 0x1101//视频遮挡报警
#define DISK_FULL_ALARM 0X1102//硬盘满报警
#define DISK_ERROR_ALARM 0x1103//硬盘故障报警
#define SOUND_DETECT_ALARM 0x1104//音频检测报警
?设备型号(DVR类型)
enum NET_DEVICE_TYPE {
NET_PRODUCT_NONE = 0,
NET_DVR_NONREALTIME_MACE, // 非实时MACE
NET_DVR_NONREALTIME, // 非实时
NET_NVS_MPEG1, // 网络视频服务器
NET_DVR_MPEG1_2, // MPEG1二路录像机
NET_DVR_MPEG1_8, // MPEG1八路录像机
NET_DVR_MPEG4_8, // MPEG4八路录像机
NET_DVR_MPEG4_16, // MPEG4十六路录像机
NET_DVR_MPEG4_SX2, // MPEG4视新十六路录像机
NET_DVR_MEPG4_ST2, // MPEG4视通录像机
NET_DVR_MEPG4_SH2, // MPEG4视豪录像机
NET_DVR_MPEG4_GBE, // MPEG4视通二代增强型录像机
NET_DVR_MPEG4_NVSII, // MPEG4网络视频服务器II代
NET_DVR_STD_NEW, // 新标准配置协议
NET_DVR_DDNS, // DDNS服务器
};
3.1.1设备信息结构
?设备结构定义如下
typedef struct {
BYTE sSerialNumber[SERIALNO_LEN]; //序列号
BYTE byAlarmInPortNum; //DVR报警输入个数
BYTE byAlarmOutPortNum; //DVR报警输出个数
BYTE byDiskNum; //DVR硬盘个数
BYTE byDVRType; //DVR类型,
BYTE byChanNum; //DVR通道个数
} NET_DEVICEINFO, *LPNET_DEVICEINFO;
3.1.2时间信息
typedef struct {
DWORD dwYear; //年
DWORD dwMonth; //月
DWORD dwDay; //日
DWORD dwHour;//时
DWORD dwMinute; //分
DWORD dwSecond; //秒
} NET_TIME,*LPNET_TIME;
3.1.3录像文件信息
typedef struct {
unsigned int ch; //通道号
char filename[128]; //文件名
unsigned int size; //文件长度
NET_TIME starttime; //开始时间
NET_TIME endtime; //结束时间
unsigned int driveno; //磁盘号
unsigned int startcluster; //起始簇号
} NET_RECORDFILE_INFO, *LPNET_RECORDFILE_INFO;
3.1.4设备状态信息
设备端通过回调主动上传的设备状态结构
typedef struct {
int channelcount;
int alarminputcount;
unsigned char diskerror[MAX_DISKNUM];
unsigned char *record; //size:channelcount
unsigned char *alarm; //size:alarminputcount unsigned char *motiondection;//size:channelcount
unsigned char *videolost; //size:channelcount
} NET_CLIENT_STATE;
typedef struct {
BYTE byRecordStatic; //通道是否在录像,0-不录像,1-录像
BYTE bySignalStatic; //连接的信号状态,0-正常,1-信号丢失
BYTE byHardwareStatic; //通道硬件状态,0-正常,1-异常,例如DSP死掉char reserve;//暂时无效
DWORD dwBitRate; //实际码率,暂时无效
DWORD dwLinkNum; //客户端连接的个数, 暂时无效
DWORD dwClientIP[MAX_LINK]; //客户端的IP地址,暂时无效
}NET_DEV_CHANNELSTATE,*LPNET_DEV_CHANNELSTATE;
typedef struct {
DWORD dwVolume; //硬盘的容量
DWORD dwFreeSpace; //硬盘的剩余空间
DWORD dwStatus; //硬盘的状态,休眠,活动,不正常等
}NET_DEV_DISKSTATE,*LPNET_DEV_DISKSTATE;
typedef struct{
DWORD dwDeviceStatic; //设备状态0x00 正常,0x01 CPU占用过高, 0x02 硬件错误NET_DEV_DISKSTATE stHardDiskStatic[MAX_DISKNUM]; //设备暂时不支持
NET_DEV_CHANNELSTATE stChanStatic[MAX_CHANNUM]; //通道的状态
BYTE byAlarmInStatic[MAX_ALARMIN]; //报警端口的状态0-无报警,1-有报警
BYTE byAlarmOutStatic[MAX_ALARMOUT];//报警输出端口的状态0-无输出,1-有输出DWORD dwLocalDisplay; //本地显示状态0-正常,1-不正常
}NET_DEV_WORKSTATE,*LPNET_DEV_WORKSTATE;
?录像文件信息
typedef struct {
unsigned int ch; //通道号
char filename[128]; //文件名
unsigned int size; //文件长度
NET_TIME starttime; //开始时间
NET_TIME endtime; //结束时间
unsigned int driveno; //磁盘号
unsigned int startcluster; //起始簇号
} NET_RECORDFILE_INFO, *LPNET_RECORDFILE_INFO;
typedef struct {
char protocolname[12]; //协议名unsigned int baudbase; //波特率unsigned char databits; //数据位unsigned char stopbits; //停止位unsigned char parity; //校验位unsigned char reserve;
} PROTOCOL_INFO, *LPPROTOCOL_INFO;
?报警IO控制(报警输出和报警输入使能)
typedef struct {
unsigned short index; //端口序号unsigned short state; //端口状态}ALARM_CONTROL;
?用户管理功能数据结构
#define MAX_RIGHT_NUM 100
#define MAX_GROUP_NUM 20
#define MAX_USER_NUM 200
#define RIGHT_NAME_LENGTH 32
#define USER_NAME_LENGTH 8
#define USER_PSW_LENGTH 8
#define MEMO_LENGTH 32
typedef struct {
DWORD dwID;
char name[RIGHT_NAME_LENGTH];
char memo[MEMO_LENGTH];
}OPR_RIGHT;
typedef struct {
DWORD dwID;
DWORD dwGroupID;
char name[USER_NAME_LENGTH];
char passWord[USER_PSW_LENGTH];
DWORD dwRightNum;
DWORD rights[MAX_RIGHT_NUM];
char memo[MEMO_LENGTH];
}USER_INFO;
typedef struct {
DWORD dwID;
char name[USER_NAME_LENGTH];
DWORD dwRightNum;
DWORD rights[MAX_RIGHT_NUM];
char memo[MEMO_LENGTH];
}USER_GROUP_INFO;
?S DK返回的用户信息结构
typedef struct {
DWORD dwRightNum;
OPR_RIGHT rightList[MAX_RIGHT_NUM];
DWORD dwGroupNum;
USER_GROUP_INFO groupList[MAX_GROUP_NUM];
DWORD dwUserNum;
USER_INFO userList[MAX_USER_NUM];
}USER_MANAGE_INFO;
?日志信息
1. 日志的结构形式
//时间结构
typedef struct _DHTIME
{
DWORD second :6; // 秒1-60
DWORD minute :6; // 分1-60
DWORD hour :5; // 时1-24
DWORD day :5; // 日1-31
DWORD month :4; // 月1-12
DWORD year :6; // 年2000-2063
}DHTIME,*pDHTIME;
//日志结构
struct LOG_ITEM
{
DHTIME time; //日期
接口文档数字视频录像机网络服务编程手册公开WORD type; //类型
BYTE flag; //标记, 0x00 正常，0x01 扩展，0x02 数据BYTE data; //数据
BYTE context[8]; //内容
};