Onvif协议开发

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

序

ONVIF协议致力于通过全球性的开放接口标准来推进网络视频在安防市场的应用，这一接口标准将确保不同厂商生产的网络视频产品具有互通性。2008年11月，论坛正式发布了ONVIF协议第一版规范——ONVIF协议核心规范Onvif协议 1.0版， 后续又推出Onvif协议 2.0版本。随着视频监控的网络化应用，产业链的分工将越来越细。有些厂商专门做网络摄像机，有些厂商专门做DVS，有些厂商则可能专门做平台等，然后通过集成商进行集成，提供给最终客户。这种产业合作模式，已经迫切的需要行业提供越来越标准化的接口平台。本文用于指导NVR及软件平台解决方案中的Onvif协议对接，详细介绍了Onvif协议、WSDL、SOAP等基本概念，讲述开发的流程及各种文件的来源，为开发及维护人员提供理论支持。

共15页 第1页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

目录

序 ......................................................................................................................................................... 1

目录 ..................................................................................................................................................... 2

第1章 基本概念 ............................................................................................................................... 3

Onvif协议协议规范 .................................................................................................................. 3

Web Service ................................................................................................................................ 3

WSDL ......................................................................................................................................... 4

4

gSOAP工具 ............................................................................................................................... 4

第2章 组网框架 ............................................................................................................................... 6

第3章 开发流程 ............................................................................................................................... 7

3.1 获取WSDL文件 ................................................................................................................ 7

3.2 通过gSOAP工具生成C/C++文件 ................................................................................... 8

3.2.1 gSOAP工具说明 ...................................................................................................... 8

3.2.2 使用wsdl2h程序生成头文件 ................................................................................. 9

3.2.3 使用生成源文件............................................................................. 10

3.3 开发业务逻辑代码 ........................................................................................................... 11

3.4 编译发布 ............................................................................................................................ 12

第4章 测试工具 ............................................................................................................................. 13

第5章 相关资料 ............................................................................................................................. 15

共15页 第2页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

第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组网

共15页 第3页

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 就是被创造出来完成这个任务的。

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的开发过程。

几个概念的关系：

Onvif协议开发的目的是为了实现一个网络视频框架协议，使不同厂商所生产的网络视频产品完全互通，而不同厂商可能会使用不同的平台、语言、内部协议来实现自己的网络视频产品，如何实现彼此间的互通及避免重复开发呢？

共15页 第4页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

Web Service就是一种忽略平台、语言的技术。它使用 SOAP 和 HTTP通过 Web 调用的方法来调用远程对象。这样，只要实现了Web Service，并且将功能集暴露出来，对端就可以通过远程调用对象的方式达成互通的目的，就像调用本地函数一样。

即使是调用本地函数，仍然需要知道函数名是什么，参数有哪些，参数类型是怎么样的。WSDL就描述了这些内容。相同的WSDL就能够保证了数据描述的一致性。

光是数据描述一致还不能实现远程调用，需要SOAP来提供通道。

没有gSOAP工具也可以实现Onvif协议开发的目标，但是需要写代码来解析WSDL文件，需要考虑的问题很多，重复性和机械性工作也很多。与其将时间跟精力花在解析WSDL文件上面，不如使用gSOAP工具来生成框架代码，将时间跟精力聚焦在业务上的实现。

共15页 第5页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

第2章 组网框架

图2-1是NVR的组网示意图，其中标红的地方是Onvif协议相关的模块，也就是本文所要介绍的开发模块。

图2-1 NVR组网

IPCNVRAppAppAdapterOnvif SBC SLogManTaskManDiskManPTZ…AppNetwork AdapterOnvif CBC CAppAdapterOnvif SBC SOnvif SOnvif CBC SBC CNetwork AdapterPC

说明：

1、 Onvif协议 S表示使用Onvif协议，充当的是Server角色；BC S表示使用百川内部协议，充当的是Server角色；Onvif协议 C表示使用Onvif协议，充当Client角色；BC C表示使用百川内部协议，充当Client协议。

