简介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_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_dictdict中包含待补充的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同时希望补充一组默认属性但不能覆盖应用已经设置的属性。#includepipewire/pipewire.hstaticstructpw_properties*create_stream_props(void){structpw_properties*props;propspw_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里已经有这两个keypw_properties_add不会覆盖它们。staticvoidadd_default_props(structpw_properties*props){intadded;addedpw_properties_add(props,default_dict);(void)added;}调用完成后props中的属性集合会变成media.typeAudio media.categoryPlayback media.roleMusic stream.nameuser-music-stream application.namepipewire-demo node.namedemo-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;propspw_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添加进去适合做默认属性补充和对象创建前的属性兜底。