[encoding] add '{Read/Write}Uint24()` (#5329)

This commit adds `ReadUint24()`, `WriteUint24()` in `encoding.hpp`
for both little and big endian formats. These methods are then used
for reading/writing OUI in `MechCop::Tlv` sub-classes. This commit
also adds a check in `DiscoverScanner` to ensure the given OUI in
`SetJoinerAdvertisement` is within the valid range.

src/core/common/encoding.hpp

@@ -148,6 +148,20 @@ inline uint32_t ReadUint32(const uint8_t *aBuffer)
             (static_cast<uint32_t>(aBuffer[2]) << 8) | (static_cast<uint32_t>(aBuffer[3]) << 0));
 }
 
+/**
+ * This function reads a 24-bit integer value from a given buffer assuming big-ending encoding.
+ *
+ * @param[in] aBuffer   Pointer to buffer to read from.
+ *
+ * @returns The value read from buffer.
+ *
+ */
+inline uint32_t ReadUint24(const uint8_t *aBuffer)
+{
+    return ((static_cast<uint32_t>(aBuffer[0]) << 16) | (static_cast<uint32_t>(aBuffer[1]) << 8) |
+            (static_cast<uint32_t>(aBuffer[2]) << 0));
+}
+
 /**
  * This function reads a `uint64_t` value from a given buffer assuming big-ending encoding.
  *
@@ -177,6 +191,20 @@ inline void WriteUint16(uint16_t aValue, uint8_t *aBuffer)
     aBuffer[1] = (aValue >> 0) & 0xff;
 }
 
+/**
+ * This function writes a 24-bit integer value to a given buffer using big-ending encoding.
+ *
+ * @param[in]  aValue    The value to write to buffer.
+ * @param[out] aBuffer   Pointer to buffer where the value will be written.
+ *
+ */
+inline void WriteUint24(uint32_t aValue, uint8_t *aBuffer)
+{
+    aBuffer[0] = (aValue >> 16) & 0xff;
+    aBuffer[1] = (aValue >> 8) & 0xff;
+    aBuffer[2] = (aValue >> 0) & 0xff;
+}
+
 /**
  * This function writes a `uint32_t` value to a given buffer using big-ending encoding.
  *
@@ -260,6 +288,20 @@ inline uint16_t ReadUint16(const uint8_t *aBuffer)
     return static_cast<uint16_t>(aBuffer[0] | (aBuffer[1] << 8));
 }
 
+/**
+ * This function reads a 24-bit integer value from a given buffer assuming little-ending encoding.
+ *
+ * @param[in] aBuffer   Pointer to buffer to read from.
+ *
+ * @returns The value read from buffer.
+ *
+ */
+inline uint32_t ReadUint24(const uint8_t *aBuffer)
+{
+    return ((static_cast<uint32_t>(aBuffer[0]) << 0) | (static_cast<uint32_t>(aBuffer[1]) << 8) |
+            (static_cast<uint32_t>(aBuffer[2]) << 16));
+}
+
 /**
  * This function reads a `uint32_t` value from a given buffer assuming little-ending encoding.
  *
@@ -303,6 +345,20 @@ inline void WriteUint16(uint16_t aValue, uint8_t *aBuffer)
     aBuffer[1] = (aValue >> 8) & 0xff;
 }
 
+/**
+ * This function writes a 24-bit integer value to a given buffer using little-ending encoding.
+ *
+ * @param[in]  aValue   The value to write to buffer.
+ * @param[out] aBuffer  Pointer to buffer where the value will be written.
+ *
+ */
+inline void WriteUint24(uint32_t aValue, uint8_t *aBuffer)
+{
+    aBuffer[0] = (aValue >> 0) & 0xff;
+    aBuffer[1] = (aValue >> 8) & 0xff;
+    aBuffer[2] = (aValue >> 16) & 0xff;
+}
+
 /**
  * This function writes a `uint32_t` value to a given buffer using little-ending encoding.
  *

src/core/meshcop/meshcop_tlvs.hpp

@@ -57,6 +57,8 @@ namespace MeshCoP {
 
 using ot::Encoding::BigEndian::HostSwap16;
 using ot::Encoding::BigEndian::HostSwap32;
+using ot::Encoding::BigEndian::ReadUint24;
+using ot::Encoding::BigEndian::WriteUint24;
 
 /**
  * This class implements MeshCoP TLV generation and parsing.
@@ -1968,11 +1970,7 @@ public:
      * @returns The Vendor Stack Vendor OUI value.
      *
      */
-    uint32_t GetOui(void) const
-    {
-        return (static_cast<uint32_t>(mOui[0]) << 16) | (static_cast<uint32_t>(mOui[1]) << 8) |
-               static_cast<uint32_t>(mOui[2]);
-    }
+    uint32_t GetOui(void) const { return ReadUint24(mOui); }
 
     /**
      * This method returns the Stack Vendor OUI value.
@@ -1980,12 +1978,7 @@ public:
      * @param[in]  aOui  The Vendor Stack Vendor OUI value.
      *
      */
-    void SetOui(uint32_t aOui)
-    {
-        mOui[0] = (aOui >> 16) & 0xff;
-        mOui[1] = (aOui >> 8) & 0xff;
-        mOui[2] = aOui & 0xff;
-    }
+    void SetOui(uint32_t aOui) { WriteUint24(aOui, mOui); }
 
     /**
      * This method returns the Build value.
@@ -2394,11 +2387,7 @@ public:
      * @returns The Vendor OUI value.
      *
      */
-    uint32_t GetOui(void) const
-    {
-        return (static_cast<uint32_t>(mOui[0]) << 16) | (static_cast<uint32_t>(mOui[1]) << 8) |
-               static_cast<uint32_t>(mOui[2]);
-    }
+    uint32_t GetOui(void) const { return ReadUint24(mOui); }
 
     /**
      * This method sets the Vendor OUI value.
@@ -2406,12 +2395,7 @@ public:
      * @param[in]  aOui The Vendor OUI value.
      *
      */
-    void SetOui(uint32_t aOui)
-    {
-        mOui[0] = (aOui >> 16) & 0xff;
-        mOui[1] = (aOui >> 8) & 0xff;
-        mOui[2] = aOui & 0xff;
-    }
+    void SetOui(uint32_t aOui) { return WriteUint24(aOui, mOui); }
 
     /**
      * This method returns the Adv Data length.

src/core/thread/discover_scanner.cpp

@@ -171,7 +171,7 @@ otError DiscoverScanner::SetJoinerAdvertisement(uint32_t aOui, const uint8_t *aA
     otError error = OT_ERROR_NONE;
 
     VerifyOrExit((aAdvData != nullptr) && (aAdvDataLength != 0) &&
-                     (aAdvDataLength <= MeshCoP::JoinerAdvertisementTlv::kAdvDataMaxLength),
+                     (aAdvDataLength <= MeshCoP::JoinerAdvertisementTlv::kAdvDataMaxLength) && (aOui <= kMaxOui),
                  error = OT_ERROR_INVALID_ARGS);
 
     mOui           = aOui;

src/core/thread/discover_scanner.hpp

@@ -155,6 +155,11 @@ private:
         kStateScanDone,
     };
 
+    enum : uint32_t
+    {
+        kMaxOui = 0xffffff,
+    };
+
     // Methods used by `MeshForwarder`
     otError PrepareDiscoveryRequestFrame(Mac::TxFrame &aFrame);
     void    HandleDiscoveryRequestFrameTxDone(Message &aMessage);