xref: /aosp_15_r20/external/openthread/include/openthread/instance.h (revision cfb92d1480a9e65faed56933e9c12405f45898b4)

/*
 *  Copyright (c) 2016, The OpenThread Authors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * @file
 * @brief
 *  This file defines the OpenThread Instance API.
 */

#ifndef OPENTHREAD_INSTANCE_H_
#define OPENTHREAD_INSTANCE_H_

#include <stdlib.h>

#include <openthread/error.h>
#include <openthread/platform/logging.h>
#include <openthread/platform/toolchain.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * The OpenThread API monotonic version number.
 *
 * This number MUST increase by one each time the contents of public OpenThread API include headers change.
 *
 * @note This number versions both OpenThread platform and user APIs.
 *
 */
#define OPENTHREAD_API_VERSION (460)

/**
 * @addtogroup api-instance
 *
 * @brief
 *   This module includes functions that control the OpenThread Instance.
 *
 * @{
 *
 */

/**
 * Represents the OpenThread instance structure.
 */
typedef struct otInstance otInstance;

/**
 * Initializes the OpenThread library.
 *
 * Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be
 * called before any other calls to OpenThread.
 *
 * Is available and can only be used when support for multiple OpenThread instances is enabled.
 *
 * @param[in]     aInstanceBuffer      The buffer for OpenThread to use for allocating the otInstance structure.
 * @param[in,out] aInstanceBufferSize  On input, the size of aInstanceBuffer. On output, if not enough space for
 *                                     otInstance, the number of bytes required for otInstance.
 *
 * @returns  A pointer to the new OpenThread instance.
 *
 * @sa otInstanceFinalize
 *
 */
otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize);

/**
 * Initializes the static single instance of the OpenThread library.
 *
 * Initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be
 * called before any other calls to OpenThread.
 *
 * Is available and can only be used when support for multiple OpenThread instances is disabled.
 *
 * @returns A pointer to the single OpenThread instance.
 *
 */
otInstance *otInstanceInitSingle(void);

/**
 * Initializes the OpenThread instance.
 *
 * This function initializes OpenThread and prepares it for subsequent OpenThread API calls. This function must be
 * called before any other calls to OpenThread. This method utilizes static buffer to initialize the OpenThread
 * instance.
 *
 * This function is available and can only be used when support for multiple OpenThread static instances is
 * enabled (`OPENTHREAD_CONFIG_MULTIPLE_STATIC_INSTANCE_ENABLE`)
 *
 * @param[in] aIdx The index of the OpenThread instance to initialize.
 *
 * @returns  A pointer to the new OpenThread instance.
 *
 */
otInstance *otInstanceInitMultiple(uint8_t aIdx);

/**
 * Gets the instance identifier.
 *
 * The instance identifier is set to a random value when the instance is constructed, and then its value will not
 * change after initialization.
 *
 * @returns The instance identifier.
 *
 */
uint32_t otInstanceGetId(otInstance *aInstance);

/**
 * Indicates whether or not the instance is valid/initialized.
 *
 * The instance is considered valid if it is acquired and initialized using either `otInstanceInitSingle()` (in single
 * instance case) or `otInstanceInit()` (in multi instance case). A subsequent call to `otInstanceFinalize()` causes
 * the instance to be considered as uninitialized.
 *
 * @param[in] aInstance A pointer to an OpenThread instance.
 *
 * @returns TRUE if the given instance is valid/initialized, FALSE otherwise.
 *
 */
bool otInstanceIsInitialized(otInstance *aInstance);

/**
 * Disables the OpenThread library.
 *
 * Call this function when OpenThread is no longer in use.
 *
 * @param[in] aInstance A pointer to an OpenThread instance.
 *
 */
void otInstanceFinalize(otInstance *aInstance);

/**
 * Returns the current instance uptime (in msec).
 *
 * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled.
 *
 * The uptime is given as number of milliseconds since OpenThread instance was initialized.
 *
 * @param[in] aInstance A pointer to an OpenThread instance.
 *
 * @returns The uptime (number of milliseconds).
 *
 */
uint64_t otInstanceGetUptime(otInstance *aInstance);

