简介：CSDN博客专家、《Android系统多媒体进阶实战》作者

博主新书推荐：《Android系统多媒体进阶实战》🚀
Android Audio工程师专栏地址：Audio工程师进阶系列【原创干货持续更新中……】🚀
Android多媒体专栏地址：多媒体系统工程师系列【原创干货持续更新中……】🚀
专题一 二：AAOS车载系统+AOSP14系统攻城狮入门视频实战课🚀
专题三：Android14 Binder之HIDL与AIDL通信实战课🚀
专题四：Android15快速自定义与集成音效实战课🚀
专题五：Android15音频策略实战课🚀
专题六：Android15音频性能实战课(无声/杂音/断音/爆音实战案例)🚀

人生格言：人生从来没有捷径，只有行动才是治疗恐惧和懒惰的唯一良药.

🌻1.前言

本篇目的：

Linux PipeWire深度解析之pw_properties_add调用流程与实战。

要点概括

• 核心功能：把一个spa_dict中的属性追加到已有pw_properties中，只添加目标集合中尚不存在的key。

• 工作机制：遍历输入dict，对每个key检查目标properties是否已有该key；不存在则复制key/value并写入，已存在则保持原值不变。

• 典型用途：合并默认属性、补充对象创建参数、为Context、Stream、Module、Node等对象构造最终属性集合。

pw_properties_add的本质是“补充属性”，不是“覆盖属性”。它适合把一组默认配置或附加属性填入目标properties，但不会破坏目标对象里已经存在的属性。

它和pw_properties_update的区别非常关键。pw_properties_update用于更新属性，输入dict中的新值会覆盖已有key；而pw_properties_add只添加缺失key，已有key保持不变。

它和pw_properties_set也不同。pw_properties_set面向单个key/value操作；pw_properties_add面向一组spa_dict批量合并。它和pw_properties_add_keys也不同，add_keys只添加指定key列表中的属性，而pw_properties_add会遍历整个dict。

因此，pw_properties_add适合用在“默认值兜底”和“非破坏性合并”场景，而不适合用来强制修改已有属性。

🌻2.应用场景与用法

pw_properties_add

是PipeWireProperties API中用于向已有属性集合补充缺失key/value的接口。

它处在PipeWire对象创建前的属性准备阶段。PipeWire中的很多对象都会携带属性，例如Context属性、Module属性、Stream属性、Node属性、Device属性等。应用或模块通常会先创建一个pw_properties对象，再把来自配置文件、默认参数、外部dict或业务逻辑的属性合并进去。

pw_properties_add用于把dict中尚不存在于目标properties里的属性追加进去。

函数原型

intpw_properties_add(structpw_properties*oldprops,conststructspa_dict*dict);

参数说明

structpw_properties*oldprops;

oldprops表示目标属性集合。

该对象是被修改的一方。函数会检查dict中的每个key是否已经存在于oldprops中。如果不存在，就把该key/value添加到oldprops中；如果已经存在，则保留oldprops中的原值。

conststructspa_dict*dict;

dict表示输入属性字典。

它是属性来源，不是最终持有者。函数只从dict中读取key/value，并把符合条件的属性复制到oldprops中。调用完成后，目标properties拥有新增属性的生命周期，dict仍然由原调用方管理。

返回值

返回值类型为：

int

返回值表示成功添加到oldprops中的属性数量。

如果返回0，表示dict中的key在oldprops中都已经存在，或者没有可新增的属性。返回0不一定是错误，它通常表示本次合并没有产生变化。

应用场景

第一类场景是合并默认属性。

模块或应用创建对象时，通常会先准备一组业务属性，再追加一组默认属性。此时使用pw_properties_add可以保证业务属性优先级更高，默认属性只在缺失时补充。

第二类场景是创建PipeWire对象前整理参数。

例如创建Stream、加载Module、创建Context或构造Node前，可能需要把配置文件属性、环境属性、用户传入属性合并成一个最终properties。pw_properties_add适合做非破坏性合并。

第三类场景是模块内部属性继承。

模块可能从外部传入一个spa_dict，再把其中没有被本地配置覆盖的属性补充到对象属性中。这样既能保留本地显式配置，又能继承上层默认配置。

第四类场景是避免误覆盖关键属性。

有些key可能已经被前面逻辑明确设置，例如node.name、media.class、application.name、stream.name等。使用pw_properties_add可以避免后续默认属性覆盖这些关键值。

🌻3.调用流程剖析

🌻3.1核心步骤

