示例工程【免费下载链接】Windows-classic-samplesThis repo contains samples that demonstrate the API used in Windows classic desktop applications.项目地址https://gitcode.com/gh_mirrors/wi/Windows-classic-samples点击查看免费下载导读本文以 Windows-classic-samples 仓库中的 EnumRelationship 示例 为主线系统讲解 Windows DHCP Server 管理 API 中DhcpV4FailoverEnumRelationship的完整用法包括分页枚举的调用模式、返回值语义、结果数据的读取与内存释放以及它在 DHCP 故障转移Failover管理 API 家族中的定位。读完本文你将掌握如何用 C 遍历一台 DHCP 服务器上的全部故障转移关系并能在此基础上扩展到创建、查询、修改、删除关系的配套 API。一、示例背景DHCP 与故障转移关系DHCPDynamic Host Configuration Protocol是一种标准化协议允许客户端被动态分配 IP 地址、子网掩码、默认网关等关键网络配置参数。DHCP 服务器集中管理这些配置数据由网络管理员针对特定网络环境进行设置并通过 DHCP 消息与客户端通信见 README.md 的说明。在多服务器部署场景中Windows DHCP 服务支持故障转移Failover两台服务器主服务器 Primary Server 与辅助服务器 Secondary Server通过一条故障转移关系Failover Relationship共享一个或多个作用域Scope。当其中一台服务器不可用时另一台接管地址分配。从本仓库 CreateRelationship 示例源码 可以看到一条关系包含以下关键属性RelationshipName关系名称如testPrimaryServer/SecondaryServer主、辅服务器 IP 地址源码中0xa000001即10.0.0.1PrimaryServerName/SecondaryServerName主、辅服务器名称Mode关系模式取LoadBalance负载均衡或HotStandby热备McltMaximum Client Lead Time客户端最大前导时间示例中0xe10 3600 秒SafePeriod安全期0x258 600 秒Percentage负载均衡百分比0x32 50%SharedSecret主辅服务器间的共享机密pScopes该关系所包含的作用域 IP 数组DHCP_IP_ARRAY结构。EnumRelationship 示例正是解决如何枚举一台服务器上已存在的所有这类关系这一问题它所调用的DhcpV4FailoverEnumRelationship属于DHCP Server Management API中Dhcpv4Failover系列函数。二、示例工程结构与系统要求2.1 文件布局该示例在仓库中的目录结构如下路径作用Samples/DHCP/EnumRelationship/README.md示例说明文档Samples/DHCP/EnumRelationship/cpp/EnumRelationship.cpp唯一源码文件完整演示枚举调用Samples/DHCP/EnumRelationship/cpp/EnumRelationship.slnVisual Studio 解决方案文件Samples/DHCP/EnumRelationship/cpp/EnumRelationship.vcxproj项目文件2.2 操作系统与开发环境要求README 明确列出的环境要求为客户端Windows 8.1服务器Windows Server 2012 R2开发工具Visual Studio Express 2013 for Windows 8.1 或更新版本README 同时说明多数情况下使用更高版本工具链可无修改运行。从 EnumRelationship.vcxproj 可以进一步确认工程级配置仅提供x64平台的 Debug / Release 两个配置工具集PlatformToolset为v110对应 Visual Studio 2012/2013 工具链CharacterSet为Unicode预处理器定义包含WIN32_LEAN_AND_MEAN、UNICODE、_UNICODE等链接器通过AdditionalOptions显式引入dhcpsapi.libDHCP Server 管理 API 的导入库子系统为Console控制台程序编译警告级别为 Level4并将警告视为错误TreatWarningAsErrortrue。这些配置意味着示例是一个面向 x64、Unicode 字符集、依赖dhcpsapi.h头文件的控制台应用运行前必须保证目标 Windows 具备 DHCP Server 管理 API 支持。三、核心原理分页式的枚举调用模式DhcpV4FailoverEnumRelationship与常见的 Windows 枚举类 API如EnumServicesStatusEx一样采用分页paging协议服务器不会一次返回全部数据而是按批返回调用方通过循环持续拉取直到取完。从 EnumRelationship.cpp 主函数 可以看出实际调用形式dwError DhcpV4FailoverEnumRelationship( pwszServer, // 服务器 IP 地址NULL 表示当前本机 resumeHandle, // 断点句柄首次调用为 0后续调用回传更新值 preferredMax, // 单批期望最大条数DWORD_MAX 表示采用服务器默认分页大小 enumRelationInfo, // 输出本次返回的关系数组 dwElementsRead, // 输出本次实际读取到的关系条数 dwElementsTotal); // 输出服务器上关系总数各参数含义归纳如下参数方向说明ServerIpAddresspwszServer入目标 DHCP 服务器的 IP 地址字符串传NULL代表当前执行程序所在的服务器ResumeHandleresumeHandle入/出分页续传句柄。首轮调用置 0之后由 API 写入新值下一轮调用原样回传PreferredMaximumpreferredMax入调用方期望单批返回的最大条数示例传DWORD_MAX即不限制交由服务器决定EnumRelationshipInfoenumRelationInfo出指向LPDHCP_FAILOVER_RELATIONSHIP_ARRAY接收本批关系数据ElementsReaddwElementsRead出本批实际读到的关系条数ElementsTotaldwElementsTotal出服务器上关系总数用于判断是否已取完3.1 返回值语义与循环终止条件示例 源码的错误处理段 展示了三种关键返回码的配合ERROR_SUCCESSNO_ERROR本批成功返回ERROR_MORE_DATA还有更多数据未取完应携带更新的resumeHandle继续循环ERROR_NO_MORE_ITEMS已无更多条目枚举结束。循环逻辑为for(;;) { dwError DhcpV4FailoverEnumRelationship(...); // 1) 除上述三种返回码外的任何错误打印后直接终止 if ((NO_ERROR ! dwError) (ERROR_MORE_DATA ! dwError) (ERROR_NO_MORE_ITEMS ! dwError )) { wprintf(LError in enumerating relationships. Error %d\n, dwError); break; } // 2) 处理本批数据见下文第四节 if (dwElementsRead enumRelationInfo) { ... FreeDhcpFailoverRelationshipArray(enumRelationInfo); enumRelationInfo NULL; } // 3) 取完的标志返回 ERROR_NO_MORE_ITEMS或 SUCCESS 且总数为 0 if (ERROR_NO_MORE_ITEMS dwError || (dwError ERROR_SUCCESS dwElementsTotal 0)) { dwError ERROR_SUCCESS; break; } // 4) 重置计数进入下一轮 dwElementsRead 0; dwElementsTotal 0; }这段代码是分页枚举的通用模板每轮处理完数据后立即释放输出内存随后依据返回码决定是否继续直到收到ERROR_NO_MORE_ITEMS或确认总数已取尽。dwElementsRead在本批没有数据时为 0enumRelationInfo也为 NULL因此示例用if (dwElementsRead enumRelationInfo)双重判断后再进入数据处理分支避免对空指针解引用。四、完整源码逐段精讲4.1 头文件与依赖EnumRelationship.cpp 顶部包含#includewindows.h #includestdio.h #includeintsafe.h // 安全整数运算辅助头 #includedhcpsapi.h // DHCP Server 管理 API 声明如 DhcpV4FailoverEnumRelationship其中dhcpsapi.h是使用本系列 API 的必经头文件它声明了DHCP_FAILOVER_RELATIONSHIP、DHCP_FAILOVER_RELATIONSHIP_ARRAY、DHCP_IP_ARRAY等数据结构以及DhcpV4Failover*系列函数原型。4.2 内存释放辅助函数API 通过 RPC 返回的数据使用DhcpRpcFreeMemory释放这是 DHCP Server 管理 API 家族的通用约定。示例为此编写了三个层次分明的释放函数FreeIPArray释放LPDHCP_IP_ARRAY先释放内部Elements数组再释放结构本身FreeDhcpFailoverRelationship释放单条关系。先逐个释放RelationshipName、PrimaryServerName、SecondaryServerName、pScopes、SharedSecret等字符串与数组成员再释放关系结构本体重载了按值与按指针两种形式FreeDhcpFailoverRelationshipArray遍历DHCP_FAILOVER_RELATIONSHIP_ARRAY的pRelationships数组逐条调用上面的释放函数最后释放数组本体。这一组函数是枚举示例的关键配套代码凡是 API 输出的堆内存都必须用DhcpRpcFreeMemory精确释放否则会产生内存泄漏。可以对照 GetRelationship 示例 中结构相同的FreeRelationshipMemory佐证这一内存管理约定。4.3 枚举结果的处理示例对每批返回的数据做了最简示范——打印每条关系的名称for ( dwIdx 0; dwIdx enumRelationInfo-NumElements; dwIdx ) { wprintf(LRelationship name %s\n, enumRelationInfo-pRelationships[dwIdx].RelationshipName); }DHCP_FAILOVER_RELATIONSHIP_ARRAY结构的两个字段在此处被使用NumElements本数组中关系条数pRelationshipsDHCP_FAILOVER_RELATIONSHIP数组指针每个元素即一条完整的关系描述含名称、主辅服务器、模式、MCLT、SafePeriod、百分比、共享机密、作用域列表等字段。实际业务中你可以在循环内根据RelationshipName做筛选、比对或驱动后续操作例如进一步调用DhcpV4FailoverGetRelationship获取单条关系明细、调用DhcpV4FailoverSetRelationship修改参数等。处理完毕后务必调用FreeDhcpFailoverRelationshipArray释放本批内存并将指针置 NULL。五、DhcpV4Failover 关系 API 家族与本示例的定位DhcpV4FailoverEnumRelationship并非孤立 API它属于 DHCP Server Management API 中管理故障转移关系的一组函数。Windows-classic-samples 仓库在 Samples/DHCP 目录下为这一家族提供了成系列的配套示例可作为枚举结果的后续动作参考示例目录使用的 API源码要点GetRelationshipDhcpV4FailoverGetRelationship按关系名test查询单条关系演示DhcpRpcFreeMemory释放模式SetRelationshipDhcpV4FailoverGetRelationshipDhcpV4FailoverSetRelationship先取回关系再通过dwFlagsMODE、SAFEPERIOD、MCLT、PERCENTAGE位指定要修改的字段CreateRelationshipDhcpV4FailoverCreateRelationship/DhcpV4FailoverDeleteRelationship完整构造DHCP_FAILOVER_RELATIONSHIP含pScopes作用域数组并在主辅服务器上先后建关系DeleteRelationshipDhcpV4FailoverGetRelationshipDhcpV4FailoverDeleteRelationship删除前先停用相关作用域主、辅服务器分别删除GetScopeRelationshipDhcpV4FailoverGetScopeRelationship按作用域子网地址如10.0.0.0反查所属关系从这些源码可以推断一条完整的关系生命周期通常是创建Create→ 枚举Enum→ 查询Get→ 修改Set→ 删除Delete而EnumRelationship 示例正是枚举环节的标准实现范本其分页循环与内存释放模式可以被其他枚举类 DHCP 管理 API如DhcpV4EnumPolicies对应仓库中的 EnumPolicy 示例直接复用。六、构建与运行6.1 构建按 README.md 的说明使用 Visual Studio Express 2013 for Windows 8.1 或更高版本打开解决方案文件 EnumRelationship.sln从顶部菜单执行Build → Build SolutionVisual Studio 2013 中为 F6其余版本通常为 F7编译产物默认输出到Debug或Release目录本工程为 x64 平台下的x64\Debug或x64\Release。工程使用v110工具集并链接dhcpsapi.lib构建时需确保 Windows SDK 提供 DHCP 管理头文件与导入库更高版本 Visual Studio 打开工程后如提示工具集升级可按默认处理。6.2 运行在 Visual Studio 中按F5启用调试运行或CtrlF5不启用调试运行也可通过Debug菜单选择相应选项。运行前提与限制README 与源码共同确认操作系统需为 Windows 8.1 / Windows Server 2012 R2 及兼容版本目标机器需具备 DHCP 服务器管理能力本 API 由 DHCP Server 管理服务承载pwszServer传NULL时枚举的是当前执行程序所在机器的 DHCP 服务器如需枚举远程服务器可将该参数改为目标服务器的 IP 地址字符串程序以控制台方式运行枚举结果关系名称逐条打印到标准输出返回码ERROR_NO_MORE_ITEMS或ERROR_SUCCESS且总数为 0 时正常结束。七、总结DhcpV4FailoverEnumRelationship是 Windows DHCP 故障转移管理中的核心枚举接口。通过 EnumRelationship 示例 可以学到一套可复用的标准模式分页调用resumeHandle配合ERROR_MORE_DATA循环拉取直到ERROR_NO_MORE_ITEMS输出约束preferredMax DWORD_MAX交由服务器决定批次大小ElementsRead/ElementsTotal用于统计与终止判断内存纪律所有输出结构必须经DhcpRpcFreeMemory逐层释放家族协同与DhcpV4FailoverGetRelationship、DhcpV4FailoverSetRelationship、DhcpV4FailoverCreateRelationship、DhcpV4FailoverDeleteRelationship、DhcpV4FailoverGetScopeRelationship共同构成关系管理的完整闭环。后续可在仓库 Samples/DHCP 目录下继续研读上述配套示例将枚举结果接入真实的运维与自动化管理流程。赞分享示例工程【免费下载链接】Windows-classic-samplesThis repo contains samples that demonstrate the API used in Windows classic desktop applications.项目地址https://gitcode.com/gh_mirrors/wi/Windows-classic-samples点击查看免费下载相关推荐Windows-classic-samples 实战使用 DhcpV4FailoverCreateRelationship API 创建 DHCP 服务器故障转移关系Windows classic samples 实战使用 DhcpV4FailoverCreateRelationship API 创建 DHCP 服务器故障示例工程Windows-classic-samples 实战使用 DhcpV4FailoverAddScopeToRelationship 将 DHCP 作用域加入故障转移关系Windows classic samples 实战使用 DhcpV4FailoverAddScopeToRelationship 将 DHCP 作用域加入故示例工程Windows DHCP Server 策略枚举实战DhcpV4EnumPolicies API 用法详解Windows-classic-samplesWindows DHCP Server 策略枚举实战DhcpV4EnumPolicies API 用法详解Windows classic samples示例工程上一篇终端美化神器awesome-hyper主题使用心得分享下一篇IntelliJ IDEA 简体中文专题教程从安装、配置到高效开发的全路径学习指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考