Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2021 Project CHIP Authors
       4             :  *
       5             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6             :  *    you may not use this file except in compliance with the License.
       7             :  *    You may obtain a copy of the License at
       8             :  *
       9             :  *        http://www.apache.org/licenses/LICENSE-2.0
      10             :  *
      11             :  *    Unless required by applicable law or agreed to in writing, software
      12             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14             :  *    See the License for the specific language governing permissions and
      15             :  *    limitations under the License.
      16             :  */
      17             : 
      18             : #pragma once
      19             : 
      20             : #include <stdint.h>
      21             : #include <stdio.h>
      22             : #include <stdlib.h>
      23             : 
      24             : #include <lib/core/CHIPCore.h>
      25             : #include <lib/support/Span.h>
      26             : 
      27             : namespace chip {
      28             : namespace Thread {
      29             : 
      30             : class ThreadTLV;
      31             : 
      32             : inline constexpr size_t kChannel_NotSpecified = UINT8_MAX;
      33             : inline constexpr size_t kPANId_NotSpecified   = UINT16_MAX;
      34             : 
      35             : inline constexpr size_t kSizeOperationalDataset = 254;
      36             : 
      37             : inline constexpr size_t kSizeNetworkName     = 16;
      38             : inline constexpr size_t kSizeExtendedPanId   = 8;
      39             : inline constexpr size_t kSizeMasterKey       = 16;
      40             : inline constexpr size_t kSizeMeshLocalPrefix = 8;
      41             : inline constexpr size_t kSizePSKc            = 16;
      42             : 
      43             : /**
      44             :  * This class provides methods to manipulate Thread operational dataset.
      45             :  *
      46             :  */
      47             : class OperationalDataset
      48             : {
      49             : public:
      50             :     /**
      51             :      * This method initializes the dataset with the given dataset.
      52             :      *
      53             :      * @param[in]   aData       Thread Operational dataset in octects.
      54             :      *
      55             :      * @retval CHIP_NO_ERROR                Successfully initialized the dataset.
      56             :      * @retval CHIP_ERROR_INVALID_ARGUMENT  The dataset length @p aLength is too long or @p data is corrupted.
      57             :      *
      58             :      */
      59             :     CHIP_ERROR Init(ByteSpan aData);
      60             : 
      61             :     /**
      62             :      * This method retrieves Thread active timestamp from the dataset.
      63             :      *
      64             :      * @param[out]  aActiveTimestamp    A reference to receive the active timestamp.
      65             :      *
      66             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the active timestamp.
      67             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread active timestamp is not present in the dataset.
      68             :      *
      69             :      */
      70             :     CHIP_ERROR GetActiveTimestamp(uint64_t & aActiveTimestamp) const;
      71             : 
      72             :     /**
      73             :      * This method sets Thread active timestamp to the dataset.
      74             :      *
      75             :      * @param[in]   aActiveTimestamp    The Thread active timestamp.
      76             :      *
      77             :      * @retval CHIP_NO_ERROR           Successfully set the active timestamp.
      78             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread active timestamp.
      79             :      *
      80             :      */
      81             :     CHIP_ERROR SetActiveTimestamp(uint64_t aActiveTimestamp);
      82             : 
      83             :     /**
      84             :      * This method retrieves Thread channel from the dataset.
      85             :      *
      86             :      * @param[out]  aChannel    A reference to receive the channel.
      87             :      *
      88             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the channel.
      89             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread channel is not present in the dataset.
      90             :      *
      91             :      */
      92             :     CHIP_ERROR GetChannel(uint16_t & aChannel) const;
      93             : 
      94             :     /**
      95             :      * This method sets Thread channel to the dataset.
      96             :      *
      97             :      * @param[in]   aChannel    The Thread channel.
      98             :      *
      99             :      * @retval CHIP_NO_ERROR           Successfully set the channel.
     100             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread channel.
     101             :      *
     102             :      */
     103             :     CHIP_ERROR SetChannel(uint16_t aChannel);
     104             : 
     105             :     /**
     106             :      * This method retrieves Thread extended PAN ID from the dataset.
     107             :      *
     108             :      * @param[out]  aExtendedPanId  A reference to receive the extended PAN ID.
     109             :      *
     110             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the extended PAN ID.
     111             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread extended PAN ID is not present in the dataset.
     112             :      *
     113             :      */
     114             :     CHIP_ERROR GetExtendedPanId(uint8_t (&aExtendedPanId)[kSizeExtendedPanId]) const;
     115             : 
     116             :     /**
     117             :      * This method returns a const ByteSpan to the extended PAN ID in the dataset.
     118             :      * This can be used to pass the extended PAN ID to a cluster command without the use of external memory.
     119             :      *
     120             :      * @param[out]  span  A reference to receive the location of the extended PAN ID.
     121             :      *
     122             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the extended PAN ID.
     123             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread extended PAN ID is not present in the dataset.
     124             :      *
     125             :      */
     126             :     CHIP_ERROR GetExtendedPanIdAsByteSpan(ByteSpan & span) const;
     127             : 
     128             :     /**
     129             :      * This method sets Thread extended PAN ID to the dataset.
     130             :      *
     131             :      * @param[in]   aExtendedPanId  The Thread extended PAN ID.
     132             :      *
     133             :      * @retval CHIP_NO_ERROR           Successfully set the extended PAN ID.
     134             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread extended PAN ID.
     135             :      *
     136             :      */
     137             :     CHIP_ERROR SetExtendedPanId(const uint8_t (&aExtendedPanId)[kSizeExtendedPanId]);
     138             : 
     139             :     /**
     140             :      * This method retrieves Thread master key from the dataset.
     141             :      *
     142             :      * @param[out]  aMasterKey  A reference to receive the master key.
     143             :      *
     144             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the master key.
     145             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread master key is not present in the dataset.
     146             :      *
     147             :      */
     148             :     CHIP_ERROR GetMasterKey(uint8_t (&aMasterKey)[kSizeMasterKey]) const;
     149             : 
     150             :     /**
     151             :      * This method sets Thread master key to the dataset.
     152             :      *
     153             :      * @param[in]   aMasterKey         The Thread master key.
     154             :      *
     155             :      * @retval CHIP_NO_ERROR           Successfully set the master key.
     156             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread master key.
     157             :      *
     158             :      */
     159             :     CHIP_ERROR SetMasterKey(const uint8_t (&aMasterKey)[kSizeMasterKey]);
     160             : 
     161             :     /**
     162             :      * This method unsets Thread master key to the dataset.
     163             :      *
     164             :      */
     165             :     void UnsetMasterKey(void);
     166             : 
     167             :     /**
     168             :      * This method retrieves Thread mesh local prefix from the dataset.
     169             :      *
     170             :      * @param[out]  aMeshLocalPrefix    A reference to receive the mesh local prefix.
     171             :      *
     172             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the mesh local prefix.
     173             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread mesh local prefix is not present in the dataset.
     174             :      *
     175             :      */
     176             :     CHIP_ERROR GetMeshLocalPrefix(uint8_t (&aMeshLocalPrefix)[kSizeMeshLocalPrefix]) const;
     177             : 
     178             :     /**
     179             :      * This method sets Thread mesh local prefix to the dataset.
     180             :      *
     181             :      * @param[in]   aMeshLocalPrefix   The Thread mesh local prefix.
     182             :      *
     183             :      * @retval CHIP_NO_ERROR           Successfully set the Thread mesh local prefix.
     184             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread mesh local prefix.
     185             :      *
     186             :      */
     187             :     CHIP_ERROR SetMeshLocalPrefix(const uint8_t (&aMeshLocalPrefix)[kSizeMeshLocalPrefix]);
     188             : 
     189             :     /**
     190             :      * This method retrieves Thread network name from the dataset.
     191             :      *
     192             :      * @param[out]  aNetworkName    A reference to receive the Thread network name.
     193             :      *
     194             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the network name.
     195             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread network name is not present in the dataset.
     196             :      *
     197             :      */
     198             :     CHIP_ERROR GetNetworkName(char (&aNetworkName)[kSizeNetworkName + 1]) const;
     199             : 
     200             :     /**
     201             :      * This method sets Thread network name to the dataset.
     202             :      *
     203             :      * @param[in]   aNetworkName    The Thread network name.
     204             :      *
     205             :      * @retval CHIP_NO_ERROR           Successfully set the network name.
     206             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread network name.
     207             :      *
     208             :      */
     209             :     CHIP_ERROR SetNetworkName(const char * aNetworkName);
     210             : 
     211             :     /**
     212             :      * This method retrieves Thread PAN ID from the dataset.
     213             :      *
     214             :      * @param[out]  aPanId  A reference to receive the PAN ID.
     215             :      *
     216             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the PAN ID.
     217             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread PAN ID is not present in the dataset.
     218             :      *
     219             :      */
     220             :     CHIP_ERROR GetPanId(uint16_t & aPanId) const;
     221             : 
     222             :     /**
     223             :      * This method sets Thread PAN ID to the dataset.
     224             :      *
     225             :      * @param[in]   aPanId  The Thread PAN ID.
     226             :      *
     227             :      * @retval CHIP_NO_ERROR           Successfully set the PAN ID.
     228             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread PAN ID.
     229             :      *
     230             :      */
     231             :     CHIP_ERROR SetPanId(uint16_t aPanId);
     232             : 
     233             :     /**
     234             :      * This method retrieves Thread PSKc from the dataset.
     235             :      *
     236             :      * @param[out]  aPSKc   A reference to receive the PSKc.
     237             :      *
     238             :      * @retval CHIP_NO_ERROR                    Successfully retrieved the PSKc.
     239             :      * @retval CHIP_ERROR_TLV_TAG_NOT_FOUND     Thread PSKc is not present in the dataset.
     240             :      *
     241             :      */
     242             :     CHIP_ERROR GetPSKc(uint8_t (&aPSKc)[kSizePSKc]) const;
     243             : 
     244             :     /**
     245             :      * This method sets Thread PSKc to the dataset.
     246             :      *
     247             :      * @param[in]   aPSKc   The Thread PSKc.
     248             :      *
     249             :      * @retval CHIP_NO_ERROR           Successfully set the PSKc.
     250             :      * @retval CHIP_ERROR_NO_MEMORY    Insufficient memory in the dataset for setting Thread PSKc.
     251             :      *
     252             :      */
     253             :     CHIP_ERROR SetPSKc(const uint8_t (&aPSKc)[kSizePSKc]);
     254             : 
     255             :     /**
     256             :      * This method unsets Thread PSKc to the dataset.
     257             :      *
     258             :      */
     259             :     void UnsetPSKc(void);
     260             : 
     261             :     /**
     262             :      * This method clears all data stored in the dataset.
     263             :      */
     264             :     void Clear(void) { mLength = 0; }
     265             : 
     266             :     /**
     267             :      * This method checks if the dataset is ready for creating Thread network.
     268             :      *
     269             :      */
     270             :     bool IsCommissioned(void) const;
     271             : 
     272             :     /**
     273             :      * This method checks if the dataset is empty.
     274             :      */
     275             :     bool IsEmpty() const { return mLength == 0; }
     276             : 
     277             :     /**
     278             :      * This method checks whether @p aData is formatted as ThreadTLVs.
     279             :      *
     280             :      * @note This method doesn't verify ThreadTLV values are valid.
     281             :      *
     282             :      */
     283             :     static bool IsValid(ByteSpan aData);
     284             : 
     285             :     ByteSpan AsByteSpan(void) const { return ByteSpan(mData, mLength); }
     286             : 
     287             : private:
     288          13 :     ThreadTLV * Locate(uint8_t aType)
     289             :     {
     290          13 :         return const_cast<ThreadTLV *>(const_cast<const OperationalDataset *>(this)->Locate(aType));
     291             :     }
     292             :     const ThreadTLV * Locate(uint8_t aType) const;
     293          42 :     const ThreadTLV & Begin(void) const { return *reinterpret_cast<const ThreadTLV *>(&mData[0]); };
     294             :     ThreadTLV & Begin(void) { return const_cast<ThreadTLV &>(const_cast<const OperationalDataset *>(this)->Begin()); }
     295          64 :     const ThreadTLV & End(void) const { return *reinterpret_cast<const ThreadTLV *>(&mData[mLength]); };
     296          22 :     ThreadTLV & End(void) { return const_cast<ThreadTLV &>(const_cast<const OperationalDataset *>(this)->End()); }
     297             :     void Remove(uint8_t aType);
     298             :     void Remove(ThreadTLV & aTlv);
     299             :     ThreadTLV * MakeRoom(uint8_t aType, uint8_t aSize);
     300           0 :     bool Has(uint8_t aType) const { return Locate(aType) != nullptr; }
     301             : 
     302             :     uint8_t mData[kSizeOperationalDataset];
     303             :     uint8_t mLength;
     304             : };
     305             : 
     306             : } // namespace Thread
     307             : }; // namespace chip