1.调用方准备目标pw_properties对象。

2.调用方准备输入spa_dict，dict中包含待补充的key/value属性。

3.调用pw_properties_add(oldprops,dict)。

4.函数遍历dict中的每个spa_dict_item。

5.对每个item取出key和value。

6.检查oldprops中是否已经存在相同key。

7.如果key已经存在，保持oldprops中的原值不变。

8.如果key不存在，把该key/value复制并添加到oldprops中。

9.每成功添加一个新属性，内部新增计数加1。

10.遍历完成后返回新增属性数量。

🌻3.2调用流程图

🌻3.3生命周期图

🌻4.实战应用案例

下面以“Stream属性默认值补充”为例，说明pw_properties_add的实际使用方式。

假设应用已经显式设置了stream.name和media.type，同时希望补充一组默认属性，但不能覆盖应用已经设置的属性。

#include<pipewire/pipewire.h>staticstructpw_properties*create_stream_props(void){structpw_properties*props;props=pw_properties_new(PW_KEY_MEDIA_TYPE,"Audio",PW_KEY_MEDIA_CATEGORY,"Playback",PW_KEY_MEDIA_ROLE,"Music",PW_KEY_STREAM_NAME,"user-music-stream",NULL);returnprops;}

上面这组属性可以理解为应用自己的显式配置。它表示这是一个音频播放流，角色是音乐，Stream名称由应用指定。

接下来准备一组默认属性：

staticconststructspa_dict_itemdefault_items[]={{PW_KEY_APP_NAME,"pipewire-demo"},{PW_KEY_MEDIA_TYPE,"Audio"},{PW_KEY_MEDIA_CATEGORY,"Playback"},{PW_KEY_NODE_NAME,"demo-node"},};staticconststructspa_dictdefault_dict={SPA_DICT_FLAG_SORTED,SPA_N_ELEMENTS(default_items),default_items,};

这里default_dict中也包含media.type和media.category。由于props里已经有这两个key，pw_properties_add不会覆盖它们。

staticvoidadd_default_props(structpw_properties*props){intadded;added=pw_properties_add(props,&default_dict);(void)added;}

调用完成后，props中的属性集合会变成：

media.type=Audio media.category=Playback media.role=Music stream.name=user-music-stream application.name=pipewire-demo node.name=demo-node

其中media.type和media.category来自原始props，不会被default_dict重新覆盖。application.name和node.name原来不存在，因此会被添加进去。

这就是pw_properties_add最典型的工程价值：让“显式配置”优先，让“默认配置”兜底。

如果把这里换成pw_properties_update，语义就变了。update会把dict中的同名key更新到props中，更适合“后来的配置覆盖前面的配置”这种场景。

staticvoidupdate_props(structpw_properties*props){pw_properties_update(props,&default_dict);}

在工程代码中，add和update不能随便互换。

如果你的目标是“缺什么补什么”，使用pw_properties_add。

如果你的目标是“以新配置为准”，使用pw_properties_update。

如果你的目标是“只改一个key”，使用pw_properties_set。

如果你的目标是“只添加指定key集合”，使用pw_properties_add_keys。

再看一个更贴近PipeWire对象创建的场景：

structstream_config{constchar*app_name;constchar*node_name;constchar*stream_name;};staticstructpw_properties*build_playback_properties(conststructstream_config*config,conststructspa_dict*extra){structpw_properties*props;props=pw_properties_new(PW_KEY_MEDIA_TYPE,"Audio",PW_KEY_MEDIA_CATEGORY,"Playback",PW_KEY_MEDIA_ROLE,"Music",PW_KEY_STREAM_NAME,config->stream_name,PW_KEY_NODE_NAME,config->node_name,PW_KEY_APP_NAME,config->app_name,NULL);if(extra!=NULL)pw_properties_add(props,extra);returnprops;}

这个函数的关键点是：config中的属性是主配置，extra只是补充配置。extra中如果包含同名key，不会覆盖config已经设置的值。

这种写法适合封装库、音频中间件、测试工具和模块代码。上层调用者可以传入额外属性，但不能意外覆盖核心属性。

如果业务确实允许外部属性覆盖默认值，顺序应反过来设计，或者直接使用pw_properties_update。属性合并的接口选择，本质上就是属性优先级设计。

🌻5.一句话总结

pw_properties_add是PipeWireProperties的非破坏性批量合并接口：它只把spa_dict中目标properties尚不存在的key/value添加进去，适合做默认属性补充和对象创建前的属性兜底。