2024年4月14日发(作者：)
Onvif开发介绍
前言
本文用于指导NVR解决方案中的Onvif开发，介绍Onvif、WSDL、SOAP等基本概
念，讲述开发的流程及各种文件的来源，为后续的开发及维护人员提供理论支持。
写文档的时候，Onvif开发项目正在探究中，文档不可避免地存在纰漏、甚至不对的
地方，希望后续开发及维护人员在获得新的认知、经验后，能不吝更正、完善该文档，使
其能发挥更大的作用。
目录
前言 ............................................................................................................................................................................................. 1
目录 ............................................................................................................................................................................................. 1
第1章 基本概念 ........................................................................................................................................................................ 1
Onvif .................................................................................................................................................................................... 1
Web Service ......................................................................................................................................................................... 2
WSDL .................................................................................................................................................................................. 3
SOAP ................................................................................................................................................................................... 3
gSOAP工具 ........................................................................................................................................................................ 4
第2章 组网框架 ........................................................................................................................................................................ 5
第3章 开发流程 ........................................................................................................................................................................ 6
3.1 获取WSDL文件 ......................................................................................................................................................... 7
3.2 通过gSOAP工具生成C/C++文件 ............................................................................................................................. 8
3.2.1 gSOAP工具说明................................................................................................................................................ 8
3.2.2 使用wsdl2h程序生成头文件 .......................................................................................................................... 9
3.2.3 使用生成源文件 ...................................................................................................................... 11
3.3 开发业务逻辑代码 ..................................................................................................................................................... 12
3.4 编译发布 ..................................................................................................................................................................... 17
第4章 测试工具 ...................................................................................................................................................................... 17
第5章 相关资料 ...................................................................................................................................................................... 19
第1章 基本概念
Onvif
共20页 第1页 基本概念
Onvif开发介绍
Onvif规范描述了网络视频的模型、接口、数据类型以及数据交互的模式，并复用了
一些现有的标准，如WS系列标准等。
规范的目标是实现一个网络视频框架协议，使不同厂商所生产的网络视频产品（包括
摄录前端、录像设备等）完全互通。
规范中设备管理和控制部分所定义的接口均以Web Services的形式提供。Onvif规
范涵盖了完全的XML及WSDL的定义。每一个支持Onvif规范的终端设备均须提供与功
能相应的Web Service。
服务端与客户端的数据交互采用SOAP协议，Onvif中的其他部分比如音视频流则通
过RTP/RTSP进行。
Web Service
Web Service是基于网络的、分布式的模块化组件，执行特定的任务。Web Service 主
要利用 HTTP 和 SOAP 协议使数据在 Web 上传输。Web 用户能够使用 SOAP 和
HTTP通过 Web 调用的方法来调用远程对象。
Web Service能使得运行在不同机器上的不同应用无须借助附加的、专门的第三方软
件或硬件，就可相互交换数据或集成。依据Web Service规范实施的应用之间，无论它们
所使用的语言、平台或内部协议是什么，都可以相互交换数据。
图1-1 Web Service组网
共20页 第2页 基本概念
Onvif开发介绍
WSDL
WSDL是Web Service Description Language(Web Services描述语言)的缩写，是
一个用来描述Web服务和说明如何与Web服务通信的XML语言，为用户提供详细的接
口说明。
SOAP
SOAP是Simple Object Access Protocol（简单对象访问协议）的缩写，是基于XML
的一种协议，被设计成在 WEB 上交换结构化的和固化的信息。
目前的应用程序通过使用远程过程调用（RPC）在诸如 DCOM 与 CORBA 等对象之
间进行通信，但是 HTTP 不是为此设计的。RPC 会产生兼容性以及安全问题；防火墙和
代理服务器通常会阻止此类流量。
通过 HTTP 在应用程序间通信是更好的方法，因为 HTTP 得到了所有的因特网浏览
器及服务器的支持。SOAP 就是被创造出来完成这个任务的。
共20页 第3页 基本概念
Onvif开发介绍
SOAP 提供了一种标准的方法，使得运行在不同的操作系统并使用不同的技术和编程
语言的应用程序可以互相进行通信。
一条 SOAP 消息就是一个普通的 XML 文档，包含下列元素：
必需的 Envelope 元素：可把此 XML 文档标识为一条 SOAP 消息
可选的 Header 元素：包含头部信息
必需的 Body 元素：包含所有的调用和响应信息
可选的 Fault 元素：提供有关在处理此消息所发生错误的信息
在向Web Service发送的SOAP请求中，Body元素中的字段需与WSDL中数据类
型的相符合。在构建SOAP的过程中，必须从WSDL文件中获取并映射这一种对应关系。
然而这样一个对应过程将是充满了重复性和机械性的，为了避免不必要的人工差错以及节
约开发时间，一个名为gSOAP的编译工具应运而生。
gSOAP工具
gSOAP利用编译器技术提供了一组透明化的SOAP API，并将与开发无关的SOAP
实现细节相关的内容对用户隐藏起来，通过将WSDL文件解析序列化为C/C++文件，最
小化了Web Service的开发过程。
几个概念的关系：
共20页 第4页 基本概念
Onvif开发介绍
Onvif开发的目的是为了实现一个网络视频框架协议，使不同厂商所生产的网络视频
产品完全互通，而不同厂商可能会使用不同的平台、语言、内部协议来实现自己的网络视
频产品，如何实现彼此间的互通及避免重复开发呢？
Web Service就是一种忽略平台、语言的技术。它使用 SOAP 和 HTTP通过 Web 调
用的方法来调用远程对象。这样，只要实现了Web Service，并且将功能集暴露出来，对
端就可以通过远程调用对象的方式达成互通的目的，就像调用本地函数一样。
即使是调用本地函数，仍然需要知道函数名是什么，参数有哪些，参数类型是怎么样
的。WSDL就描述了这些内容。相同的WSDL就能够保证了数据描述的一致性。
光是数据描述一致还不能实现远程调用，需要SOAP来提供通道。
没有gSOAP工具也可以实现Onvif开发的目标，但是需要写代码来解析WSDL文件，
需要考虑的问题很多，重复性和机械性工作也很多。与其将时间跟精力花在解析WSDL文
件上面，不如使用gSOAP工具来生成框架代码，将时间跟精力聚焦在业务上的实现。
第2章 组网框架
图2-1是NVR的组网示意图，其中标红的地方是Onvif相关的模块，也就是本文所
要介绍的开发模块。
图2-1 NVR组网
共20页 第5页 组网框架
Onvif开发介绍
IPC
NVR
App
App
Adapter
Onvif SBC S
LogManTaskManDiskManPTZ
…
App
Network Adapter
Onvif C
BC C
App
Adapter
Onvif SBC S
Onvif S
Onvif C
BC S
BC C
Network Adapter
PC
说明：
1、 Onvif S表示使用Onvif协议，充当的是Server角色；BC S表示使用百川内部
协议，充当的是Server角色；Onvif C表示使用Onvif协议，充当Client角色；BC C表
示使用百川内部协议，充当Client协议。
2、 重点关注Onvif相关的部分，其他的模块的关系与数据交换只需要意会即可，不
必深入研究。
第3章 开发流程
总体开发流程如图3-1所示。工作的重点在于业务逻辑开发，但如果不了解各流程的
来龙去脉，在看到一些工具生成的文件时，将会感觉到迷惑。
图3-1 Onvif开发的流程
共20页 第6页 开发流程
Onvif开发介绍
3.1 获取WSDL文件
如果每个厂商都定义自己的WSDL文件，则Onvif只能做到方便跟别的厂商对接；要
实现各厂商产品的完全互通，WSDL文件必须是统一的。幸运的是，Onvif组织提供了这
样的WSDL文件，地址在下面网页的“ONVIF WSDL and XML Schemas
Specifications”节下。
/Documents/
获得的WSDL文件如图3-2所示，感兴趣的可看一下WSDL文件的内容，这里不展
开。
图3-2 获取的WSDL文件
共20页 第7页 开发流程
Onvif开发介绍
3.2 通过gSOAP工具生成C/C++文件
3.2.1 gSOAP工具说明
gSOAP工具是开源的，在网上搜索一下就能获得该工具及源码。下面以gSOAP2.8
为例进行说明。
从网上下载gSOAP工具，解压后得到的文件列表如图3-3所示。
图3-3 gSoap2.8文件列表
共20页 第8页 开发流程
Onvif开发介绍
说明文档及源代码有必要的时候可以查看下，我们现在只关注工具的应用。在
gsoapbin目录下，看到gSOAP工具可在Linux、Macosx和Windows操作系统下运
行。
图3-4 bin目录文件列表
下面以Windows系统的gSOAP工具的使用进行说明。
在win32目录下，有和这两个文件。是根据
wsdl文件生成C/C++的头文件；而则是根据该头文件来生成C/C++的框
架源码。
在doc窗口里面，进入到 gsoapbinwin32目录，敲wsdl2h /?或者soapcpp2 /?
可查看两个应用程序的详细用法。
3.2.2 使用wsdl2h程序生成头文件
在使用wsdl2h生成头文件前需要修改。
修改的依据在这里：/~engelen/，在FAQ页面下
的How do I use gSOAP for the ONVIF specifications?
共20页 第9页 开发流程
Onvif开发介绍
当然，此文件不必每次都修改，我们知道归档的文件跟gSOAP自带的文件不同的原
因即可。如图3-5所示，右边是修改后的文件，只贴出来部分。
图3-5 修改前后的
拿远程设备发现举例。
首先打开dos窗口，进入到所在目录。
如果设备发现的wsdl文件在网上，则生成头文件的命令为：
wsdl2h -o onvif.h -c -s -t .
/onvif/ver10/network/wsdl/
如果文件已经下载下来，并且放在相同的目录中，
则对应的命令为：
wsdl2h -o onvif.h -c -s -t .
命令执行成功后，将生成一个onvif.h文件。
共20页 第10页 开发流程
Onvif开发介绍
如果要生成多个WSDL文件共同的头文件，则在上面的命令后面加WSDL文件名，
中间以空格分开即可。Onvif有15个WSDL文件，文件中又导入了其他的文件，如果都
从网上直接下载，则需要很长时间，导致失败。如果将所有的文件的都下载下来，并且修
改文件的导入目录，则生成头文件的时间会大大减少。在实际操作过程中，正是将所有文
件下载到本地的。
3.2.3 使用生成源文件
保持gSOAP的目录结构不变，使用soapcpp2应用程序，要包含图3-6所圈红的目
录gsoap和import。
打开dos窗口，进入到所在目录，使用上小节生成的onvif.h文件，
执行的命令如下：
soapcpp2 -c onvif.h -x -I ../../import -I ../../
执行完命令后，生成的文件如图3-7所示。其中，3个nsmap文件是相同的，只需要
文件即可。生成的文件再加上gSOAP自带的两个文件stdsoap2.c和
stdsoap2.h，共同构成了Onvif的框架代码。
图3-6 soapcpp2依赖的目录
共20页 第11页 开发流程
Onvif开发介绍
图3-7 soapcpp2生成的文件
3.3 开发业务逻辑代码
在上节中，已经使用gSOAP工具生成了Onvif的框架代码，明确了互通相关的数据
结构及动作名称。我们要做的事就是怎么实现这些动作，如往数据结构里填写什么数据发
给对端，从对端收到的数据如何提交给应用处理。
共20页 第12页 开发流程
Onvif开发介绍
拿开发NVR侧的Onvif server端的设备发现功能举例。打开soapStub.h文件，可
看到有如下的代码。这些就是Onvif server端开放的接口，仅仅是一个声明，需要我们去
实现具体的功能。
/******************************************************************************
* Server-Side Operations
*
******************************************************************************/
SOAP_FMAC5 int SOAP_FMAC6 __wsdd__Hello(struct soap*, struct
wsdd__HelloType *wsdd__Hello);
SOAP_FMAC5 int SOAP_FMAC6 __wsdd__Bye(struct soap*, struct
wsdd__ByeType *wsdd__Bye);
SOAP_FMAC5 int SOAP_FMAC6 __wsdd__Probe(struct soap*, struct
wsdd__ProbeType *wsdd__Probe);
SOAP_FMAC5 int SOAP_FMAC6 __wsdd__ProbeMatches(struct soap*, struct
wsdd__ProbeMatchesType *wsdd__ProbeMatches);
SOAP_FMAC5 int SOAP_FMAC6 __wsdd__Resolve(struct soap*, struct
wsdd__ResolveType *wsdd__Resolve);
共20页 第13页 开发流程
Onvif开发介绍
SOAP_FMAC5 int SOAP_FMAC6 __wsdd__ResolveMatches(struct soap*, struct
wsdd__ResolveMatchesType *wsdd__ResolveMatches);
SOAP_FMAC5 int SOAP_FMAC6 __ns1__Hello(struct soap*, struct
wsdd__HelloType tdn__Hello, struct wsdd__ResolveType *tdn__HelloResponse);
SOAP_FMAC5 int SOAP_FMAC6 __ns1__Bye(struct soap*, struct
wsdd__ByeType tdn__Bye, struct wsdd__ResolveType *tdn__ByeResponse);
SOAP_FMAC5 int SOAP_FMAC6 __ns2__Probe(struct soap*, struct
wsdd__ProbeType tdn__Probe, struct wsdd__ProbeMatchesType
*tdn__ProbeResponse);
如实现其中的一个函数__wsdd__Probe，不必关注代码的逻辑，只需要知道这种形式
即可，也就是前面按照格式申请内存，中间填充内容，后面将内容发送出去的这种形式。
int __wsdd__Probe(struct soap* soap, struct wsdd__ProbeType
*wsdd__Probe)
{
char macaddr[6] = {0};
char _IPAddr[INFO_LENGTH] = {0};
char _HwId[1024] = {0};
共20页 第14页 开发流程
Onvif开发介绍
wsdd__ProbeMatchesType ProbeMatches;
atch = (struct wsdd__ProbeMatchType
*)soap_malloc(soap,
sizeof(struct wsdd__ProbeMatchType));
atch->XAddrs = (char *)soap_malloc(soap, sizeof(char)
* INFO_LENGTH);
atch->Types = (char *)soap_malloc(soap, sizeof(char) *
INFO_LENGTH);
…………
sprintf(_HwId,"urn:uuid:2419d68a-2dd2-21b2-a205-");
sprintf(_IPAddr, "%03d.%03d.%1d.%03d/onvif/device_service", 192, 168,
2, 146);
ProbeMatches.__sizeProbeMatch = 1;
atch->Scopes->__item =(char *)soap_malloc(soap,
1024);
memset(atch->Scopes->__item,0,
共20页 第15页 开发流程
Onvif开发介绍
sizeof(atch->Scopes->__item));
//Scopes MUST BE
strcat(atch->Scopes->__item,
"onvif:///type/NetworkVideoTransmitter");
atch->Scopes->MatchBy = NULL;
strcpy(atch->XAddrs, _IPAddr);
strcpy(atch->Types, wsdd__Probe->Types);
DBG("wsdd__Probe->Types=%sn",wsdd__Probe->Types);
atch->MetadataVersion = 1;
//ws-discovery规定 为可选项
atch->wsa__nceProperties->
__size = 0;
atch->wsa__nceProperties->
__any = NULL;
atch->wsa__nceParameters-
共20页 第16页 开发流程
Onvif开发介绍
>__size = 0;
atch->wsa__nceParameters-
>__any = NULL;
…………
/* send over current socket as HTTP OK response: */
soap_send___wsdd__ProbeMatches(soap, "", NULL, &ProbeMatches);
return SOAP_OK;
}
3.4 编译发布
Onvif相关代码在系统内都是增量开发，编译时遵循各种系统原来的规则即可，无特
殊要求。
第4章 测试工具
使用Onvif测试工具“ONVIF Conformance Test”可验证所实现的Onvif协议是否
符合规范。本文介绍的Onvif测试工具版本是V1.02.4。安装包里的文件如图4-1所示。
图4-1 Onvif测试工具安装包
共20页 第17页 测试工具
Onvif开发介绍
单击，默认安装即可。启动测试工具，显示主界面如图4-2所示。
图4-2 Onvif测试工具主界面
单击Test标签页，可看到测试工具里面的内容包含了IP配置、设备发现、设备管理、
媒体配置等Onvif协议功能项，如图4-3所示。
图4-3 Onvif测试工具的测试项
共20页 第18页 测试工具
Onvif开发介绍
工具的详细使用方法请参看工具的帮助（通过菜单Help > How do I…调出）。帮助文
档如图4-4所示。
图4-4 Onvif测试工具的帮助
第5章 相关资料
共20页 第19页 相关资料
Onvif开发介绍
Onvif组织的官网：
/
Web service介绍：
/view/
WSDL文件详解：
/libin2722/articles/
Onvif规范实现实例（共5篇）：
/ghostyu/article/details/8162193
/ghostyu/article/details/8162280
/ghostyu/article/details/8182516
/ghostyu/article/details/8208428
/ghostyu/article/details/8432760
共20页 第20页 相关资料
发布评论