備信息提供者（DeviceInfoProvider）示例實現(xiàn)解析：FixedLabel、UserLabel、區(qū)域設(shè)置與日歷類型)
Matter SDK 設(shè)備信息提供者DeviceInfoProvider示例實現(xiàn)解析FixedLabel、UserLabel、區(qū)域設(shè)置與日歷類型【免費下載鏈接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.項目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip導(dǎo)讀本篇文章圍繞 examples/providers/README.md 展開深入解析 MatterConnected Home over IPCHIPSDK 中應(yīng)用專用 Providerprovider的示例實現(xiàn)機制。文章以 Device Info Provider 為主線完整介紹其職責邊界、兩個示例實現(xiàn)空實現(xiàn)版與 All-Clusters 常量版的代碼結(jié)構(gòu)與設(shè)計意圖、四個迭代器接口FixedLabel / UserLabel / SupportedLocales / SupportedCalendarTypes的底層語義、持久化存儲實現(xiàn)以及如何在真實應(yīng)用如 all-clusters-app中注冊使用。讀完本文你將掌握如何為自己的 Matter 產(chǎn)品自定義設(shè)備信息提供者并理解 Matter 1.5 之后對示例默認值采取的安全拒絕策略。1. Provider 目錄的定位應(yīng)用專用的可替換實現(xiàn)examples/providers/README.md 開篇就明確了該目錄的核心定位This folder contains example implementations of providers that are generally application-specific. Final applications should generally have their own implementations of these.即examples/providers/存放的是**應(yīng)用專用application-specific**的 Provider 示例實現(xiàn)。所謂 Provider在 Matter SDK 中指的是向協(xié)議棧上層尤其是各類 Cluster提供業(yè)務(wù)數(shù)據(jù)的一組可插拔接口。最終產(chǎn)品不應(yīng)直接復(fù)用這些示例代碼而應(yīng)基于它們派生并定制自己的實現(xiàn)。從目錄結(jié)構(gòu)看該目錄共包含 6 個文件文件作用DeviceInfoProviderImpl.h / .cpp空實現(xiàn)版 Device Info Provider安全默認AllClustersExampleDeviceInfoProviderImpl.h / .cpp帶常量數(shù)據(jù)的 All-Clusters 示例版BUILD.gn兩個靜態(tài)庫目標的 GN 構(gòu)建配置README.md目錄說明本文的關(guān)聯(lián)文檔其中 README 明確點名的Device Info Provider是目錄中唯一被詳細介紹的主題其職責是Supports device-specific information like labels, locales and calendar types.即向設(shè)備端 Cluster 提供**標簽labels、區(qū)域設(shè)置locales和日歷類型calendar types**等設(shè)備特有信息。這三類數(shù)據(jù)分別對應(yīng) Matter 規(guī)范中的 Fixed Label、User Label、Localization Configuration 和 Time Format Localization 等 Cluster。2. 核心接口DeviceInfoProvider 抽象基類在深入示例實現(xiàn)之前需要先理解 SDK 定義的抽象基類 src/include/platform/DeviceInfoProvider.h。它是所有設(shè)備信息 Provider 的公共契約位于chip::DeviceLayer命名空間下。2.1 四個純虛迭代器接口基類定義了四個必須實現(xiàn)的純虛迭代器 0分別覆蓋 README 中提到的 labels、locales、calendar types純虛方法返回迭代器類型數(shù)據(jù)來源 Cluster元素類型IterateFixedLabel(EndpointId)FixedLabelIterator *Fixed Label固定標簽FixedLabelTypeIterateUserLabel(EndpointId)UserLabelIterator *User Label用戶標簽UserLabelTypeIterateSupportedLocales()SupportedLocalesIterator *Localization Configuration區(qū)域配置CharSpanIterateSupportedCalendarTypes()SupportedCalendarTypesIterator *Time Format Localization時間格式本地化CalendarType所有迭代器都基于同一個模板IteratorT定義其協(xié)議非常簡單template typename T class Iterator { public: virtual size_t Count() 0; // 返回總共將迭代的條目數(shù) virtual bool Next(T item) 0; // 成功取回下一個元素返回 true無更多條目返回 false virtual void Release() 0; // 釋放迭代器分配的內(nèi)存指針離開作用域前必須調(diào)用 };其中元素類型在基類中做了別名綁定using FixedLabelType app::Clusters::FixedLabel::Structs::LabelStruct::Type; using UserLabelType app::Clusters::UserLabel::Structs::LabelStruct::Type; using CalendarType app::Clusters::TimeFormatLocalization::CalendarTypeEnum;2.2 平臺側(cè)定義的常量約束基類頭部同時定義了 Provider 實現(xiàn)需要遵守的容量上限src/include/platform/DeviceInfoProvider.hstatic constexpr size_t kMaxUserLabelListLength 4; // 每個 Endpoint 的用戶標簽列表最大 4 條 static constexpr size_t kMaxLabelNameLength 16; // 標簽名最大 16 字節(jié) static constexpr size_t kMaxLabelValueLength 16; // 標簽值最大 16 字節(jié) static constexpr size_t kMaxActiveLocaleLength 35; // 活動區(qū)域設(shè)置串最大 35 字節(jié)這些常量直接決定了示例實現(xiàn)中內(nèi)部緩沖區(qū)的尺寸詳見第 4 節(jié)。2.3 User Label 的寫操作與全局 Provider 注冊除了讀側(cè)迭代器基類還向派生類暴露了一組protected 虛函數(shù)用于對 User Label 列表做持久化讀寫SetUserLabelAt(endpoint, index, userLabel)設(shè)置指定索引處的標簽DeleteUserLabelAt(endpoint, index)刪除指定索引處的標簽SetUserLabelLength(endpoint, val)/GetUserLabelLength(endpoint, val)讀寫標簽列表長度。公共的列表級操作SetUserLabelList、ClearUserLabelList、AppendUserLabel則由基類在 src/platform/DeviceInfoProvider.cpp 中基于上述原語組合實現(xiàn)例如AppendUserLabel會先讀取當前長度、校驗不超過kMaxUserLabelListLength否則返回CHIP_ERROR_NO_MEMORY再依次寫入長度與新標簽。全局訪問通過GetDeviceInfoProvider()/SetDeviceInfoProvider(DeviceInfoProvider *)完成兩者維護一個進程級單例指針src/platform/DeviceInfoProvider.cpp。3. 兩個示例實現(xiàn)的設(shè)計意圖空實現(xiàn) vs 常量數(shù)據(jù)目錄中提供了兩套風格截然不同的實現(xiàn)體現(xiàn)了不同的使用場景DeviceInfoProviderImpl空實現(xiàn)所有迭代器返回空數(shù)據(jù)是Matter 1.5 之后引入的安全默認AllClustersExampleDeviceInfoProviderImpl常量實現(xiàn)填充硬編碼的示例值專供 all-clusters 類測試應(yīng)用使用。3.1 空實現(xiàn)版防止壞數(shù)據(jù)泄漏進產(chǎn)品在 DeviceInfoProviderImpl.h 的頭部源碼用四個感嘆號標注了非常醒目的 WARNINGDO NOT USE THESE DEFAULT IMPLEMENTATIONS WITH DEFAULT VALUES IN PRODUCTION PRODUCTS WITHOUT AUDITING THEM! ... Here, all providers have empty implementations to force empty lists which prevent bad values from leaking into products like happened before Matter 1.5.這段話傳遞了兩個關(guān)鍵信息歷史教訓(xùn)Matter 1.5 之前示例默認值曾直接泄漏到產(chǎn)品中設(shè)計對策此后默認示例強制返回空列表如果產(chǎn)品確實要用 FixedLabel、LocalizationConfiguration、Time Format Localization 等 Cluster必須重新實現(xiàn) Provider且填入的值必須經(jīng)過正確性審查。具體到代碼DeviceInfoProviderImpl.cppDeviceInfoProvider::FixedLabelIterator * DeviceInfoProviderImpl::IterateFixedLabel(EndpointId endpoint) { // We dont include fixed label data in this sample one. Returning nullptr returns empty list. (void) endpoint; return nullptr; }IterateFixedLabel直接返回nullptr按照基類文檔約定returns nullptr if no iterator instances are available調(diào)用方會將其解釋為空列表。3.2 常量實現(xiàn)版面向 all-clusters 測試AllClustersExampleDeviceInfoProviderImpl則為測試目的填充了經(jīng)過審查的常量值其頭部警告措辭相對緩和但也明確指出FixedLabel cluster, if used, should have values that have been vetted for correctness in the productAllClustersExampleDeviceInfoProviderImpl.cpp。兩套實現(xiàn)的差異匯總維度DeviceInfoProviderImplAllClustersExampleDeviceInfoProviderImplFixedLabel返回nullptr空列表返回 1 條硬編碼標簽directionup/downUserLabel持久化存儲讀寫持久化存儲讀寫SupportedLocales2 個en-US、en-GB8 個en-US、de-DE、fr-FR、en-GB、es-ES、zh-CN、it-IT、ja-JPSupportedCalendarTypes1 個kGregorian1 個kGregorian4. 源碼級剖析四個迭代器的完整實現(xiàn)下面以AllClustersExampleDeviceInfoProviderImpl為主要樣本逐個剖析四個迭代器的實現(xiàn)空實現(xiàn)版邏輯相同只是數(shù)據(jù)量為 0 或nullptr。4.1 FixedLabelIteratorImpl按 Endpoint 區(qū)分的固定標簽DeviceInfoProvider::FixedLabelIterator * AllClustersExampleDeviceInfoProviderImpl::IterateFixedLabel(EndpointId endpoint) { return chip::Platform::NewFixedLabelIteratorImpl(endpoint); }迭代器在堆上通過chip::Platform::New分配Release()時通過chip::Platform::Delete(this)釋放這與基類必須調(diào)用 Release() 釋放內(nèi)存的契約一致。FixedLabelIteratorImpl::Next()的實現(xiàn)展示了按 Endpoint 返回不同值的手法AllClustersExampleDeviceInfoProviderImpl.cppcase 0: output.label direction_span; if (mEndpoint 1) { output.value up_span; } else { output.value down_span; } break;即固定標簽名direction對 Endpoint 1 返回up其余 Endpoint 返回down。源碼注釋還提醒真實產(chǎn)品中這些值很可能需要按 Endpoint 動態(tài)生成此時應(yīng)把 span 指向正確的 buffersize而非直接使用const char*支撐的CharSpan。4.2 UserLabelIteratorImpl基于持久化存儲的讀寫User Label 與前兩者最大的不同是可寫——用戶或控制器可以通過 Cluster 命令增刪標簽。因此示例實現(xiàn)將其落到PersistentStorageDelegate上。寫入側(cè)SetUserLabelAt把標簽序列化為 TLV 結(jié)構(gòu)后按 key 存儲AllClustersExampleDeviceInfoProviderImpl.cppuint8_t buf[UserLabelTLVMaxSize()]; TLV::TLVWriter writer; writer.Init(buf); TLV::TLVType outerType; ReturnErrorOnFailure(writer.StartContainer(TLV::AnonymousTag(), TLV::kTLVType_Structure, outerType)); ReturnErrorOnFailure(writer.PutString(kLabelNameTag, userLabel.label)); // ContextTag(0) ReturnErrorOnFailure(writer.PutString(kLabelValueTag, userLabel.value)); // ContextTag(1) ReturnErrorOnFailure(writer.EndContainer(outerType)); return mStorage-SyncSetKeyValue( DefaultStorageKeyAllocator::UserLabelIndexKey(endpoint, static_castuint32_t(index)).KeyName(), buf, static_castuint16_t(writer.GetLengthWritten()));其中kLabelNameTag/kLabelValueTag分別是TLV::ContextTag(0)/ContextTag(1)緩沖區(qū)大小由UserLabelTLVMaxSize()決定即TLV::EstimateStructOverhead(kMaxLabelNameLength, kMaxLabelValueLength)16 字節(jié) name 16 字節(jié) value TLV 結(jié)構(gòu)開銷存儲 key 由DefaultStorageKeyAllocator::UserLabelLengthKey(endpoint)長度與UserLabelIndexKey(endpoint, index)條目統(tǒng)一生成。讀取側(cè)UserLabelIteratorImpl::Next()先從存儲讀出 TLV 字節(jié)再用TLV::ContiguousBufferTLVReader逐字段解析最終把 label/value 拷貝進內(nèi)部緩沖后以CharSpan返回Platform::CopyString(mUserLabelNameBuf, label); Platform::CopyString(mUserLabelValueBuf, value); output.label CharSpan::fromCharString(mUserLabelNameBuf); output.value CharSpan::fromCharString(mUserLabelValueBuf);迭代器的Count()與Next()均基于構(gòu)造時讀到的列表長度mTotal工作超出范圍即返回false結(jié)束迭代。兩個示例實現(xiàn)空實現(xiàn)版與常量版的 User Label 讀寫邏輯完全一致因為這一部分與示例數(shù)據(jù)無關(guān)屬于通用存儲邏輯。4.3 SupportedLocalesIteratorImpl區(qū)域設(shè)置清單空實現(xiàn)版硬編碼 2 個區(qū)域DeviceInfoProviderImpl.cppstatic const char * kAllSupportedLocales[kNumSupportedLocales] { en-US, en-GB };常量實現(xiàn)版擴展為 8 個常用區(qū)域AllClustersExampleDeviceInfoProviderImpl.cppstatic const char * kAllSupportedLocales[kNumSupportedLocales] { en-US, de-DE, fr-FR, en-GB, es-ES, zh-CN, it-IT, ja-JP };區(qū)域字符串是 BCP-47 風格的語言-國家/地區(qū)格式直接對應(yīng) Localization Configuration Cluster 中SupportedLocales屬性的枚舉值。4.4 SupportedCalendarTypesIteratorImpl日歷類型清單兩套實現(xiàn)都只支持一種日歷——公歷static const CalendarType kAllSupportedCalendarTypes[kNumSupportedCalendarTypes] { app::Clusters::TimeFormatLocalization::CalendarTypeEnum::kGregorian };該枚舉值來自TimeFormatLocalizationCluster其迭代器元素類型是CalendarType枚舉與區(qū)域設(shè)置迭代器返回的CharSpan不同。5. 構(gòu)建配置兩個靜態(tài)庫目標examples/providers/BUILD.gn 將兩套實現(xiàn)分別封裝為靜態(tài)庫static_library(device_info_provider_please_do_not_reuse_as_is) { output_name libMatterDeviceInfoProviderExample sources [ DeviceInfoProviderImpl.cpp, DeviceInfoProviderImpl.h, ] public_deps [ ${chip_root}/src/lib/support, ${chip_root}/src/platform, ] public_configs [ :include_providers_dir ] } static_library(all_clusters_device_info_provider) { output_name libMatterAllClustersDeviceInfoProviderExample sources [ AllClustersExampleDeviceInfoProviderImpl.cpp, AllClustersExampleDeviceInfoProviderImpl.h, ] public_deps [ ${chip_root}/src/lib/support, ${chip_root}/src/platform, ] public_configs [ :include_providers_dir ] }值得注意的命名細節(jié)第一個目標名device_info_provider_please_do_not_reuse_as_is本身就攜帶了請勿照搬復(fù)用的語義與源碼頭部的 WARNING 相呼應(yīng)include_providers_dirconfig 同時把examples根目錄加入 include 路徑因此下游可以通過#include providers/AllClustersExampleDeviceInfoProviderImpl.h這種形如providers/...的頭文件引用方式引入實現(xiàn)。兩個庫都依賴${chip_root}/src/lib/support與${chip_root}/src/platform因為它們使用了DefaultStorageKeyAllocator、TLV、Platform內(nèi)存管理等 SDK 基礎(chǔ)設(shè)施。6. 在真實應(yīng)用中注冊使用all-clusters-app 實例示例 Provider 在 all-clusters-app 的 fuzzing 入口中有完整使用示范examples/all-clusters-app/linux/fuzzing-main.cpp#include providers/AllClustersExampleDeviceInfoProviderImpl.h // ... chip::DeviceLayer::AllClustersExampleDeviceInfoProviderImpl gAllClustersExampleDeviceInfoProvider; // ... DeviceLayer::SetDeviceInfoProvider(gAllClustersExampleDeviceInfoProvider);完整的接入流程是實例化在全局或初始化階段構(gòu)造 Provider 子類對象設(shè)置存儲委托調(diào)用SetStorageDelegate(PersistentStorageDelegate *)注入非易失存儲基類SetStorageDelegate對空指針會VerifyOrDiesrc/platform/DeviceInfoProvider.cppUser Label 的持久化讀寫依賴該存儲注冊全局實例調(diào)用SetDeviceInfoProvider(provider)掛入DeviceLayer的全局指針協(xié)議棧使用此后 Fixed Label、User Label、Localization Configuration、Time Format Localization 等 Cluster 的數(shù)據(jù)讀寫都會路由到該 Provider。這四條步驟同樣適用于任何自定義 Provider繼承DeviceInfoProvider→ 實現(xiàn)四個迭代器與四個 User Label 原語 → 注入存儲 → 全局注冊。7. 面向產(chǎn)品開發(fā)者的最佳實踐綜合 README 的定位說明與源碼中的 WARNING可以總結(jié)出以下實踐要點示例僅供學(xué)習與測試examples/providers/中的實現(xiàn)是應(yīng)用專用的示例最終產(chǎn)品應(yīng)擁有自己的實現(xiàn)空實現(xiàn)是安全基線Matter 1.5 之后默認空實現(xiàn)刻意返回空列表避免未審查的示例值進入產(chǎn)品如果你確實啟用 FixedLabel、LocalizationConfiguration、TimeFormatLocalization 等 Cluster務(wù)必重寫 Provider 并提供經(jīng)過驗證的值User Label 需要持久化該能力依賴PersistentStorageDelegate務(wù)必在注冊 Provider 前通過SetStorageDelegate注入有效存儲否則斷言失敗遵守容量約束標簽名與標簽值均不超過 16 字節(jié)、每 Endpoint 用戶標簽最多 4 條kMaxUserLabelListLength列表操作在超限時返回CHIP_ERROR_NO_MEMORY迭代器生命周期管理所有迭代器通過chip::Platform::New分配調(diào)用方必須在迭代結(jié)束后調(diào)用Release()且迭代期間不允許修改標簽數(shù)據(jù)。參考文件索引關(guān)聯(lián)文檔examples/providers/README.md空實現(xiàn)版DeviceInfoProviderImpl.h / DeviceInfoProviderImpl.cpp常量實現(xiàn)版AllClustersExampleDeviceInfoProviderImpl.h / AllClustersExampleDeviceInfoProviderImpl.cpp構(gòu)建配置examples/providers/BUILD.gn抽象基類src/include/platform/DeviceInfoProvider.h基類通用實現(xiàn)src/platform/DeviceInfoProvider.cpp應(yīng)用接入示例examples/all-clusters-app/linux/fuzzing-main.cpp【免費下載鏈接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.項目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Matter SDK 設(shè)備信息提供者（DeviceInfoProvider）示例實現(xiàn)解析：FixedLabel、UserLabel、區(qū)域設(shè)置與日歷類型
Matter SDK 設(shè)備信息提供者DeviceInfoProvider示例實現(xiàn)解析FixedLabel、UserLabel、區(qū)域設(shè)置與日歷類型【免費下載鏈接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.項目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip導(dǎo)讀本篇文章圍繞 examples/providers/README.md 展開深入解析 MatterConnected Home over IPCHIPSDK 中應(yīng)用專用 Providerprovider的示例實現(xiàn)機制。文章以 Device Info Provider 為主線完整介紹其職責邊界、兩個示例實現(xiàn)空實現(xiàn)版與 All-Clusters 常量版的代碼結(jié)構(gòu)與設(shè)計意圖、四個迭代器接口FixedLabel / UserLabel / SupportedLocales / SupportedCalendarTypes的底層語義、持久化存儲實現(xiàn)以及如何在真實應(yīng)用如 all-clusters-app中注冊使用。讀完本文你將掌握如何為自己的 Matter 產(chǎn)品自定義設(shè)備信息提供者并理解 Matter 1.5 之后對示例默認值采取的安全拒絕策略。1. Provider 目錄的定位應(yīng)用專用的可替換實現(xiàn)examples/providers/README.md 開篇就明確了該目錄的核心定位This folder contains example implementations of providers that are generally application-specific. Final applications should generally have their own implementations of these.即examples/providers/存放的是**應(yīng)用專用application-specific**的 Provider 示例實現(xiàn)。所謂 Provider在 Matter SDK 中指的是向協(xié)議棧上層尤其是各類 Cluster提供業(yè)務(wù)數(shù)據(jù)的一組可插拔接口。最終產(chǎn)品不應(yīng)直接復(fù)用這些示例代碼而應(yīng)基于它們派生并定制自己的實現(xiàn)。從目錄結(jié)構(gòu)看該目錄共包含 6 個文件文件作用DeviceInfoProviderImpl.h / .cpp空實現(xiàn)版 Device Info Provider安全默認AllClustersExampleDeviceInfoProviderImpl.h / .cpp帶常量數(shù)據(jù)的 All-Clusters 示例版BUILD.gn兩個靜態(tài)庫目標的 GN 構(gòu)建配置README.md目錄說明本文的關(guān)聯(lián)文檔其中 README 明確點名的Device Info Provider是目錄中唯一被詳細介紹的主題其職責是Supports device-specific information like labels, locales and calendar types.即向設(shè)備端 Cluster 提供**標簽labels、區(qū)域設(shè)置locales和日歷類型calendar types**等設(shè)備特有信息。這三類數(shù)據(jù)分別對應(yīng) Matter 規(guī)范中的 Fixed Label、User Label、Localization Configuration 和 Time Format Localization 等 Cluster。2. 核心接口DeviceInfoProvider 抽象基類在深入示例實現(xiàn)之前需要先理解 SDK 定義的抽象基類 src/include/platform/DeviceInfoProvider.h。它是所有設(shè)備信息 Provider 的公共契約位于chip::DeviceLayer命名空間下。2.1 四個純虛迭代器接口基類定義了四個必須實現(xiàn)的純虛迭代器 0分別覆蓋 README 中提到的 labels、locales、calendar types純虛方法返回迭代器類型數(shù)據(jù)來源 Cluster元素類型IterateFixedLabel(EndpointId)FixedLabelIterator *Fixed Label固定標簽FixedLabelTypeIterateUserLabel(EndpointId)UserLabelIterator *User Label用戶標簽UserLabelTypeIterateSupportedLocales()SupportedLocalesIterator *Localization Configuration區(qū)域配置CharSpanIterateSupportedCalendarTypes()SupportedCalendarTypesIterator *Time Format Localization時間格式本地化CalendarType所有迭代器都基于同一個模板IteratorT定義其協(xié)議非常簡單template typename T class Iterator { public: virtual size_t Count() 0; // 返回總共將迭代的條目數(shù) virtual bool Next(T item) 0; // 成功取回下一個元素返回 true無更多條目返回 false virtual void Release() 0; // 釋放迭代器分配的內(nèi)存指針離開作用域前必須調(diào)用 };其中元素類型在基類中做了別名綁定using FixedLabelType app::Clusters::FixedLabel::Structs::LabelStruct::Type; using UserLabelType app::Clusters::UserLabel::Structs::LabelStruct::Type; using CalendarType app::Clusters::TimeFormatLocalization::CalendarTypeEnum;2.2 平臺側(cè)定義的常量約束基類頭部同時定義了 Provider 實現(xiàn)需要遵守的容量上限src/include/platform/DeviceInfoProvider.hstatic constexpr size_t kMaxUserLabelListLength 4; // 每個 Endpoint 的用戶標簽列表最大 4 條 static constexpr size_t kMaxLabelNameLength 16; // 標簽名最大 16 字節(jié) static constexpr size_t kMaxLabelValueLength 16; // 標簽值最大 16 字節(jié) static constexpr size_t kMaxActiveLocaleLength 35; // 活動區(qū)域設(shè)置串最大 35 字節(jié)這些常量直接決定了示例實現(xiàn)中內(nèi)部緩沖區(qū)的尺寸詳見第 4 節(jié)。2.3 User Label 的寫操作與全局 Provider 注冊除了讀側(cè)迭代器基類還向派生類暴露了一組protected 虛函數(shù)用于對 User Label 列表做持久化讀寫SetUserLabelAt(endpoint, index, userLabel)設(shè)置指定索引處的標簽DeleteUserLabelAt(endpoint, index)刪除指定索引處的標簽SetUserLabelLength(endpoint, val)/GetUserLabelLength(endpoint, val)讀寫標簽列表長度。公共的列表級操作SetUserLabelList、ClearUserLabelList、AppendUserLabel則由基類在 src/platform/DeviceInfoProvider.cpp 中基于上述原語組合實現(xiàn)例如AppendUserLabel會先讀取當前長度、校驗不超過kMaxUserLabelListLength否則返回CHIP_ERROR_NO_MEMORY再依次寫入長度與新標簽。全局訪問通過GetDeviceInfoProvider()/SetDeviceInfoProvider(DeviceInfoProvider *)完成兩者維護一個進程級單例指針src/platform/DeviceInfoProvider.cpp。3. 兩個示例實現(xiàn)的設(shè)計意圖空實現(xiàn) vs 常量數(shù)據(jù)目錄中提供了兩套風格截然不同的實現(xiàn)體現(xiàn)了不同的使用場景DeviceInfoProviderImpl空實現(xiàn)所有迭代器返回空數(shù)據(jù)是Matter 1.5 之后引入的安全默認AllClustersExampleDeviceInfoProviderImpl常量實現(xiàn)填充硬編碼的示例值專供 all-clusters 類測試應(yīng)用使用。3.1 空實現(xiàn)版防止壞數(shù)據(jù)泄漏進產(chǎn)品在 DeviceInfoProviderImpl.h 的頭部源碼用四個感嘆號標注了非常醒目的 WARNINGDO NOT USE THESE DEFAULT IMPLEMENTATIONS WITH DEFAULT VALUES IN PRODUCTION PRODUCTS WITHOUT AUDITING THEM! ... Here, all providers have empty implementations to force empty lists which prevent bad values from leaking into products like happened before Matter 1.5.這段話傳遞了兩個關(guān)鍵信息歷史教訓(xùn)Matter 1.5 之前示例默認值曾直接泄漏到產(chǎn)品中設(shè)計對策此后默認示例強制返回空列表如果產(chǎn)品確實要用 FixedLabel、LocalizationConfiguration、Time Format Localization 等 Cluster必須重新實現(xiàn) Provider且填入的值必須經(jīng)過正確性審查。具體到代碼DeviceInfoProviderImpl.cppDeviceInfoProvider::FixedLabelIterator * DeviceInfoProviderImpl::IterateFixedLabel(EndpointId endpoint) { // We dont include fixed label data in this sample one. Returning nullptr returns empty list. (void) endpoint; return nullptr; }IterateFixedLabel直接返回nullptr按照基類文檔約定returns nullptr if no iterator instances are available調(diào)用方會將其解釋為空列表。3.2 常量實現(xiàn)版面向 all-clusters 測試AllClustersExampleDeviceInfoProviderImpl則為測試目的填充了經(jīng)過審查的常量值其頭部警告措辭相對緩和但也明確指出FixedLabel cluster, if used, should have values that have been vetted for correctness in the productAllClustersExampleDeviceInfoProviderImpl.cpp。兩套實現(xiàn)的差異匯總維度DeviceInfoProviderImplAllClustersExampleDeviceInfoProviderImplFixedLabel返回nullptr空列表返回 1 條硬編碼標簽directionup/downUserLabel持久化存儲讀寫持久化存儲讀寫SupportedLocales2 個en-US、en-GB8 個en-US、de-DE、fr-FR、en-GB、es-ES、zh-CN、it-IT、ja-JPSupportedCalendarTypes1 個kGregorian1 個kGregorian4. 源碼級剖析四個迭代器的完整實現(xiàn)下面以AllClustersExampleDeviceInfoProviderImpl為主要樣本逐個剖析四個迭代器的實現(xiàn)空實現(xiàn)版邏輯相同只是數(shù)據(jù)量為 0 或nullptr。4.1 FixedLabelIteratorImpl按 Endpoint 區(qū)分的固定標簽DeviceInfoProvider::FixedLabelIterator * AllClustersExampleDeviceInfoProviderImpl::IterateFixedLabel(EndpointId endpoint) { return chip::Platform::NewFixedLabelIteratorImpl(endpoint); }迭代器在堆上通過chip::Platform::New分配Release()時通過chip::Platform::Delete(this)釋放這與基類必須調(diào)用 Release() 釋放內(nèi)存的契約一致。FixedLabelIteratorImpl::Next()的實現(xiàn)展示了按 Endpoint 返回不同值的手法AllClustersExampleDeviceInfoProviderImpl.cppcase 0: output.label direction_span; if (mEndpoint 1) { output.value up_span; } else { output.value down_span; } break;即固定標簽名direction對 Endpoint 1 返回up其余 Endpoint 返回down。源碼注釋還提醒真實產(chǎn)品中這些值很可能需要按 Endpoint 動態(tài)生成此時應(yīng)把 span 指向正確的 buffersize而非直接使用const char*支撐的CharSpan。4.2 UserLabelIteratorImpl基于持久化存儲的讀寫User Label 與前兩者最大的不同是可寫——用戶或控制器可以通過 Cluster 命令增刪標簽。因此示例實現(xiàn)將其落到PersistentStorageDelegate上。寫入側(cè)SetUserLabelAt把標簽序列化為 TLV 結(jié)構(gòu)后按 key 存儲AllClustersExampleDeviceInfoProviderImpl.cppuint8_t buf[UserLabelTLVMaxSize()]; TLV::TLVWriter writer; writer.Init(buf); TLV::TLVType outerType; ReturnErrorOnFailure(writer.StartContainer(TLV::AnonymousTag(), TLV::kTLVType_Structure, outerType)); ReturnErrorOnFailure(writer.PutString(kLabelNameTag, userLabel.label)); // ContextTag(0) ReturnErrorOnFailure(writer.PutString(kLabelValueTag, userLabel.value)); // ContextTag(1) ReturnErrorOnFailure(writer.EndContainer(outerType)); return mStorage-SyncSetKeyValue( DefaultStorageKeyAllocator::UserLabelIndexKey(endpoint, static_castuint32_t(index)).KeyName(), buf, static_castuint16_t(writer.GetLengthWritten()));其中kLabelNameTag/kLabelValueTag分別是TLV::ContextTag(0)/ContextTag(1)緩沖區(qū)大小由UserLabelTLVMaxSize()決定即TLV::EstimateStructOverhead(kMaxLabelNameLength, kMaxLabelValueLength)16 字節(jié) name 16 字節(jié) value TLV 結(jié)構(gòu)開銷存儲 key 由DefaultStorageKeyAllocator::UserLabelLengthKey(endpoint)長度與UserLabelIndexKey(endpoint, index)條目統(tǒng)一生成。讀取側(cè)UserLabelIteratorImpl::Next()先從存儲讀出 TLV 字節(jié)再用TLV::ContiguousBufferTLVReader逐字段解析最終把 label/value 拷貝進內(nèi)部緩沖后以CharSpan返回Platform::CopyString(mUserLabelNameBuf, label); Platform::CopyString(mUserLabelValueBuf, value); output.label CharSpan::fromCharString(mUserLabelNameBuf); output.value CharSpan::fromCharString(mUserLabelValueBuf);迭代器的Count()與Next()均基于構(gòu)造時讀到的列表長度mTotal工作超出范圍即返回false結(jié)束迭代。兩個示例實現(xiàn)空實現(xiàn)版與常量版的 User Label 讀寫邏輯完全一致因為這一部分與示例數(shù)據(jù)無關(guān)屬于通用存儲邏輯。4.3 SupportedLocalesIteratorImpl區(qū)域設(shè)置清單空實現(xiàn)版硬編碼 2 個區(qū)域DeviceInfoProviderImpl.cppstatic const char * kAllSupportedLocales[kNumSupportedLocales] { en-US, en-GB };常量實現(xiàn)版擴展為 8 個常用區(qū)域AllClustersExampleDeviceInfoProviderImpl.cppstatic const char * kAllSupportedLocales[kNumSupportedLocales] { en-US, de-DE, fr-FR, en-GB, es-ES, zh-CN, it-IT, ja-JP };區(qū)域字符串是 BCP-47 風格的語言-國家/地區(qū)格式直接對應(yīng) Localization Configuration Cluster 中SupportedLocales屬性的枚舉值。4.4 SupportedCalendarTypesIteratorImpl日歷類型清單兩套實現(xiàn)都只支持一種日歷——公歷static const CalendarType kAllSupportedCalendarTypes[kNumSupportedCalendarTypes] { app::Clusters::TimeFormatLocalization::CalendarTypeEnum::kGregorian };該枚舉值來自TimeFormatLocalizationCluster其迭代器元素類型是CalendarType枚舉與區(qū)域設(shè)置迭代器返回的CharSpan不同。5. 構(gòu)建配置兩個靜態(tài)庫目標examples/providers/BUILD.gn 將兩套實現(xiàn)分別封裝為靜態(tài)庫static_library(device_info_provider_please_do_not_reuse_as_is) { output_name libMatterDeviceInfoProviderExample sources [ DeviceInfoProviderImpl.cpp, DeviceInfoProviderImpl.h, ] public_deps [ ${chip_root}/src/lib/support, ${chip_root}/src/platform, ] public_configs [ :include_providers_dir ] } static_library(all_clusters_device_info_provider) { output_name libMatterAllClustersDeviceInfoProviderExample sources [ AllClustersExampleDeviceInfoProviderImpl.cpp, AllClustersExampleDeviceInfoProviderImpl.h, ] public_deps [ ${chip_root}/src/lib/support, ${chip_root}/src/platform, ] public_configs [ :include_providers_dir ] }值得注意的命名細節(jié)第一個目標名device_info_provider_please_do_not_reuse_as_is本身就攜帶了請勿照搬復(fù)用的語義與源碼頭部的 WARNING 相呼應(yīng)include_providers_dirconfig 同時把examples根目錄加入 include 路徑因此下游可以通過#include providers/AllClustersExampleDeviceInfoProviderImpl.h這種形如providers/...的頭文件引用方式引入實現(xiàn)。兩個庫都依賴${chip_root}/src/lib/support與${chip_root}/src/platform因為它們使用了DefaultStorageKeyAllocator、TLV、Platform內(nèi)存管理等 SDK 基礎(chǔ)設(shè)施。6. 在真實應(yīng)用中注冊使用all-clusters-app 實例示例 Provider 在 all-clusters-app 的 fuzzing 入口中有完整使用示范examples/all-clusters-app/linux/fuzzing-main.cpp#include providers/AllClustersExampleDeviceInfoProviderImpl.h // ... chip::DeviceLayer::AllClustersExampleDeviceInfoProviderImpl gAllClustersExampleDeviceInfoProvider; // ... DeviceLayer::SetDeviceInfoProvider(gAllClustersExampleDeviceInfoProvider);完整的接入流程是實例化在全局或初始化階段構(gòu)造 Provider 子類對象設(shè)置存儲委托調(diào)用SetStorageDelegate(PersistentStorageDelegate *)注入非易失存儲基類SetStorageDelegate對空指針會VerifyOrDiesrc/platform/DeviceInfoProvider.cppUser Label 的持久化讀寫依賴該存儲注冊全局實例調(diào)用SetDeviceInfoProvider(provider)掛入DeviceLayer的全局指針協(xié)議棧使用此后 Fixed Label、User Label、Localization Configuration、Time Format Localization 等 Cluster 的數(shù)據(jù)讀寫都會路由到該 Provider。這四條步驟同樣適用于任何自定義 Provider繼承DeviceInfoProvider→ 實現(xiàn)四個迭代器與四個 User Label 原語 → 注入存儲 → 全局注冊。7. 面向產(chǎn)品開發(fā)者的最佳實踐綜合 README 的定位說明與源碼中的 WARNING可以總結(jié)出以下實踐要點示例僅供學(xué)習與測試examples/providers/中的實現(xiàn)是應(yīng)用專用的示例最終產(chǎn)品應(yīng)擁有自己的實現(xiàn)空實現(xiàn)是安全基線Matter 1.5 之后默認空實現(xiàn)刻意返回空列表避免未審查的示例值進入產(chǎn)品如果你確實啟用 FixedLabel、LocalizationConfiguration、TimeFormatLocalization 等 Cluster務(wù)必重寫 Provider 并提供經(jīng)過驗證的值User Label 需要持久化該能力依賴PersistentStorageDelegate務(wù)必在注冊 Provider 前通過SetStorageDelegate注入有效存儲否則斷言失敗遵守容量約束標簽名與標簽值均不超過 16 字節(jié)、每 Endpoint 用戶標簽最多 4 條kMaxUserLabelListLength列表操作在超限時返回CHIP_ERROR_NO_MEMORY迭代器生命周期管理所有迭代器通過chip::Platform::New分配調(diào)用方必須在迭代結(jié)束后調(diào)用Release()且迭代期間不允許修改標簽數(shù)據(jù)。參考文件索引關(guān)聯(lián)文檔examples/providers/README.md空實現(xiàn)版DeviceInfoProviderImpl.h / DeviceInfoProviderImpl.cpp常量實現(xiàn)版AllClustersExampleDeviceInfoProviderImpl.h / AllClustersExampleDeviceInfoProviderImpl.cpp構(gòu)建配置examples/providers/BUILD.gn抽象基類src/include/platform/DeviceInfoProvider.h基類通用實現(xiàn)src/platform/DeviceInfoProvider.cpp應(yīng)用接入示例examples/all-clusters-app/linux/fuzzing-main.cpp【免費下載鏈接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.項目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考