1 /* 2 * Copyright (c) 2018, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the top-level sntp functions for the OpenThread library. 33 */ 34 35 #ifndef OPENTHREAD_SNTP_H_ 36 #define OPENTHREAD_SNTP_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/ip6.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup api-sntp 48 * 49 * @brief 50 * This module includes functions that control SNTP communication. 51 * 52 * @{ 53 */ 54 55 #define OT_SNTP_DEFAULT_SERVER_IP "2001:4860:4806:8::" ///< Defines default SNTP Server address - Google NTP Server. 56 #define OT_SNTP_DEFAULT_SERVER_PORT 123 ///< Defines default SNTP Server port. 57 58 /** 59 * Implements SNTP Query parameters. 60 */ 61 typedef struct otSntpQuery 62 { 63 const otMessageInfo *mMessageInfo; ///< A reference to the message info related with SNTP Server. 64 } otSntpQuery; 65 66 /** 67 * Pointer is called when a SNTP response is received. 68 * 69 * @param[in] aContext A pointer to application-specific context. 70 * @param[in] aTime Specifies the time at the server when the response left for the client, in UNIX time. 71 * @param[in] aResult A result of the SNTP transaction. 72 * 73 * @retval OT_ERROR_NONE A response was received successfully and time is provided 74 * in @p aTime. 75 * @retval OT_ERROR_ABORT A SNTP transaction was aborted by stack. 76 * @retval OT_ERROR_BUSY The Kiss-o'-death packet has been received. 77 * @retval OT_ERROR_RESPONSE_TIMEOUT No SNTP response has been received within timeout. 78 * @retval OT_ERROR_FAILED A response was received but contains incorrect data. 79 */ 80 typedef void (*otSntpResponseHandler)(void *aContext, uint64_t aTime, otError aResult); 81 82 /** 83 * Sends a SNTP query. 84 * 85 * Is available only if feature `OPENTHREAD_CONFIG_SNTP_CLIENT_ENABLE` is enabled. 86 * 87 * @param[in] aInstance A pointer to an OpenThread instance. 88 * @param[in] aQuery A pointer to specify SNTP query parameters. 89 * @param[in] aHandler A function pointer that shall be called on response reception or time-out. 90 * @param[in] aContext A pointer to arbitrary context information. 91 */ 92 otError otSntpClientQuery(otInstance *aInstance, 93 const otSntpQuery *aQuery, 94 otSntpResponseHandler aHandler, 95 void *aContext); 96 97 /** 98 * Sets the unix era number. 99 * 100 * The default value of unix era is set to 0. The subsequent eras start after year 2106. 101 * 102 * @param[in] aInstance A pointer to an OpenThread instance. 103 * @param[in] aUnixEra Unix era number. 104 */ 105 void otSntpClientSetUnixEra(otInstance *aInstance, uint32_t aUnixEra); 106 107 /** 108 * @} 109 */ 110 111 #ifdef __cplusplus 112 } // extern "C" 113 #endif 114 115 #endif // OPENTHREAD_SNTP_H_ 116
