[instance] expose multi-instance getter as instance API (#11914)

This commit adds public getter functions to acquire a pointer for
the single OpenThread instance or one associated with a provided index.

An index to instance reference getter function was previously implemented
in the core instance interface, but this capability was not publicly accessible.
The accessor function introduced in this commit will now allow for platforms
or application code to perform this mapping. Corresponding changes for the
single instance case are also included.

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (537)
+#define OPENTHREAD_API_VERSION (538)
 
 /**
  * @addtogroup api-instance
@@ -98,6 +98,15 @@ otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize);
  */
 otInstance *otInstanceInitSingle(void);
 
+/**
+ * Gets the pointer to the single OpenThread instance when multiple instances are not in use.
+ *
+ * Is available and can only be used when support for multiple OpenThread instances is disabled.
+ *
+ * @returns A pointer to the single OpenThread instance.
+ */
+otInstance *otInstanceGetSingle(void);
+
 /**
  * Initializes the OpenThread instance.
  *
@@ -114,6 +123,18 @@ otInstance *otInstanceInitSingle(void);
  */
 otInstance *otInstanceInitMultiple(uint8_t aIdx);
 
+/**
+ * Gets the pointer to an OpenThread instance with the provided index when multiple instances are in use.
+ *
+ * This function is available when both `OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE` and
+ * `OPENTHREAD_CONFIG_MULTIPLE_STATIC_INSTANCE_ENABLE` are enabled.
+ *
+ * @param[in] aIdx The index of the OpenThread instance.
+ *
+ * @returns A pointer to the corresponding OpenThread instance, or `NULL` if @p aIdx is out of bounds.
+ */
+otInstance *otInstanceGetInstance(uint8_t aIdx);
+
 /**
  * Gets the index of the OpenThread instance when multiple instance is in use.
  *

src/core/api/instance_api.cpp

@@ -65,6 +65,12 @@ otInstance *otInstanceInitMultiple(uint8_t aIdx)
 
     return instance;
 }
+
+otInstance *otInstanceGetInstance(uint8_t aIdx)
+{
+    return (aIdx >= OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_NUM) ? nullptr : &Instance::Get(aIdx);
+}
+
 uint8_t otInstanceGetIndex(otInstance *aInstance) { return Instance::GetIdx(AsCoreTypePtr(aInstance)); }
 #endif // OPENTHREAD_CONFIG_MULTIPLE_STATIC_INSTANCE_ENABLE
 otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
@@ -77,6 +83,7 @@ otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
 }
 #else
 otInstance *otInstanceInitSingle(void) { return &Instance::InitSingle(); }
+otInstance *otInstanceGetSingle(void) { return &Instance::Get(); }
 #endif // #if OPENTHREAD_CONFIG_MULTIPLE_INSTANCE_ENABLE
 
 uint32_t otInstanceGetId(otInstance *aInstance) { return AsCoreType(aInstance).GetId(); }