#define OT_UPTIME_STRING_SIZE 24 ///< Recommended size for string representation of uptime.

/**
 * Returns the current instance uptime as a human-readable string.
 *
 * Requires `OPENTHREAD_CONFIG_UPTIME_ENABLE` to be enabled.
 *
 * The string follows the format "<hh>:<mm>:<ss>.<mmmm>" for hours, minutes, seconds and millisecond (if uptime is
 * shorter than one day) or "<dd>d.<hh>:<mm>:<ss>.<mmmm>" (if longer than a day).
 *
 * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be truncated
 * but the outputted string is always null-terminated.
 *
 * @param[in]  aInstance A pointer to an OpenThread instance.
 * @param[out] aBuffer   A pointer to a char array to output the string.
 * @param[in]  aSize     The size of @p aBuffer (in bytes). Recommended to use `OT_UPTIME_STRING_SIZE`.
 *
 */
void otInstanceGetUptimeAsString(otInstance *aInstance, char *aBuffer, uint16_t aSize);

#define OT_CHANGED_IP6_ADDRESS_ADDED (1U << 0)             ///< IPv6 address was added
#define OT_CHANGED_IP6_ADDRESS_REMOVED (1U << 1)           ///< IPv6 address was removed
#define OT_CHANGED_THREAD_ROLE (1U << 2)                   ///< Role (disabled, detached, child, router, leader) changed
#define OT_CHANGED_THREAD_LL_ADDR (1U << 3)                ///< The link-local address changed
#define OT_CHANGED_THREAD_ML_ADDR (1U << 4)                ///< The mesh-local address changed
#define OT_CHANGED_THREAD_RLOC_ADDED (1U << 5)             ///< RLOC was added
#define OT_CHANGED_THREAD_RLOC_REMOVED (1U << 6)           ///< RLOC was removed
#define OT_CHANGED_THREAD_PARTITION_ID (1U << 7)           ///< Partition ID changed
#define OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER (1U << 8)   ///< Thread Key Sequence changed
#define OT_CHANGED_THREAD_NETDATA (1U << 9)                ///< Thread Network Data changed
#define OT_CHANGED_THREAD_CHILD_ADDED (1U << 10)           ///< Child was added
#define OT_CHANGED_THREAD_CHILD_REMOVED (1U << 11)         ///< Child was removed
#define OT_CHANGED_IP6_MULTICAST_SUBSCRIBED (1U << 12)     ///< Subscribed to a IPv6 multicast address
#define OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED (1U << 13)   ///< Unsubscribed from a IPv6 multicast address
#define OT_CHANGED_THREAD_CHANNEL (1U << 14)               ///< Thread network channel changed
#define OT_CHANGED_THREAD_PANID (1U << 15)                 ///< Thread network PAN Id changed
#define OT_CHANGED_THREAD_NETWORK_NAME (1U << 16)          ///< Thread network name changed
#define OT_CHANGED_THREAD_EXT_PANID (1U << 17)             ///< Thread network extended PAN ID changed
#define OT_CHANGED_NETWORK_KEY (1U << 18)                  ///< Network key changed
#define OT_CHANGED_PSKC (1U << 19)                         ///< PSKc changed
#define OT_CHANGED_SECURITY_POLICY (1U << 20)              ///< Security Policy changed
#define OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL (1U << 21)  ///< Channel Manager new pending Thread channel changed
#define OT_CHANGED_SUPPORTED_CHANNEL_MASK (1U << 22)       ///< Supported channel mask changed
#define OT_CHANGED_COMMISSIONER_STATE (1U << 23)           ///< Commissioner state changed
#define OT_CHANGED_THREAD_NETIF_STATE (1U << 24)           ///< Thread network interface state changed
#define OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE (1U << 25) ///< Backbone Router state changed
#define OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL (1U << 26) ///< Local Backbone Router configuration changed
#define OT_CHANGED_JOINER_STATE (1U << 27)                 ///< Joiner state changed
#define OT_CHANGED_ACTIVE_DATASET (1U << 28)               ///< Active Operational Dataset changed
#define OT_CHANGED_PENDING_DATASET (1U << 29)              ///< Pending Operational Dataset changed
#define OT_CHANGED_NAT64_TRANSLATOR_STATE (1U << 30)       ///< The state of NAT64 translator changed
#define OT_CHANGED_PARENT_LINK_QUALITY (1U << 31)          ///< Parent link quality changed

