Linux PipeWire深度解析之pw_properties_iterate调用流程与实战(六十五)
简介：CSDN博客专家、《Android系统多媒体进阶实战》作者
博主新书推荐：《Android系统多媒体进阶实战》🚀
Android Audio工程师专栏地址：Audio工程师进阶系列【原创干货持续更新中……】🚀
Android多媒体专栏地址：多媒体系统工程师系列【原创干货持续更新中……】🚀
专题一 二：AAOS车载系统+AOSP14系统攻城狮入门视频实战课🚀
专题三：Android14 Binder之HIDL与AIDL通信实战课🚀
专题四：Android15快速自定义与集成音效实战课🚀
专题五：Android15音频策略实战课🚀
专题六：Android15音频性能实战课(无声/杂音/断音/爆音实战案例)🚀
人生格言：人生从来没有捷径，只有行动才是治疗恐惧和懒惰的唯一良药.
🍉🍉🍉文章目录🍉🍉🍉
- 🌻1.前言
- 要点概括
- 🌻2.应用场景与用法
- 函数原型
- 参数说明
- 返回值
- 应用场景
- 🌻3.调用流程剖析
- 🌻3.1核心步骤
- 🌻3.2调用流程图
- 🌻3.3生命周期图
- 🌻4.实战应用案例
- 🌻5.一句话总结
🌻1.前言
本篇目的：
Linux PipeWire深度解析之pw_properties_iterate调用流程与实战。
要点概括
核心功能：遍历pw_properties对象中的key/value属性集合，逐个取出属性key。
工作机制：调用者准备一个void*类型的迭代状态变量，并初始化为NULL；每次调用函数返回一个key，同时更新state，直到返回NULL表示遍历结束。
典型用途：调试PipeWire对象属性、打印Stream/Node/Device参数、过滤指定属性、复制Properties内容、构造运行时配置。
pw_properties_iterate的本质是“遍历属性key”，不是“读取属性value”。它每次返回的是属性名，也就是key；如果要拿到对应value，还需要使用pw_properties_get继续查询。
它也不是Properties对象的创建接口。Properties对象通常由pw_properties_new、pw_properties_new_dict、pw_properties_copy或框架内部传入，pw_properties_iterate只负责在已有Properties对象上移动遍历游标。
它和pw_properties_get的区别很明确：pw_properties_get是按指定key读取value；pw_properties_iterate是不知道key名称时，逐个枚举全部key。一个解决“点查”，一个解决“遍历”。
它和spa_dict遍历也有边界区别。pw_properties底层包含spa_dict，但pw_properties_iterate隐藏了内部遍历细节，应用侧只需要维护state即可，不必直接关心spa_dict_item数组如何组织。
🌻2.应用场景与用法
pw_properties_iterate
是PipeWire Properties API中用于遍历属性集合的接口。
PipeWire中大量对象都会携带Properties，例如Context、Core、Stream、Node、Device、Port、Client、Module等。Properties用于描述对象名称、媒体类型、角色、设备信息、应用信息、路由参数和调试信息。
在调试PipeWire对象时，经常需要把Properties完整打印出来。此时应用并不知道对象里有哪些key，不能只靠pw_properties_get固定读取某几个字段，就需要使用pw_properties_iterate逐个枚举。
pw_properties_iterate用于遍历pw_properties中的全部属性key。
函数原型
constchar*pw_properties_iterate(conststructpw_properties*properties,void**state);参数说明
conststructpw_properties*properties;properties表示要遍历的Properties对象。
它必须指向一个有效的pw_properties对象。该函数不会创建Properties，也不会修改Properties内容，只是在已有对象上执行遍历。
void**state;state表示遍历状态游标。
调用者需要先定义一个void*变量，并初始化为NULL：
void*state=NULL;然后把它的地址传给pw_properties_iterate：
key=pw_properties_iterate(props,&state);第一次调用时，state内部值为NULL，函数从第一个属性开始遍历。后续每次调用时，函数根据state继续向后移动。返回NULL后表示遍历结束。
如果要重新开始遍历，需要重新把state设置为NULL。
返回值
成功时返回：
constchar*表示当前遍历到的属性key。
返回NULL表示没有更多属性可以遍历。它只是正常的遍历结束条件，不代表Properties对象一定异常。
需要注意，返回值只是key，不是value。要读取value，需要继续调用：
constchar*value=pw_properties_get(properties,key);返回的key和value通常由Properties内部持有，调用者不要直接free。如果要长期保存，应该复制字符串。
应用场景
第一类场景是打印PipeWire对象属性。
例如调试Stream创建参数、Node属性、Device属性时，可以通过pw_properties_iterate把所有key枚举出来，再配合pw_properties_get打印value。
第二类场景是复制属性。
当应用需要把一个Properties对象中的部分key/value复制到另一个Properties对象时，可以先遍历全部key，再按规则筛选和写入。
第三类场景是过滤属性。
例如只保留以media.、node.、application.、audio.开头的属性，用于构造更干净的Stream参数或调试输出。
第四类场景是诊断配置问题。
PipeWire很多行为由Properties驱动，例如media.class、media.type、node.name、node.description、application.name等。如果对象创建结果不符合预期，遍历Properties可以快速确认关键字段是否设置正确。
🌻3.调用流程剖析
🌻3.1核心步骤
1.调用者准备一个有效的pw_properties对象。
2.定义void*类型的state变量，并初始化为NULL。
3.调用pw_properties_iterate(properties,&state)。
4.函数根据state定位当前属性项。
5.如果找到属性项，返回当前属性的key。
6.调用者拿到key后，可以使用pw_properties_get(properties,key)读取value。
7.调用者处理key/value，例如打印、过滤、复制或转换。
8.再次调用pw_properties_iterate(properties,&state)，继续遍历下一个属性。
9.当函数返回NULL时，表示全部属性已经遍历完成。
10.遍历结束后，Properties对象仍然由原所有者管理，pw_properties_iterate不会释放它。
🌻3.2调用流程图
🌻3.3生命周期图
🌻4.实战应用案例
下面以“打印PipeWire对象Properties”为例，说明pw_properties_iterate的典型用法。
在PipeWire调试中，我们经常需要确认一个对象到底携带了哪些属性。例如Stream创建时传入的application.name、media.type、media.category、media.role、node.name是否正确。固定读取某几个字段不够通用，因此更适合使用遍历方式。
#include<stdio.h>#include<pipewire/pipewire.h>staticvoiddump_properties(conststructpw_properties*props){void*state=NULL;constchar*key;if(props==NULL)return;while((key=pw_properties_iterate(props,&state))!=NULL){constchar*value;value=pw_properties_get(props,key);printf("%s = %s\n",key,value?value:"");}}这个函数的关键点不在printf，而在state的使用方式。
void*state=NULL;state必须在第一次遍历前初始化为NULL。它表示当前遍历位置，由pw_properties_iterate内部更新。调用者不需要解析state的内容，也不应该修改它。
while((key=pw_properties_iterate(props,&state))!=NULL)这个循环每次取出一个key。只要返回值不是NULL，就说明当前还有属性可以处理。返回NULL后，遍历结束。
value=pw_properties_get(props,key);pw_properties_iterate只返回key，不返回value。因此读取value时必须再调用pw_properties_get。
下面是一个更贴近实际工程的例子：只复制以media.和node.开头的属性。
#include<string.h>#include<pipewire/pipewire.h>staticintstarts_with(constchar*s,constchar*prefix){returnstrncmp(s,prefix,strlen(prefix))==0;}staticstructpw_properties*copy_media_node_properties(conststructpw_properties*src){structpw_properties*dst;void*state=NULL;constchar*key;if(src==NULL)returnNULL;dst=pw_properties_new(NULL,NULL);if(dst==NULL)returnNULL;while((key=pw_properties_iterate(src,&state))!=NULL){constchar*value;if(!starts_with(key,"media.")&&!starts_with(key,"node."))continue;value=pw_properties_get(src,key);if(value!=NULL)pw_properties_set(dst,key,value);}returndst;}这个例子体现了pw_properties_iterate在工程中的一个常见用途：从一个完整Properties对象中筛选出业务真正需要的字段。
在PipeWire开发中，Properties经常既包含框架字段，也包含应用字段。直接整体复制可能会带来无关参数，甚至覆盖目标对象已有配置。通过遍历加过滤，可以把属性传递控制得更精确。
使用pw_properties_iterate时，要注意四个细节。
第一，state要独立使用。一次遍历对应一个state变量。嵌套遍历或多轮遍历时，不要复用同一个未重置的state。
第二，返回NULL只是遍历结束。不要把它简单理解为错误。
第三，遍历期间不要随意修改同一个Properties对象。尤其不要一边遍历一边删除当前对象中的属性，否则容易造成遍历状态不符合预期。
第四，不要长期保存返回的key指针。如果后续Properties被释放或修改，内部字符串指针可能失效。需要长期使用时，应主动复制key和value。
🌻5.一句话总结
pw_properties_iterate是PipeWire Properties API中的属性遍历接口：它通过调用者维护的state游标逐个返回key，适合调试、打印、复制和过滤Properties内容，读取value时需要配合pw_properties_get使用。