简介：面向Linux平台下需要对接ONVIF网络摄像机的C/C++开发者，这套资料提供了基于gSOAP生成ONVIF框架C代码的完整实现。包内共12个文件，涵盖5个C源文件、5个头文件、1个命名空间映射文件及1个makefile，整体仅1.31MB，结构紧凑，适合直接嵌入实际工程。已有1692人学习下载。
资料包含gSOAP编译器预处理WSDL后生成的代理与存根源码，以及对应接口头文件和构建脚本。示例代码演示了初始化客户端、连接设备、获取设备信息、请求RTSP码流地址等关键操作，返回的XML数据由gSOAP自动编解码，开发者可直接使用C结构体处理结果。对于正在搭建ONVIF客户端、实现视频监控或设备互通的工程师，这份资料能节省大量WSDL转换与基础框架搭建时间，同时帮助理解gSOAP的工作流程，无论入门学习还是快速原型验证都极具参考价值。
1. 为什么用 gSOAP 生成 ONVIF 框架 C 代码：先解决能不能跑再谈可维护
在 Linux 下用 gSOAP 生成 ONVIF 框架 C 代码，这件事看着像编译问题，实际是翻译问题：ONVIF 设备通过 SOAP 收发报文，而 gSOAP 能把 WSDL 定义翻译成可编译、可调用的 C 结构体和远程调用函数。我在接到一个网络摄像机对接任务时，设备 SDK 只开放了 RTSP 和登录接口，NVR 平台却要求兼容 ONVIF 的标准能力发现和设备管理，手写 SOAP 报文拼 XML 很快就成了黑匣子，抓包调错一整天都未必能对上字段。用 gSOAP 生成 ONVIF 框架 C 代码，是把协议成本前置到生成阶段的最直接办法，适合要快速接入 IPC、NVR、平台网关的嵌入式开发者，也适合想摆脱厂商私有 SDK 束缚、自己掌控协议的团队。
2. gSOAP 工具链拆解：WSDL、wsdl2h、soapcpp2 各自解决什么问题
2.1 ONVIF 的 WSDL 体系与 gSOAP 的接口模型
ONVIF 的规范不是一份文档，而是一组 WSDL 和 XSD 文件的组合。设备管理、媒体配置、PTZ 控制分别对应 devicemgmt、media、ptz 等服务，每个服务都有自己的 WSDL，而这些 WSDL 又会 include 一些通用的 XML Schema，比如 common.xsd 和 types.xsd。开发者要做的不是把整份协议背下来，而是把这一组定义文件交给工具，让它生成出"能编译的客户端"。
gSOAP 恰好是干这个的。它的思路是：WSDL 描述的是服务的接口和数据结构，XML Schema 描述的是这些数据在 XSD 类型系统中的约束，而 gSOAP 可以把这两者映射成 C 语言里的结构体、枚举和函数原型。映射过程分成两步，第一步用 wsdl2h 把 WSDL/XSD 转成一个头文件，第二步用 soapcpp2 读这个头文件，生成真正的序列化代码和远程调用框架。这两步是流水线关系，中间产物是 onvif.h，理解这条链路，后面所有生成、编译问题都能定位到具体环节。
2.2 wsdl2h：把 WSDL 变成 C 头文件的翻译官
wsdl2h 接受多个 .wsdl 和 .xsd 文件作为输入，通过分析 XML Schema 的 type、element、message、portType、binding，生成一个包含全部数据类型和服务方法声明的头文件。它的关键参数我一般这样用：
wsdl2h -c -s -o onvif.h -P http://www.onvif.org/ \ -t typemap.dat \ devicemgmt.wsdl media.wsdl ptz.wsdl common.xsd types.xsd-c 表示生成纯 C 代码，不引入 C++ 包装；-s 表示不使用 STL 数据结构，嵌入式场景更友好；-o 指定输出文件名；-P 把 ONVIF 的 URL 前缀映射成短标识符，生成出来的结构体命名更短；-t 指定自定义 typemap.dat。typemap.dat 的作用是把难以直接映射的 XSD 类型替换成 C 类型，比如把 xsd__duration 映射成 char*，把常用的 datetime 字符串映射成 time_t，这一步直接影响后续可读性。
不指定 -t 也能跑，但生成的头文件里会出现大量 wsdl__ 前缀的中间类型，代码量大且难读。社区里常见的做法是维护一份针对 ONVIF 的 typemap.dat，把 ONVIF 自定义的 tds__、trt__、tptz__ 命名空间映射清理干净，再配合 -P 使用，生成的头文件才谈得上可维护。
2.3 soapcpp2：从中间头文件生成真正的 C 代码
wsdl2h 完成后，onvif.h 里是类型和接口的声明。soapcpp2 读这个头文件，做的是第二层翻译：把声明变成实现。它生成的文件在工程里起着骨架作用，下面这张清单是生成物与职责对照。
| 生成文件 | 职责 |
|---|---|
| soapStub.h | 各结构体、枚举的定义，所有远程调用函数的原型声明 |
| soapH.h | 序列化/反序列化函数声明、SOAP_TYPE 类型标识宏 |
| soapC.c | XML 解析与序列化的具体实现 |
| soapClient.c | soap_call__ 系列客户端调用封装 |
| soapServer.c | soap_serve__ 系列服务端调度骨架 |
| soapClientLib.c / soapServerLib.c | 把客户端或服务端代码打包成库文件，用 -L 参数生成 |
soapcpp2 的调用本身不复杂：
soapcpp2 -c -d generated -I/usr/local/include/gsoap onvif.h -L-c 继续维持纯 C；-d 指定输出目录，避免生成物和 onvif.h 混在一起；-I 指向 gSOAP 的 import 目录，因为生成的代码会 include 一些公共头文件；-L 生成库形式的 soapClientLib.c，方便后续集成。无论怎么生成，gSOAP 运行引擎 stdsoap2.c 都不在其中，它是独立的一部分，链接时必须一起编进去。
2.4 生成代码与手写业务代码的边界
很多初接触 gSOAP 的人会把生成的 6 个文件全部改一遍，这是错误方向。soapStub.h 是接口契约，soapClient.c 和 soapC.c 是协议实现，它们只有在 WSDL 变更时才需要重新生成，业务代码不应该往里塞。我一般这样组织：生成的代码单独放一个目录，业务代码只 include soapStub.h 和 soapH.h，通过 soap_call__ 系列函数与设备通信，不直接触摸 soapC.c。这个边界清晰之后，二次变更时只需重新生成并对比 soaapStub.h 的差异，就不用担心手写改动被覆盖。
3. 动手生成：从拿到 WSDL 到编译出一个可运行的 ONVIF 客户端
3.1 准备目录与依赖
先在 Linux 环境装好依赖。gSOAP 用到的编译依赖是 gcc、make、openssl 开发库（计算摘要用），运行则依赖 libc。工作目录我习惯按模块分开，避免生成物污染源码：
onvif-linux/ ├── wsdl/ ├── generated/ ├── src/ │ └── main.c ├── third-party/ │ └── gsoap/ └── Makefilewsdl/ 放下载回来的 .wsdl 和 .xsd，generated/ 放 soapcpp2 的输出，third-party/gsoap 放 gSOAP 源码。ONVIF 的 WSDL 文件从官网规范下载区获取，注意按协议版本拉取整套而不是单独一个文件。常见做法是先把 devicemgmt.wsdl 下载回来，再用工具解析它 include 了哪些 schema，把这些一并补齐，否则 wsdl2h 会报 schema 文件找不到的错误。
3.2 用 wsdl2h 生成 onvif.h
WSDL 齐全后进入生成第一步。初次运行时我建议先用最小集合验证环境：
cd wsdl wsdl2h -c -s -o onvif.h -P http://www.onvif.org/ \ devicemgmt.wsdl media.wsdl ptz.wsdl common.xsd types.xsd命令执行完，终端会输出正在处理的命名空间和文件列表，没有报错即生成成功。打开 onvif.h 确认里面出现了 _tds__GetDeviceInformation、_trt__GetProfiles 这类结构体声明，说明 WSDL 解析正常。这里有个常踩的坑：如果只给了 devicemgmt.wsdl，而它 include 的 types.xsd 不在同一目录，wsdl2h 会直接报错退出，不是解析失败，是文件缺失，把公共 schema 下载到同一目录即可。
生成后的 onvif.h 通常很大，几万行很正常，别被吓到，里面绝大多数是类型声明，真正需要手改的只有少量内容。
3.3 用 soapcpp2 生成框架 C 代码
接下来把 onvif.h 转成可编译的 C 代码：
mkdir -p ../generated soapcpp2 -c -d ../generated -I/usr/local/include/gsoap -L onvif.h如果 onvif.h 里包含了 WS-Security 相关定义，soapcpp2 会提示缺少 wsse.h 之类的公共文件，这时把 gSOAP 自带示例里的 wsse.h 和 wsse.c 一并放进 generated/ 再编译，或者直接让 -I 指向包含它们的目录。生成完成后，在 generated/ 里应该能看到 soapStub.h、soapH.h、soapC.c、soapClient.c、soapServer.c 这几个文件。
到这里，一个可以调用的 ONVIF 客户端框架已经落地，剩下的是把业务代码写进去。
3.4 编译最小的可运行客户端
在 src/main.c 里写一个最简单的调用：设备能力发现。ONVIF 规范规定第一个要调的接口就是 GetDeviceInformation，通过它拿厂商、型号、固件版本，验证认证是否通过。
#include "soapH.h" #include "soapStub.h" #include "wsse.h" int main(void) { struct soap *soap = soap_new2(SOAP_C_UTFSTRING, SOAP_C_UTFSTRING); struct _tds__GetDeviceInformation req, res; const char *endpoint = "http://192.168.1.64/onvif/device_service"; memset(&req, 0, sizeof(req)); memset(&res, 0, sizeof(res)); if (soap_call___tds__GetDeviceInformation(soap, endpoint, NULL, &req, &res) == SOAP_OK) { printf("Manufacturer: %s\n", res.Manufacturer ? res.Manufacturer : ""); printf("Model: %s\n", res.Model ? res.Model : ""); printf("FirmwareVersion: %s\n", res.FirmwareVersion ? res.FirmwareVersion : ""); } else { soap_print_fault(soap, stderr); } soap_destroy(soap); soap_end(soap); soap_free(soap); return 0; }malloc 的行为。soap_new2 创建引擎，两个参数是传输和编码标志；soap_call___tds__GetDeviceInformation 是远程调用入口，endpoint 是设备 ONVIF 服务地址，NULL 是 SOAPAction，后两个参数分别是请求和响应结构体；soap_destroy 释放所有通过 soap_malloc/soap_new 分配的对象，soap_end 清理当前上下文，soap_free 释放引擎本身，顺序不能反。
This 逻辑很简单，但注意 res 里的字符串字段是 gSOAP 内部 buffer 管理的，不能手动 free，否则 double free 崩溃。gSOAP 把响应对象的生命周期绑定在 soap 引擎上，统一用 soap_destroy 收尾。
3.5 第一次编译与运行的前置自检
用 Makefile 把引擎、生成的代码、业务代码编在一起：
CC ?= gcc CFLAGS = -Igenerated -Ithird-party/gsoap -D_GNU_SOURCE LDFLAGS = -lssl -lcrypto -lpthread OBJS = generated/soapC.o generated/soapClient.o generated/soapClientLib.o \ third-party/gsoap/stdsoap2.o src/main.o onvif_client: $(OBJS) $(CC) -o $@ $(OBJS) $(LDFLAGS) %.o: %.c $(CC) $(CFLAGS) -c $< -o $@stdsoap2.c 是 gSOAP 运行引擎，必须编进来；-lpthread 是因为 gSOAP 内部在非阻塞模式下会用到线程相关功能。首次编译最容易翻车的地方是 -I 路径，wsse.h、soapStub.h 分散在 generated 和 gSOAP 源码两个目录，少一个目录 include 就报找不到头文件。编好后跑一次，连不上设备时先确认网络层，再确认认证。
4. 核心代码拆解：一次带鉴权的 ONVIF 请求从发送到返回的完整链路
4.1 生成代码里的文件职责，哪些可以放心改
拿到生成代码后我通常是这么看它的：soapStub.h 是数据结构的唯一权威来源，soapH.h 是序列化函数和类型 ID 的注册表，soapC.c 是类型转换与 XML 解析实现，soapClient.c 是客户端调用封装，soapServer.c 是服务端入口。其中能放心改的是业务层文件，生成物原则上只作黑匣子使用。
但有一个文件值得细读，soapH.h 里的 SOAP_TYPE_ 宏。它定义了每个结构体在序列化映射表中的类型 ID，像 SOAP_TYPE__tds__GetDeviceInformationResponse 这样的枚举贯穿整个传输链路。如果做深度的自定义服务，新增了结构体却没有注册类型 ID，序列化时会直接报 SOAP_TYPEMAP 错误，这个知识点在使用 soapcpp2 扩展接口时会反复踩到。
4.2 ONVIF 鉴权头是如何在框架里落地的
ONVIF 标准几乎强制要求 WS-UsernameToken 鉴权，gSOAP 生成代码不会自动填充鉴权头，需要手动构造 Security 元素再挂到 soap->header 上。
static int onvif_set_auth(struct soap *soap, const char *username, const char *password) { struct SOAP_ENV__Header hdr; struct wsse__Security sec; struct wsse__UsernameToken token; unsigned char nonce[16]; unsigned char digest[EVP_MAX_MD_SIZE]; unsigned int digest_len; char created[32]; time_t now; memset(&hdr, 0, sizeof(hdr)); memset(&sec, 0, sizeof(sec)); memset(&token, 0, sizeof(token)); /* 随机生成 16 字节 nonce */ RAND_bytes(nonce, sizeof(nonce)); /* 生成 UTC 时间戳，格式固定为 YYYY-MM-DDTHH:MM:SSZ */ time(&now); strftime(created, sizeof(created), "%Y-%m-%dT%H:%M:%SZ", gmtime(&now)); /* digest = SHA1(nonce + created + password) */ EVP_MD_CTX *ctx = EVP_MD_CTX_new(); EVP_DigestInit_ex(ctx, EVP_sha1(), NULL); EVP_DigestUpdate(ctx, nonce, sizeof(nonce)); EVP_DigestUpdate(ctx, created, strlen(created)); EVP_DigestUpdate(ctx, password, strlen(password)); EVP_DigestFinal_ex(ctx, digest, &digest_len); EVP_MD_CTX_free(ctx); token.Username = (char *)username; token.Password = soap_s2base64(soap, digest, NULL, digest_len); token.nonce = soap_s2base64(soap, nonce, NULL, sizeof(nonce)); token.wsu__Created = (char *)created; sec.UsernameToken = &token; soap->header = &hdr; hdr.wsse__Security = &sec; return SOAP_OK; }注意一个关键差异：早期设备支持 PasswordText 明文，把 token.Password 直接放密码、不设 nonce 也能过；但新设备基本都校验 PasswordDigest，也就是上面这套计算。token 里的 nonce 和 Created 字段必须出现在 SOAP Header 里，设备端会用同样的算法重新计算摘要来比对，所以本机时间和设备时间如果偏差太大，digest 一定验证失败。密码不要用 strlen 之外的编码处理，遇到 UTF-8 密码时 digest 长度会偏。
soap_s2base64 是 gSOAP 自带的内存安全 base64 编码函数，返回的指针由 soap 引擎托管，不需要手动 free。soap->header 的赋值要在每次发送前重新做，因为上一次发送会清空 header 上下文。很多 401 错误不是密码错，而是头没挂上去或时间戳格式不对。
4.3 一次 GetDeviceInformation 调用的内部链路
soap_call___tds__GetDeviceInformation 不是直接发 HTTP 请求，它内部经历了完整的序列化和传输链：
int soap_call___tds__GetDeviceInformation(struct soap *soap, const char *endpoint, const char *soap_action, struct _tds__GetDeviceInformation *in, struct _tds__GetDeviceInformationResponse *out) { struct __tds__GetDeviceInformation tmp; memset(&tmp, 0, sizeof(tmp)); tmp.tds__GetDeviceInformation = in; soap_begin_send(soap); if (soap_put___tds__GetDeviceInformation(soap, endpoint, soap_action, &tmp) == SOAP_OK) soap_end_send(soap); soap_begin_recv(soap); if (soap_get___tds__GetDeviceInformation(soap, &tmp) == SOAP_OK && soap->error == SOAP_OK) { /* 从响应结构中复制出业务字段 */ *out = *tmp.tds__GetDeviceInformationResponse; } soap_end_recv(soap); return soap->error; }soap_put_ 系列函数把请求结构体按 XML Schema 定义序列化成 SOAP XML，soap_get_ 系列反序列化响应，中间用 soap_begin_send/end_send/begin_recv/end_recv 做 HTTP 边界的控制。这里有个细节值得注意：响应结构体是从临时变量 tmp 里拷贝出来的，而不是直接在 out 上反序列化，这么做是为了避免 SOAP 的 envelope 格式污染业务结构。理解这条链路之后，后面做异步调用和超时控制会容易很多。
4.4 内存生命周期：谁负责释放，谁不能动
gSOAP 最反直觉的地方是内存托管。soap_malloc、soap_new、soap_s2base64 返回的指针都在 soap 引擎的上下文里注册，soap_destroy 统一释放。如果开发者手动 free 这些指针，轻则 double free，重则整个堆结构被破坏，程序表现像玄学崩溃。我一般只在长期驻留进程里单独为每个请求 new 一个 soap 上下文，用完 destroy+free，不让两个请求共享同一个引擎。
5. 实操避坑：生成、编译、对接中的常见问题排查
5.1 编译通过但设备一直返回 401 Unauthorized
现象：程序编译无错误，运行后 soap_print_fault 输出 401，设备日志显示鉴权失败。原因基本不在 gSOAP 本身，而是 SOAP Header 没带全或摘要算法算错。常见情况有三种：soap->header 每次发送后没重新挂载；PasswordDigest 里的 nonce 和 Created 没同步更新；设备时间与本机相差超过 5 分钟，摘要校验失败。解决方法是抓包看实际发送的 XML，确认 Security 元素存在，再逐一比对 Username、nonce、Created、Password 四个字段。密码摘要串错一个字都会导致 401。
5.2 程序运行到 soap_end 或 soap_free 时段错误
现象：soap_call__ 返回 SOAP_OK，一切正常，退出前调用 soap_end 直接崩溃。原因是手动释放了响应结构体里的字符串字段，比如对 res.Manufacturer 调了 free。gSOAP 把响应内容的生命周期绑定在引擎上，soap_destroy 会统一回收，任何手动 free 都会让它二次释放。解决方法是保持代码干净，所有由 soap_ 函数返回的指针都交给引擎管理，业务层只拷贝字符串内容，不接管指针。这个习惯在接手旧项目时尤其重要，老代码里裸 free 太多，接过来第一件事应该是删除所有针对 gSOAP 结构体的 free 调用。
5.3 交叉编译时总报 stdsoap2.h 找不到
现象：在 x86_64 主机上编译正常，换成交叉工具链后 include 阶段直接失败。原因通常是 -I 路径没有正确包含 gSOAP 源码目录，或者 Makefile 里用了系统路径 /usr/include。解决方法是把 gSOAP 源码作为 third-party 放进工程，Makefile 里用相对路径指定 -I，交叉编译时只替换 CC。另一个问题是 gSOAP 源码里有平台配置宏，比如 SOAP_PLATFORM_LINUX，在编译 stdsoap2.c 时必须与业务代码的宏保持一致，否则会出现结构体字节对齐不一致导致的内存错乱。
5.4 设备响应慢，程序在 recv 阶段长时间阻塞
现象：调 GetDeviceInformation 偶尔要等十几秒才返回，甚至直接卡死。原因是没设置网络超时，gSOAP 默认缺省超时时间是无限。解决方法是显式配置：
struct soap *soap = soap_new2(SOAP_C_UTFSTRING, SOAP_C_UTFSTRING); soap->connect_timeout = 5; soap->recv_timeout = 5; soap->send_timeout = 5;connect_timeout 控制 TCP 连接建立，recv_timeout 控制读取响应，send_timeout 控制发送请求。这三个值是秒数，按设备部署环境的网络质量调，局域网设备 5 秒足够，跨公网场景可以放宽到 10 秒。超时后 soap->error 返回 SOAP_EOF 或 SOAP_TCP_ERROR，需要先判断错误类型再决定重试还是放弃。
5.5 重新生成代码把手工改动覆盖了
现象：改过 generated/soapClient.c 后重新跑 soapcpp2，全部改动消失。原因是在生成目录上原地覆盖，没做隔离。解决方法是生成产物与手工代码彻底分离，generated/ 只放生成文件，业务代码引用 soapStub.h 的接口，不修改生成实现。如果确实需要改生成逻辑，也要保留改动脚本或用 patch 文件管理，生成后自动重放。从那以后我每次重新生成都会先把 generated/ 里的旧文件复制到备份目录，diff 一下再决定是否保留。
6. 二次开发改造：把生成的框架代码改造成自己的业务层
生成的代码是骨架，直接往里填业务会越写越乱。我在对接多个品牌设备后发现，更扎实的改造思路是把所有 ONVIF 交互收敛到一个业务层，上层只面对设备操作，不面对 SOAP 结构体。第一步，把设备的服务地址、用户名、密码封装成一个上下文结构体，所有请求都从这个上下文出发。第二步，把 soap_call__ 系列函数包成统一的返回码和错误信息，底层错误不再以 SOAP_OK 形式泄露到业务层。第三步，把鉴权头的构造放进公共入口，新加接口时不用重复写一遍 wsse 逻辑。
异步调用是另一个高频改造点。默认 soap_call__ 是同步阻塞模式，如果同时要管理多路设备，阻塞调用会拖死主循环。改造方式是用 soap_put_ 和 soap_get_ 系列把发送和接收拆开：先 soap_begin_send + soap_put___tds__GetDeviceInformation 把请求发出，然后轮询 soap_begin_recv + soap_get_ 是否返回。配合 recv_timeout，单线程也能轮流处理几十台设备的心跳和状态查询。
自定义服务扩展需要动生成入口。假设要向设备端加一个私有配网接口，做法是在 onvif.h 里按 WSDL 风格手动添加 service 方法和结构体，再跑 soapcpp2。它会为新增接口生成 soap_serve__ 的调度分支和 serializer 代码。验证这套改造是否成立的流程，我一般先用一个开源工具作为模拟端，确认报文格式正确，再连真实设备抓包对比。某次改造后设备状态上报一直不触发，最后发现是自定义接口的 SOAPAction 没有在 WSDL 里声明，设备端按规范拒绝了请求。从那以后我每次加新接口都强制走一遍完整验证链路：生成、编译、模拟端校验、真机抓包，等四步全部通过才提交。这套流程虽然繁琐，但能省掉后期大量扯皮，希望帮到你。
本文还有配套的精品资源，点击获取
