[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

@@ -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

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.
  *

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));

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)

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.