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

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

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

🌻1.前言

本篇目的：

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

要点概括

• 核心功能：从pw_properties中按key读取字符串属性，并转换为int32_t整数值。

• 工作机制：先查找key对应的value字符串，再使用SPA字符串转换工具完成int32_t解析，成功后写入调用方传入的value指针。

• 典型用途：读取PipeWire配置项、模块参数、节点属性、运行期属性中的整型字段。

pw_properties_fetch_int32的本质是“带类型校验的属性读取函数”。PipeWire很多属性都以key/value字符串形式保存，哪怕配置里写的是数字，进入pw_properties后通常仍然是字符串。该函数的价值就是把字符串属性安全转换为int32_t，并通过返回值告诉调用方读取是否成功。

它不是属性设置函数，不会修改properties中的原始key/value内容。它也不是默认值读取函数，失败时不会自动返回默认值。调用方必须根据返回值决定是否使用默认值、报错、忽略或走降级逻辑。

它和pw_properties_get的区别是：pw_properties_get只返回constchar*字符串，不负责类型转换。它和pw_properties_get_int32的区别是：pw_properties_get_int32内部会带默认值语义，适合“拿不到就用默认值”的场景；pw_properties_fetch_int32适合“我要知道到底是成功、缺失，还是格式错误”的场景。

🌻2.应用场景与用法

pw_properties_fetch_int32

是PipeWirePropertiesAPI中用于读取int32_t类型属性的接口。

它位于PipeWire属性系统的读取路径中。PipeWire的Core、Context、Module、Node、Device、Stream等对象都可能携带properties。properties本质上是一组key/value字典，value通常以字符串保存。当上层逻辑需要把某个属性当作int32_t使用时，就可以通过pw_properties_fetch_int32完成读取和类型转换。

pw_properties_fetch_int32用于从pw_properties中读取指定key对应的int32_t数值。

函数原型

intpw_properties_fetch_int32(conststructpw_properties*properties,constchar*key,int32_t*value);

参数说明

conststructpw_properties*properties;

properties表示要读取的PipeWire属性集合。

它通常来自pw_properties_new、pw_properties_copy、pw_properties_new_dict、对象事件回调中的props，或者模块、节点、流对象保存的属性字典。

constchar*key;

key表示要读取的属性名。

例如"nice.level"、"node.priority.driver"、"priority.session"这类属性都可能以字符串形式保存在properties中。

int32_t*value;

value表示输出参数。

函数读取成功时，会把转换后的int32_t结果写入*value。读取失败时，*value保持原值不变，因此调用前可以先给value设置一个默认值，再根据返回值决定是否覆盖或继续使用默认值。

返回值

返回0表示读取成功。

返回负值表示失败，常见失败路径包括：

-ENOENT

表示指定key不存在。

-EINVAL

表示key存在，但value字符串不能转换为合法int32_t。例如字符串为空、包含非法字符，或者数值超出int32_t范围。

该函数的返回值不是读取到的整数本身。真正的整数结果通过第三个参数value返回。

应用场景

第一类场景是读取模块配置。

PipeWire模块启动时可能从配置文件或加载参数中获得properties。模块内部需要读取某个整型参数时，可以用pw_properties_fetch_int32区分“没有配置”和“配置了但格式错误”。

第二类场景是读取节点优先级。

PipeWire对象属性中经常包含优先级、权重、调度相关参数。这类字段在properties里通常是字符串，但策略逻辑需要把它们作为整数比较。

第三类场景是读取带符号配置项。

例如nice.level这类值可能为负数，使用int32_t比uint32_t更合适。pw_properties_fetch_int32可以保留负数语义，避免把负值误当成无符号整数。

第四类场景是实现严格校验。

如果只是“没有就用默认值”，可以使用pw_properties_get_int32。如果需要明确判断key是否缺失、格式是否错误，就应该使用pw_properties_fetch_int32。

🌻3.调用流程剖析

🌻3.1核心步骤

1.调用方准备pw_properties对象。

2.调用方准备要读取的key。

3.调用方准备int32_t变量，并把变量地址传给value参数。

4.pw_properties_fetch_int32内部按key查找value字符串。

5.如果key不存在，函数返回-ENOENT。

6.如果key存在，函数取得对应字符串。

