From cb27207675b2e92119a9ba5eb4b2f366be0852c7 Mon Sep 17 00:00:00 2001
From: Handa Wang <7058128+superwhd@users.noreply.github.com>
Date: Tue, 29 Oct 2024 22:56:05 +0800
Subject: [PATCH] [nat64] add API `otNat64ClearIp4Cidr`  (#10848)

This commit introduces a new API `otNat64ClearIp4Cidr` which is useful
when the in-use NAT64 CIDR is preempted and the platform fails to
allocate a new IPv4 CIDR. In such a (rare) case we'd better notify OT
that there isn't an available CIDR. `otNat64SetIp4Cidr` doesn't
support an 0-length CIDR as the input so we'll have to introduce this
new API.
---
 include/openthread/instance.h     |  2 +-
 include/openthread/nat64.h        | 18 ++++++++++++++++--
 src/core/api/nat64_api.cpp        |  2 ++
 src/core/net/nat64_translator.cpp | 10 ++++++++++
 src/core/net/nat64_translator.hpp |  8 ++++++++
 5 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/include/openthread/instance.h b/include/openthread/instance.h
index aab7045d4..daca8dace 100644
--- a/include/openthread/instance.h
+++ b/include/openthread/instance.h
@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (458)
+#define OPENTHREAD_API_VERSION (459)
 
 /**
  * @addtogroup api-instance
diff --git a/include/openthread/nat64.h b/include/openthread/nat64.h
index 8d48a6a76..f99e979ef 100644
--- a/include/openthread/nat64.h
+++ b/include/openthread/nat64.h
@@ -312,11 +312,25 @@ otMessage *otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSett
  * @retval  OT_ERROR_INVALID_ARGS   The given CIDR is not a valid IPv4 CIDR for NAT64.
  * @retval  OT_ERROR_NONE           Successfully set the CIDR for NAT64.
  *
- * @sa otBorderRouterSend
- * @sa otBorderRouterSetReceiveCallback
+ * @sa otNat64Send
+ * @sa otNat64SetReceiveIp4Callback
  */
 otError otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr);
 
+/**
+ * Clears the CIDR used when setting the source address of the outgoing translated IPv4 packets.
+ *
+ * Is available only when OPENTHREAD_CONFIG_NAT64_TRANSLATOR_ENABLE is enabled.
+ *
+ * @note This function can be called at any time, but the NAT64 translator will be reset and all existing sessions
+ * will be expired when clearing the configured CIDR.
+ *
+ * @param[in] aInstance  A pointer to an OpenThread instance.
+ *
+ * @sa otNat64SetIp4Cidr
+ */
+void otNat64ClearIp4Cidr(otInstance *aInstance);
+
 /**
  * Translates an IPv4 datagram to an IPv6 datagram and sends via the Thread interface.
  *
diff --git a/src/core/api/nat64_api.cpp b/src/core/api/nat64_api.cpp
index bab32126e..3e300cc0c 100644
--- a/src/core/api/nat64_api.cpp
+++ b/src/core/api/nat64_api.cpp
@@ -49,6 +49,8 @@ otError otNat64SetIp4Cidr(otInstance *aInstance, const otIp4Cidr *aCidr)
     return AsCoreType(aInstance).Get<Nat64::Translator>().SetIp4Cidr(AsCoreType(aCidr));
 }
 
+void otNat64ClearIp4Cidr(otInstance *aInstance) { AsCoreType(aInstance).Get<Nat64::Translator>().ClearIp4Cidr(); }
+
 otMessage *otIp4NewMessage(otInstance *aInstance, const otMessageSettings *aSettings)
 {
     return AsCoreType(aInstance).Get<Nat64::Translator>().NewIp4Message(Message::Settings::From(aSettings));
diff --git a/src/core/net/nat64_translator.cpp b/src/core/net/nat64_translator.cpp
index c1ffa733b..f553b2333 100644
--- a/src/core/net/nat64_translator.cpp
+++ b/src/core/net/nat64_translator.cpp
@@ -514,6 +514,16 @@ exit:
     return err;
 }
 
+void Translator::ClearIp4Cidr(void)
+{
+    mIp4Cidr.Clear();
+    mAddressMappingPool.FreeAll();
+    mActiveAddressMappings.Clear();
+    mIp4AddressPool.Clear();
+
+    UpdateState();
+}
+
 void Translator::SetNat64Prefix(const Ip6::Prefix &aNat64Prefix)
 {
     if (aNat64Prefix.GetLength() == 0)
diff --git a/src/core/net/nat64_translator.hpp b/src/core/net/nat64_translator.hpp
index d630b0338..043d48dce 100644
--- a/src/core/net/nat64_translator.hpp
+++ b/src/core/net/nat64_translator.hpp
@@ -233,6 +233,14 @@ public:
      */
     Error SetIp4Cidr(const Ip4::Cidr &aCidr);
 
+    /**
+     * Clears the CIDR used when setting the source address of the outgoing translated IPv4 datagrams.
+     *
+     * @note The NAT64 translator will be reset and all existing sessions will be expired when clearing the configured
+     * CIDR.
+     */
+    void ClearIp4Cidr(void);
+
     /**
      * Sets the prefix of NAT64-mapped addresses in the thread network. The address mapping table will not be cleared.
      * Equals to `ClearNat64Prefix` when an empty prefix is provided.