简介CSDN博客专家、《Android系统多媒体进阶实战》作者博主新书推荐《Android系统多媒体进阶实战》Android Audio工程师专栏地址Audio工程师进阶系列【原创干货持续更新中……】Android多媒体专栏地址多媒体系统工程师系列【原创干货持续更新中……】专题一 二AAOS车载系统AOSP14系统攻城狮入门视频实战课专题三Android14 Binder之HIDL与AIDL通信实战课专题四Android15快速自定义与集成音效实战课专题五Android15音频策略实战课专题六Android15音频性能实战课(无声/杂音/断音/爆音实战案例)人生格言人生从来没有捷径只有行动才是治疗恐惧和懒惰的唯一良药.更多原创,欢迎关注Android系统攻城狮文章目录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读取valuepw_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*变量并初始化为NULLvoid*stateNULL;然后把它的地址传给pw_properties_iteratekeypw_properties_iterate(props,state);第一次调用时state内部值为NULL函数从第一个属性开始遍历。后续每次调用时函数根据state继续向后移动。返回NULL后表示遍历结束。如果要重新开始遍历需要重新把state设置为NULL。返回值成功时返回constchar*表示当前遍历到的属性key。返回NULL表示没有更多属性可以遍历。它只是正常的遍历结束条件不代表Properties对象一定异常。需要注意返回值只是key不是value。要读取value需要继续调用constchar*valuepw_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是否正确。固定读取某几个字段不够通用因此更适合使用遍历方式。#includestdio.h#includepipewire/pipewire.hstaticvoiddump_properties(conststructpw_properties*props){void*stateNULL;constchar*key;if(propsNULL)return;while((keypw_properties_iterate(props,state))!NULL){constchar*value;valuepw_properties_get(props,key);printf(%s %s\n,key,value?value:);}}这个函数的关键点不在printf而在state的使用方式。void*stateNULL;state必须在第一次遍历前初始化为NULL。它表示当前遍历位置由pw_properties_iterate内部更新。调用者不需要解析state的内容也不应该修改它。while((keypw_properties_iterate(props,state))!NULL)这个循环每次取出一个key。只要返回值不是NULL就说明当前还有属性可以处理。返回NULL后遍历结束。valuepw_properties_get(props,key);pw_properties_iterate只返回key不返回value。因此读取value时必须再调用pw_properties_get。下面是一个更贴近实际工程的例子只复制以media.和node.开头的属性。#includestring.h#includepipewire/pipewire.hstaticintstarts_with(constchar*s,constchar*prefix){returnstrncmp(s,prefix,strlen(prefix))0;}staticstructpw_properties*copy_media_node_properties(conststructpw_properties*src){structpw_properties*dst;void*stateNULL;constchar*key;if(srcNULL)returnNULL;dstpw_properties_new(NULL,NULL);if(dstNULL)returnNULL;while((keypw_properties_iterate(src,state))!NULL){constchar*value;if(!starts_with(key,media.)!starts_with(key,node.))continue;valuepw_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使用。