include/openthread/network_time.h

/*
 *  Copyright (c) 2018, 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 Network Time Synchronization Service API.
 */

#ifndef OPENTHREAD_NETWORK_TIME_H_
#define OPENTHREAD_NETWORK_TIME_H_

#include <openthread/error.h>
#include <openthread/instance.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup api-network-time
 *
 * @brief
 *   This module includes functions that control network time synchronization service.
 *
 * @{
 *
 */

/**
 * This enumeration represents OpenThread time synchronization status.
 *
 */
typedef enum otNetworkTimeStatus
{
    OT_NETWORK_TIME_UNSYNCHRONIZED = -1, ///< The device hasn't attached to a network.
    OT_NETWORK_TIME_RESYNC_NEEDED  = 0,  ///< The device hasn’t received time sync for more than two periods time.
    OT_NETWORK_TIME_SYNCHRONIZED   = 1,  ///< The device network time is synchronized.
} otNetworkTimeStatus;

/**
 * This function pointer is called when a network time sync or status change occurs.
 *
 */
typedef void (*otNetworkTimeSyncCallbackFn)(void *aCallbackContext);

/**
 * zero is considered as invalid time synchronization sequence.
 *
 */
#define OT_TIME_SYNC_INVALID_SEQ 0

/**
 * Get the Thread network time.
 *
 * @param[in]    aInstance     The OpenThread instance structure.
 * @param[inout] aNetworkTime  The Thread network time in microseconds.
 *
 * @returns The time synchronization status.
 *
 */
otNetworkTimeStatus otNetworkTimeGet(otInstance *aInstance, uint64_t *aNetworkTime);

/**
 * Set the time synchronization period.
 *
 * This function can only be called while Thread protocols are disabled.
 *
 * @param[in] aInstance         The OpenThread instance structure.
 * @param[in] aTimeSyncPeriod   The time synchronization period, in seconds.
 *
 * @retval OT_ERROR_NONE           Successfully set the time sync period.
 * @retval OT_ERROR_INVALID_STATE  Thread protocols are enabled.
 *
 */
otError otNetworkTimeSetSyncPeriod(otInstance *aInstance, uint16_t aTimeSyncPeriod);

/**
 * Get the time synchronization period.
 *
 * @param[in] aInstance  The OpenThread instance structure.
 *
 * @returns The time synchronization period.
 *
 */
uint16_t otNetworkTimeGetSyncPeriod(otInstance *aInstance);

/**
 * Set the time synchronization XTAL accuracy threshold for Router-Capable device.
 *
 * This function can only be called while Thread protocols are disabled.
 *
 * @param[in] aInstance        The OpenThread instance structure.
 * @param[in] aXTALThreshold   The XTAL accuracy threshold for Router, in PPM.
 *
 * @retval OT_ERROR_NONE           Successfully set the time sync period.
 * @retval OT_ERROR_INVALID_STATE  Thread protocols are enabled.
 *
 */
otError otNetworkTimeSetXtalThreshold(otInstance *aInstance, uint16_t aXTALThreshold);

/**
 * Get the time synchronization XTAL accuracy threshold for Router.
 *
 * @param[in] aInstance  The OpenThread instance structure.
 *
 * @returns The XTAL accuracy threshold for Router, in PPM.
 *
 */
uint16_t otNetworkTimeGetXtalThreshold(otInstance *aInstance);

/**
 * Set a callback to be called when a network time sync or status change occurs
 *
 * This callback shall be called only when the network time offset jumps by
 * OPENTHREAD_CONFIG_TIME_SYNC_JUMP_NOTIF_MIN_US or when the status changes.
 *
 * @param[in] aInstance The OpenThread instance structure.
 * @param[in] aCallbackFn The callback function to be called
 * @param[in] aCallbackContext The context to be passed to the callback function upon invocation
 *
 */
void otNetworkTimeSyncSetCallback(otInstance *                aInstance,
                                  otNetworkTimeSyncCallbackFn aCallbackFn,
                                  void *                      aCallbackContext);

/**
 * @}
 *
 */

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

#endif // OPENTHREAD_NETWORK_TIME_H_