/**
 * Represents a bit-field indicating specific state/configuration that has changed. See `OT_CHANGED_*`
 * definitions.
 *
 */
typedef uint32_t otChangedFlags;

/**
 * Pointer is called to notify certain configuration or state changes within OpenThread.
 *
 * @param[in]  aFlags    A bit-field indicating specific state that has changed.  See `OT_CHANGED_*` definitions.
 * @param[in]  aContext  A pointer to application-specific context.
 *
 */
typedef void (*otStateChangedCallback)(otChangedFlags aFlags, void *aContext);

/**
 * Registers a callback to indicate when certain configuration or state changes within OpenThread.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 * @param[in]  aCallback  A pointer to a function that is called with certain configuration or state changes.
 * @param[in]  aContext   A pointer to application-specific context.
 *
 * @retval OT_ERROR_NONE     Added the callback to the list of callbacks.
 * @retval OT_ERROR_ALREADY  The callback was already registered.
 * @retval OT_ERROR_NO_BUFS  Could not add the callback due to resource constraints.
 *
 */
otError otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext);

/**
 * Removes a callback to indicate when certain configuration or state changes within OpenThread.
 *
 * @param[in]  aInstance   A pointer to an OpenThread instance.
 * @param[in]  aCallback   A pointer to a function that is called with certain configuration or state changes.
 * @param[in]  aContext    A pointer to application-specific context.
 *
 */
void otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext);

/**
 * Triggers a platform reset.
 *
 * The reset process ensures that all the OpenThread state/info (stored in volatile memory) is erased. Note that the
 * `otPlatformReset` does not erase any persistent state/info saved in non-volatile memory.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 *
 */
void otInstanceReset(otInstance *aInstance);

/**
 * Triggers a platform reset to bootloader mode, if supported.
 *
 * Requires `OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE`.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 *
 * @retval OT_ERROR_NONE         Reset to bootloader successfully.
 * @retval OT_ERROR_BUSY         Failed due to another operation is ongoing.
 * @retval OT_ERROR_NOT_CAPABLE  Not capable of resetting to bootloader.
 *
 */
otError otInstanceResetToBootloader(otInstance *aInstance);

/**
 * Deletes all the settings stored on non-volatile memory, and then triggers a platform reset.
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 *
 */
void otInstanceFactoryReset(otInstance *aInstance);

/**
 * Resets the internal states of the OpenThread radio stack.
 *
 * Callbacks and configurations are preserved.
 *
 * This API is only available under radio builds (`OPENTHREAD_RADIO = 1`).
 *
 * @param[in]  aInstance  A pointer to an OpenThread instance.
 *
 */
void otInstanceResetRadioStack(otInstance *aInstance);

/**
 * Erases all the OpenThread persistent info (network settings) stored on non-volatile memory.
 * Erase is successful only if the device is in `disabled` state/role.
 *
 * @param[in]  aInstance A pointer to an OpenThread instance.
 *
 * @retval OT_ERROR_NONE           All persistent info/state was erased successfully.
 * @retval OT_ERROR_INVALID_STATE  Device is not in `disabled` state/role.
 *
 */
otError otInstanceErasePersistentInfo(otInstance *aInstance);

/**
 * Gets the OpenThread version string.
 *
 * @returns A pointer to the OpenThread version.
 *
 */
const char *otGetVersionString(void);

/**
 * Gets the OpenThread radio version string.
 *
 * @param[in]  aInstance A pointer to an OpenThread instance.
 *
 * @returns A pointer to the OpenThread radio version.
 *
 */
const char *otGetRadioVersionString(otInstance *aInstance);

/**
 * @}
 *
 */

#ifdef __cplusplus
} // extern "C"
#endif

#endif // OPENTHREAD_INSTANCE_H_