7.函数尝试把字符串转换为int32_t。

8.如果字符串格式非法或数值越界，函数返回-EINVAL。

9.如果转换成功，函数把结果写入*value。

10.函数返回0，调用方使用读取到的int32_t结果。

🌻3.2调用流程图

🌻3.3生命周期图

🌻4.实战应用案例

下面以“读取节点调度相关属性”为例，说明pw_properties_fetch_int32的真实用法。

假设一个PipeWire模块或客户端创建了properties，里面保存了节点优先级和nice级别。properties中的value虽然看起来是数字，但实际保存形式仍然是字符串。

#include<errno.h>#include<stdint.h>#include<pipewire/pipewire.h>structnode_policy{int32_tpriority_driver;int32_tnice_level;};staticintload_node_policy(conststructpw_properties*props,structnode_policy*policy){intres;int32_tvalue;policy->priority_driver=0;policy->nice_level=0;value=policy->priority_driver;res=pw_properties_fetch_int32(props,"node.priority.driver",&value);if(res==0){policy->priority_driver=value;}elseif(res==-ENOENT){policy->priority_driver=0;}else{returnres;}value=policy->nice_level;res=pw_properties_fetch_int32(props,"nice.level",&value);if(res==0){policy->nice_level=value;}elseif(res==-ENOENT){policy->nice_level=0;}else{returnres;}return0;}

这个案例体现了pw_properties_fetch_int32最重要的工程价值：调用方可以区分三种情况。

第一种是读取成功。

说明key存在，并且value可以转换为int32_t。此时可以放心使用转换后的数值。

第二种是key不存在。

这通常不是严重错误，可能表示配置没有显式指定。调用方可以使用默认值。

第三种是key存在但格式错误。

这通常比key缺失更严重。因为用户或配置文件明确写了这个字段，但内容不能被解释为int32_t。对于模块加载、策略初始化、设备参数解析等场景，这类错误应该被暴露出来，而不是静默吞掉。

如果只是想快速读取一个带默认值的int32_t，可以使用更短的写法：

int32_tpriority;priority=pw_properties_get_int32(props,"node.priority.driver",0);

这种写法简洁，但它隐藏了失败原因。key不存在、格式错误、转换失败，最终都会落到默认值语义里。对于普通默认配置读取可以接受，但对于严格参数校验不够清晰。

因此，工程上可以按下面原则选择：

/* 需要知道失败原因 */pw_properties_fetch_int32(props,key,&value);/* 只关心结果，没有就用默认值 */pw_properties_get_int32(props,key,deflt);/* 只想拿原始字符串 */pw_properties_get(props,key);

在PipeWire源码阅读中看到fetch类函数时，要注意它们表达的是“读取+转换+错误报告”。它们不是简单getter，而是属性系统和类型系统之间的一层边界检查。

再看一个更贴近模块参数解析的写法：

staticintread_required_int32(conststructpw_properties*props,constchar*key,int32_t*out){intres;res=pw_properties_fetch_int32(props,key,out);if(res<0)returnres;return0;}

这个函数适合读取必填参数。只要key不存在或格式错误，就把错误返回给上层。上层可以决定是拒绝加载模块、禁用某个功能，还是打印错误日志后继续运行。

如果参数是可选的，可以封装成带默认值的版本：

staticint32_tread_optional_int32(conststructpw_properties*props,constchar*key,int32_tdeflt){int32_tvalue=deflt;pw_properties_fetch_int32(props,key,&value);returnvalue;}

这个封装和pw_properties_get_int32语义接近，但它保留了fetch接口“失败不修改value”的特点。调用前把value设置为默认值，读取成功后覆盖，读取失败则继续使用原值。

实际项目中，建议把属性读取分成两层：

第一层负责读取和校验。

第二层负责把读取到的值转换为业务策略。

不要在业务逻辑深处反复写字符串key，也不要在多个模块中重复解析同一个属性。这样可以减少属性名写错、默认值不一致、错误处理不统一的问题。

🌻5.一句话总结

pw_properties_fetch_int32是PipeWire属性系统中的int32_t读取接口：它从properties按key取出字符串属性，成功转换后写入*value，失败时返回负errno并保持输出值不变，适合需要严格区分“缺失”和“格式错误”的配置解析场景。