2、

重点关注Onvif协议相关的部分，其他的模块的关系与数据交换只需要意会即可，不必深入研究。

共15页 第6页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

第3章 开发流程

总体开发流程如图3-1所示。工作的重点在于业务逻辑开发，但如果不了解各流程的来龙去脉，在看到一些工具生成的文件时，将会感觉到迷惑。

图3-1 Onvif协议开发的流程

3.1 获取WSDL文件

如果每个厂商都定义自己的WSDL文件，则Onvif协议只能做到方便跟别的厂商对接；要实现各厂商产品的完全互通，WSDL文件必须是统一的。幸运的是，Onvif协议组织提供了这样的WSDL文件，地址在下面网页的“ONVIF WSDL and XML Schemas Specifications”节下。

/Documents/

获得的WSDL文件如图3-2所示，感兴趣的可看一下WSDL文件的内容，这里不展开。

共15页 第7页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

图3-2 获取的WSDL文件

3.2 通过gSOAP工具生成C/C++文件

3.2.1 gSOAP工具说明

gSOAP工具是开源的，在网上搜索一下就能获得该工具及源码。下面以gSOAP2.8为例进行说明。

从网上下载gSOAP工具，解压后得到的文件列表如图3-3所示。

图3-3 gSoap2.8文件列表

说明文档及源代码有必要的时候可以查看下，我们现在只关注工具的应用。在gsoapbin目录下，看到gSOAP工具可在Linux、Macosx和Windows操作系统下运行。

共15页 第8页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

图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?

当然，此文件不必每次都修改，我们知道归档的文件跟gSOAP自带的文件不同的原因即可。如图3-5所示，右边是修改后的文件，只贴出来部分。

图3-5 修改前后的

拿远程设备发现举例。

首先打开dos窗口，进入到所在目录。

如果设备发现的wsdl文件在网上，则生成头文件的命令为：

wsdl2h -o Onvif协议.h -c -s -t . 协议.org/Onvif协议/ver10/network/wsdl/

如果文件已经下载下来，并且放在相同的目录中，则共15页 第9页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

对应的命令为：

wsdl2h -o Onvif协议.h -c -s -t .

命令执行成功后，将生成一个Onvif协议.h文件。

如果要生成多个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依赖的目录

共15页 第10页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

图3-7 soapcpp2生成的文件

3.3 开发业务逻辑代码

在上节中，已经使用gSOAP工具生成了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);

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);

共15页 第11页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

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};

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,

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->__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协议相关代码在系统内都是增量开发，编译时遵循各种系统原来的规则即可，无特殊要求。

共15页 第12页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

第4章 测试工具

使用Onvif协议测试工具“ONVIF协议 Conformance Test”可验证所实现的Onvif协议协议是否符合规范。本文介绍的Onvif协议测试工具版本是V1.02.4。安装包里的文件如图4-1所示。

图4-1 Onvif协议测试工具安装包

单击，默认安装即可。启动测试工具，显示主界面如图4-2所示。

图4-2 Onvif协议测试工具主界面

单击Test标签页，可看到测试工具里面的内容包含了IP配置、设备发现、设备管理、媒体配置等Onvif协议功能项，如图4-3所示。

共15页 第13页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

图4-3 Onvif协议测试工具的测试项

工具的详细使用方法请参看工具的帮助（通过菜单Help > How do I…调出）。帮助文档如图4-4所示。

图4-4 Onvif协议测试工具的帮助

共15页 第14页

Onvif协议开发简介-美佳威迪欧电子（香港）实业有限公司“网上学院”

第5章 相关资料

Onvif协议组织的官网：

/

Onvif协议成员单位-美佳威迪欧电子（香港）实业有限公司官网

发邮件获取技术支持：sales@

技术咨询QQ：1421174152

共15页 第15页