| /* |
| * |
| * Copyright (c) 2013-2017 Nest Labs, Inc. |
| * All rights reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| /** |
| * @file |
| * This file contains header for the Time Services feature set, which includes |
| * both time sync and time zone. |
| * WEAVE_CONFIG_TIME must be defined if Time Services are needed |
| * |
| * TimeZoneUtcOffset: coding and decoding of the UTC offset packed binary format |
| * TimeChangeNotification: coding and decoding of the Time Change Notification message |
| * TimeSyncRequest: coding and decoding of the Time Sync Request message |
| * TimeSyncResponse: coding and decoding of the Time Sync Response message |
| * TimeSyncServer: protocol engine for Time Sync Server |
| * TimeSyncClient: protocol engine for Time Sync Client |
| * |
| */ |
| |
| #ifndef WEAVE_TIME_H_ |
| #define WEAVE_TIME_H_ |
| |
| // __STDC_CONSTANT_MACROS must be defined for UINT64_C and INT64_C to be defined for pre-C++11 clib |
| #ifndef __STDC_CONSTANT_MACROS |
| #define __STDC_CONSTANT_MACROS |
| #endif // __STDC_CONSTANT_MACROS |
| #ifndef __STDC_LIMIT_MACROS |
| #define __STDC_LIMIT_MACROS |
| #endif // __STDC_LIMIT_MACROS |
| #include <stdint.h> |
| |
| #include <Weave/Core/WeaveCore.h> |
| #include <Weave/Profiles/ProfileCommon.h> |
| |
| namespace nl { |
| |
| namespace Weave { |
| |
| namespace Profiles { |
| |
| namespace Time { |
| |
| /// type used to store and handle number of microseconds from different epoch |
| /// if used to express system time, the epoch is 1970/1/1 0:00:00 |
| typedef int64_t timesync_t; |
| |
| /// used as a bit mask to be applied to timesync_t |
| /// the highest 6 bits, including sign bit, must be zero, for valid system time |
| #define MASK_INVALID_TIMESYNC UINT64_C(0xFC00000000000000) |
| |
| /// used to initialize timestamp (system time) to some invalid value |
| #define TIMESYNC_INVALID timesync_t(MASK_INVALID_TIMESYNC) |
| |
| /// Maximum value can be expressed if used as system time (microsecond). |
| /// This is the largest value that could pass the masking of #MASK_INVALID_TIMESYNC. |
| #define TIMESYNC_MAX timesync_t(UINT64_MAX & ~(MASK_INVALID_TIMESYNC)) |
| |
| /// maximum value can be expressed if used as system time (second) |
| #define MAX_TIMESYNC_SEC int64_t(TIMESYNC_MAX / UINT64_C(1000000)) |
| |
| #if WEAVE_CONFIG_TIME_PROGRESS_LOGGING |
| #define WEAVE_TIME_PROGRESS_LOG WeaveLogProgress |
| #else // WEAVE_CONFIG_TIME_PROGRESS_LOGGING |
| #define WEAVE_TIME_PROGRESS_LOG(...) |
| #endif // WEAVE_CONFIG_TIME_PROGRESS_LOGGING |
| |
| /// type of a message, used with Weave Exchange |
| enum |
| { |
| kTimeMessageType_TimeSyncTimeChangeNotification = 0, |
| kTimeMessageType_TimeSyncRequest = 1, |
| kTimeMessageType_TimeSyncResponse = 2, |
| }; |
| |
| /// Profile-specific tags used in WDM queries for timezone information |
| enum |
| { |
| kWdmTagTime_Zone_Name = 0x00, ///< The IANA Timezone name in UTF8-String format |
| kWdmTagTime_Zone_POSIX_TZ = 0x01, ///< The POSIX TZ environment variable in UTF8-String format |
| kWdmTagTime_Zone_UTC_Offset = 0x02 ///< The UTC offsets for this timezone, in packed binary format |
| }; |
| |
| /// Roles a protocol engine can play. |
| /// for example, a TimeSyncServer could be playing a Server or part of a Coordinator. |
| /// likewise, a TimeSyncClient could be playing a Client or just part of a Coordinator. |
| enum TimeSyncRole |
| { |
| kTimeSyncRole_Unknown = 0, |
| kTimeSyncRole_Server = 1, |
| kTimeSyncRole_Coordinator = 2, |
| kTimeSyncRole_Client = 3, |
| }; |
| |
| /// Codec for UTC offset of a timezone |
| class NL_DLL_EXPORT TimeZoneUtcOffset |
| { |
| public: |
| |
| /// conversion information |
| struct UtcOffsetRecord |
| { |
| timesync_t mBeginAt_usec; ///< UTC time, in usec since standard epoch, |
| ///< of the beginning of this conversion period |
| int32_t mUtcOffset_sec; ///< Offset, in seconds, from UTC to local time |
| }; |
| |
| /// number of valid entries in mUtcOffsetRecord |
| uint8_t mSize; |
| |
| /// entries of UTC offsets |
| UtcOffsetRecord mUtcOffsetRecord[WEAVE_CONFIG_TIME_NUM_UTC_OFFSET_RECORD]; |
| |
| TimeZoneUtcOffset() : |
| mSize(0) |
| { |
| } |
| |
| /** |
| * convert UTC time to local time, using the UTC offsets stored. |
| * |
| * @param[out] aLocalTime A pointer to the resulting local time |
| * |
| * @param[in] aUtcTime UTC time |
| * |
| * @return WEAVE_NO_ERROR On success. WEAVE_ERROR_KEY_NOT_FOUND if it couldn't find reasonable results |
| */ |
| WEAVE_ERROR GetCurrentLocalTime(timesync_t * const aLocalTime, const timesync_t aUtcTime) const; |
| |
| /** |
| * decode UTC offsets from a byte string, extracted from Weave TLV. |
| * data type for size is the same as WeaveTLV.h |
| * |
| * @param[in] aInputBuf A pointer to the input data buffer |
| * |
| * @param[in] aDataSize number of bytes available |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Decode(const uint8_t * const aInputBuf, const uint32_t aDataSize); |
| |
| /// TimeZoneUtcOffset::BufferSizeForEncoding is a compile time constant, which can be used to declare byte arrays. |
| /// Callers shall prepare enough buffer size for encoding to complete successfully, and BufferSizeForEncoding is |
| /// the longest buffer that could be needed. |
| static const uint32_t BufferSizeForEncoding = 2 + 8 + 4 + (WEAVE_CONFIG_TIME_NUM_UTC_OFFSET_RECORD - 1) * 8; |
| |
| /** |
| * encode UTC offsets into a buffer. |
| * data type for size is the same as WeaveTLV.h |
| * |
| * @param[out] aOutputBuf A pointer to the output data buffer |
| * |
| * @param[in/out] aDataSize A pointer to number of bytes available in aOutputBuf at calling and will be changed |
| * to indicate number of bytes used after the function returns. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Encode(uint8_t * const aOutputBuf, uint32_t * const aDataSize); |
| }; |
| |
| /// codec for Time Change Notification message |
| class NL_DLL_EXPORT TimeChangeNotification |
| { |
| public: |
| /// default constructor shall be used with Decode, as all members will be initialized through decoding |
| TimeChangeNotification(void); |
| |
| /** |
| * encode time change notification into an PacketBuffer. |
| * |
| * @param[out] aMsg A pointer to the PacketBuffer |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Encode(PacketBuffer* const aMsg); |
| |
| /** |
| * decode time change notification from an PacketBuffer. |
| * |
| * @param[out] aObject A pointer to the decoded object |
| * |
| * @param[in] aMsg A pointer to the PacketBuffer |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| static WEAVE_ERROR Decode(TimeChangeNotification * const aObject, PacketBuffer* const aMsg); |
| }; |
| |
| // codec for Time Sync Request message |
| class NL_DLL_EXPORT TimeSyncRequest |
| { |
| public: |
| |
| /// default constructor shall be used with Decode, as all members will be initialized through decoding |
| TimeSyncRequest(void); |
| |
| /** |
| * initialize this object for encoding. |
| * |
| * @param[in] aLikelihood intended likelihood of response for this time sync request |
| * |
| * @param[in] aIsTimeCoordinator true if the originator of this request is a Time Sync Coordinator |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| void Init(const uint8_t aLikelihood, const bool aIsTimeCoordinator); |
| |
| /** |
| * encode time sync request into an PacketBuffer. |
| * |
| * @param[out] aMsg A pointer to the PacketBuffer |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Encode(PacketBuffer* const aMsg); |
| |
| /** |
| * decode time sync request from an PacketBuffer. |
| * |
| * @param[out] aObject A pointer to the decoded object |
| * |
| * @param[in] aMsg A pointer to the PacketBuffer |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| static WEAVE_ERROR Decode(TimeSyncRequest * const aObject, PacketBuffer* const aMsg); |
| |
| /// minimum and maxiumum settings for the intended likelihood of response |
| /// for this time sync request. |
| /// Note that we cannot put check on kLikelihoodForResponse_Min in the Encode and Decode |
| /// routines because it's 0, so it's not safe to adjust it just at here |
| enum |
| { |
| kLikelihoodForResponse_Min = 0, |
| kLikelihoodForResponse_Max = 31, |
| }; |
| |
| // Time Sync Request Payload length |
| enum |
| { |
| kPayloadLen = 2, |
| }; |
| |
| /// intended likelihood of response for this time sync request. |
| uint8_t mLikelihoodForResponse; |
| |
| /// true if the originator of this request is a Time Sync Coordinator |
| bool mIsTimeCoordinator; |
| }; |
| |
| // codec for Time Sync Response message |
| class NL_DLL_EXPORT TimeSyncResponse |
| { |
| public: |
| /// default constructor shall be used with Decode, as all members will be initialized through decoding |
| TimeSyncResponse(void); |
| |
| /** |
| * initialize this object for encoding. |
| * |
| * @param[in] aRole the role this responder is playing. |
| * can be either kTimeSyncRole_Server or kTimeSyncRole_Coordinator |
| * |
| * @param[in] aTimeOfRequest the system time when the original request was received |
| * |
| * @param[in] aTimeOfResponse the system time when this response is being sent out |
| * |
| * @param[in] aNumContributorInLastLocalSync number of nodes contributed in the last local time sync |
| * |
| * @param[in] aTimeSinceLastSyncWithServer_min number of minutes passed since last sync with a Server |
| * |
| */ |
| void Init(const TimeSyncRole aRole, const timesync_t aTimeOfRequest, const timesync_t aTimeOfResponse, |
| const uint8_t aNumContributorInLastLocalSync, const uint16_t aTimeSinceLastSyncWithServer_min); |
| |
| /// maximum number of contributors in the last successful time sync operation on local fabric |
| enum |
| { |
| kNumberOfContributor_Max = 31, |
| }; |
| |
| /// time, in number of minutes, since last successful time sync with some proxy of atomic time. |
| /// kTimeSinceLastSyncWithServer_Invalid means this happened too long ago to be relevant, if ever |
| enum |
| { |
| kTimeSinceLastSyncWithServer_Max = 4094, |
| kTimeSinceLastSyncWithServer_Invalid = 4095, |
| }; |
| |
| /** |
| * encode time sync response into an PacketBuffer. |
| * |
| * @param[out] aMsg A pointer to the PacketBuffer |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Encode(PacketBuffer* const aMsg); |
| |
| /** |
| * decode time sync response from an PacketBuffer. |
| * |
| * @param[out] aObject A pointer to the decoded object |
| * |
| * @param[in] aMsg A pointer to the PacketBuffer |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| static WEAVE_ERROR Decode(TimeSyncResponse * const aObject, PacketBuffer* const aMsg); |
| |
| /// true if this response is constructed by a coordinator; |
| /// false implies this response is constructed by a server. |
| bool mIsTimeCoordinator; |
| |
| /// number of local contributors (coordinators or servers) used in last successful time sync |
| uint8_t mNumContributorInLastLocalSync; |
| |
| /// time, in number of minutes, since last successful time sync with some proxy of atomic time |
| uint16_t mTimeSinceLastSyncWithServer_min; |
| |
| /// system time (number of microseconds since 1970/1/1 0:00:00) when the request arrived |
| timesync_t mTimeOfRequest; |
| |
| /// system time (number of microseconds since 1970/1/1 0:00:00) when the response was prepared |
| timesync_t mTimeOfResponse; |
| }; |
| |
| class _TimeSyncNodeBase |
| { |
| protected: |
| _TimeSyncNodeBase(void); |
| |
| void Init(WeaveFabricState * const aFabricState, |
| WeaveExchangeManager * const aExchangeMgr); |
| |
| public: |
| WeaveFabricState * GetFabricState(void) const |
| { |
| return FabricState; |
| } |
| |
| WeaveExchangeManager * GetExchangeMgr(void) const |
| { |
| return ExchangeMgr; |
| } |
| |
| private: |
| WeaveFabricState * FabricState; |
| WeaveExchangeManager *ExchangeMgr; |
| }; |
| |
| /// This is in the public because the TimeSyncNode::FilterTimeCorrectionContributor callback gives |
| /// a global view to higher layer. |
| /// It's put in the open instead of being a nested class to make |
| /// class declaration of TimeSyncNode shorter, and also the export declaration more explicit. |
| struct NL_DLL_EXPORT Contact |
| { |
| /// contains CommState. casted to uint8_t to save space. |
| /// always valid |
| uint8_t mCommState; |
| |
| /// count the number of communication errors have happened for this contact. |
| /// only valid when mCommState is not kCommState_Invalid |
| uint8_t mCountCommError; |
| |
| /// contains ResponseStatus. casted to uint8_t to save space. |
| /// only valid when mCommState is not kCommState_Invalid |
| uint8_t mResponseStatus; |
| |
| /// contains TimeSyncRole. casted to uint8_t to save space |
| /// only valid if response is not kResponseStatus_Invalid |
| uint8_t mRole; |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| /// true if this contact is learned from time change notification |
| /// only valid when mCommState is not kCommState_Invalid |
| bool mIsTimeChangeNotification; |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| /// only valid if response is not kResponseStatus_Invalid |
| uint8_t mNumberOfContactUsedInLastLocalSync; |
| |
| /// only valid if response is not kResponseStatus_Invalid |
| uint16_t mTimeSinceLastSuccessfulSync_min; |
| |
| /// node ID of this contact |
| /// only valid when mCommState is not kCommState_Invalid |
| uint64_t mNodeId; |
| |
| /// node address of this contact |
| /// only valid when mCommState is not kCommState_Invalid |
| IPAddress mNodeAddr; |
| |
| /// used to store the system time of remote node, when the |
| /// response message was prepared for transmission. |
| /// only valid if response is not kResponseStatus_Invalid |
| timesync_t mRemoteTimestamp_usec; |
| |
| /// used to store one way flight time. |
| /// only valid if response is not kResponseStatus_Invalid |
| int32_t mFlightTime_usec; |
| |
| /// this is the timestamp when the response was received. |
| /// only valid if response is not kResponseStatus_Invalid |
| timesync_t mUnadjTimestampLastContact_usec; |
| }; |
| |
| /// used to specify contacts for calling SyncWithNodes |
| /// It's put in the open instead of being a nested class to make |
| /// class declaration of TimeSyncNode shorter, and also the export declaration more explicit. |
| struct NL_DLL_EXPORT ServingNode |
| { |
| uint64_t mNodeId; |
| IPAddress mNodeAddr; |
| }; |
| |
| class NL_DLL_EXPORT TimeSyncNode: |
| public _TimeSyncNodeBase |
| { |
| public: |
| |
| /// current state of this Time Sync Server |
| enum ServerState |
| { |
| kServerState_Uninitialized = 0, |
| kServerState_ContructionFailed, |
| kServerState_Constructed, |
| kServerState_InitializationFailed, |
| |
| /// time reserved for the server to sync its system time through some other means |
| /// only meaningful if aIsAlwaysFresh is true when Init is called |
| kServerState_UnreliableAfterBoot, |
| |
| /// the server is ready to respond to requests with normal settings |
| kServerState_Idle, |
| |
| kServerState_ShutdownCompleted, |
| kServerState_ShutdownFailed, |
| }; |
| |
| /// current state of this Time Sync Client |
| enum ClientState |
| { |
| kClientState_Uninitialized = 0, |
| kClientState_ContructionFailed, |
| kClientState_Constructed, |
| kClientState_InitializationFailed, |
| |
| kClientState_BeginNormal, |
| kClientState_Idle, |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| kClientState_Sync_Discovery, |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| kClientState_Sync_1, |
| kClientState_Sync_2, |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| kClientState_ServiceSync_1, |
| kClientState_ServiceSync_2, |
| #endif // WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| |
| kClientState_EndNormal, |
| |
| kClientState_ShutdownNeeded, |
| kClientState_ShutdownCompleted, |
| kClientState_ShutdownFailed, |
| }; |
| |
| /// status of communication to a certain contact. |
| /// This is in the public because Contact is in public |
| enum CommState |
| { |
| kCommState_Invalid = 0, |
| kCommState_Idle, |
| kCommState_Active, |
| kCommState_Completed, |
| }; |
| |
| /// status of stored response to a certain contact. |
| /// This is in the public because Contact is in public |
| enum ResponseStatus |
| { |
| kResponseStatus_Invalid = 0, |
| kResponseStatus_ReliableResponse, |
| kResponseStatus_LessReliableResponse, |
| kResponseStatus_UnusableResponse, |
| }; |
| |
| |
| TimeSyncNode(void); |
| |
| /** |
| * stop the service, no matter which role it is playing. |
| * This function must be called to properly reclaim resources allocated, before |
| * another call to any of the init functions can be made. |
| * not available in callbacks. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Shutdown(void); |
| |
| #if WEAVE_CONFIG_TIME_ENABLE_COORDINATOR |
| /** |
| * initialize this coordinator. |
| * |
| * @param[in] aExchangeMgr A pointer to system wide Weave Exchange Manager object |
| * |
| * @param[in] aEncryptionType encryption type to be used for requests and responses |
| * |
| * @param[in] aKeyId key id to be used for requests and responses |
| * |
| * @param[in] aSyncPeriod_msec number of msec between syncing |
| * |
| * @param[in] aNominalDiscoveryPeriod_msec shortest time between discovery, in msec, if no communication error is observed |
| * |
| * @param[in] aShortestDiscoveryPeriod_msec smallest number of msec between discovery, if communication error has been observed |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR InitCoordinator(nl::Weave::WeaveExchangeManager *aExchangeMgr, const uint8_t aEncryptionType = |
| nl::Weave::kWeaveEncryptionType_None, |
| const uint16_t aKeyId = nl::Weave::WeaveKeyId::kNone, |
| const int32_t aSyncPeriod_msec = WEAVE_CONFIG_TIME_CLIENT_SYNC_PERIOD_MSEC |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| , |
| const int32_t aNominalDiscoveryPeriod_msec = WEAVE_CONFIG_TIME_CLIENT_NOMINAL_DISCOVERY_PERIOD_MSEC, |
| const int32_t aShortestDiscoveryPeriod_msec = WEAVE_CONFIG_TIME_CLIENT_MINIMUM_DISCOVERY_PERIOD_MSEC |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| ); |
| |
| #endif // WEAVE_CONFIG_TIME_ENABLE_COORDINATOR |
| |
| #if WEAVE_CONFIG_TIME_ENABLE_SERVER |
| /** |
| * initialize for the Server role |
| * must be called as the first function after object construction |
| * if the intention is to be a Time Sync Server. |
| * not available in callbacks |
| * |
| * @param[in] aApp A pointer to higher layer data, used in callbacks to higher layer. |
| * |
| * @param[in] aExchangeMgr A pointer to system wide Weave Exchange Manager object |
| * |
| * @param[in] aIsAlwaysFresh could be set to true to indicate the server is always synced |
| * except for the initial unreliable time. |
| * shall be set to false for Coordinator. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR InitServer(void * const aApp, WeaveExchangeManager * const aExchangeMgr, |
| const bool aIsAlwaysFresh = true); |
| |
| |
| /** |
| * callback to indicate we just received a time sync request. |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * |
| * @param[in] aMsgInfo A WeaveMessageInfo containing information about the received |
| * time sync request, including information about the sender. |
| * |
| * @param[in] aLikelyhood likelihood of response as requested by the originator |
| * |
| * @param[in] aIsTimeCoordinator true if the originating node is a Time Sync Coordinator |
| * |
| * @return false and the engine shall ignore this request |
| */ |
| typedef bool (*OnSyncRequestReceivedHandler)(void * const aApp, const WeaveMessageInfo *aMsgInfo, |
| const uint8_t aLikelyhood, |
| const bool aIsTimeCoordinator); |
| |
| /// if not set, the default implementation always returns true |
| OnSyncRequestReceivedHandler OnSyncRequestReceived; |
| |
| /// simple getter for the server state |
| ServerState GetServerState(void) const; |
| |
| /// Called by higher layer to indicate that we just finished a round of time sync |
| /// with either any Server or through some reliable means like NTP. |
| /// not available in callbacks. |
| void RegisterCorrectionFromServerOrNtp(void); |
| |
| /** |
| * Called by higher layer to indicate that we just finished a round of time sync with |
| * other local Coordinators. |
| * not available in callbacks. |
| * |
| * @param[in] aNumContributor number of coordinators contributed to this time sync |
| * |
| */ |
| void RegisterLocalSyncOperation(const uint8_t aNumContributor); |
| |
| /** |
| * Called by higher layer to multicast time change notification. |
| * not available in callbacks. |
| * |
| * @param[in] aEncryptionType type of encryption to be used for this notification |
| * |
| * @param[in] aKeyId key id to be used for this notification |
| * |
| */ |
| void MulticastTimeChangeNotification(const uint8_t aEncryptionType, const uint16_t aKeyId) const; |
| |
| #endif // #if WEAVE_CONFIG_TIME_ENABLE_SERVER |
| |
| #if WEAVE_CONFIG_TIME_ENABLE_CLIENT |
| |
| /** |
| * initialize this client. |
| * not available in callbacks |
| * |
| * @param[in] aApp A pointer to higher layer data, used in callbacks to higher layer. |
| * |
| * @param[in] aExchangeMgr A pointer to system wide Weave Exchange Manager object |
| * |
| * @param[in] aRole can be either kTimeSyncRole_Client or kTimeSyncRole_Coordinator |
| * |
| * @param[in] aEncryptionType encryption type to be used for requests and responses |
| * |
| * @param[in] aKeyId key id to be used for requests and responses |
| * |
| * @param[in] aInitialLikelyhood initial likelihood to be used for discovery stage |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR InitClient(void * const aApp, WeaveExchangeManager *aExchangeMgr, |
| const uint8_t aEncryptionType = kWeaveEncryptionType_None, |
| const uint16_t aKeyId = WeaveKeyId::kNone |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| , |
| const int8_t aInitialLikelyhood = TimeSyncRequest::kLikelihoodForResponse_Min |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| ); |
| |
| /** |
| * callback to indicate we just received a Time Change Notification. |
| * if auto sync mode is enabled, a time sync would be scheduled shortly |
| * after this callback automatically. |
| * otherwise the application layer can choose to call Sync family of functions |
| * to directly kick off sync operation not restricted by the normal |
| * not-available-in-call-back rule. however, it must be noted that |
| * this special callback is still on top of callback stack of weave exchange |
| * layer. |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * |
| * @param[in] aNodeId requesting node ID |
| * |
| * @param[in] aNodeAddr requesting node address |
| * |
| */ |
| typedef void (*TimeChangeNotificationHandler)(void * const aApp, const uint64_t aNodeId, |
| const IPAddress & aNodeAddr); |
| TimeChangeNotificationHandler OnTimeChangeNotificationReceived; |
| |
| /** |
| * callback happens right before we calculate the time correction from responses. |
| * application layer could overwrite aContact[i].mResponseStatus to kResponseStatus_Invalid |
| * so that response would be ignored in the calculation |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * |
| * @param[in] aContact array of contacts and response status |
| * |
| * @param[in] aSize number of records in the aContact array |
| * |
| */ |
| typedef void (*ContributorFilter)(void * const aApp, Contact aContact[], const int aSize); |
| ContributorFilter FilterTimeCorrectionContributor; |
| |
| /** |
| * callback happens after sync is considered successful, including auto sync, |
| * but before the result is applied. Note that successful doesn't mean we have |
| * applicable results. In case no response was received, aNumContributor would |
| * be set to 0. |
| * application layer could overwrite aContact[i].mResponseStatus to kResponseStatus_Invalid |
| * so that response would be ignored in the calculation |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * |
| * @param[in] aOffsetUsec amount of correction in usec |
| * |
| * @param[in] aIsReliable is the correction considered reliable by the built-in logic |
| * |
| * @param[in] aIsServer does the correction come from Server(s) |
| * |
| * @param[in] aNumContributor number of nodes which contributed to this correction. |
| * 0 means there is no results from sync operation. |
| * |
| * @return true if this offset shall be used to adjust system time. |
| * in case aNumContributor is 0, the return value would be |
| * ignored. |
| * |
| */ |
| typedef bool (*SyncSucceededHandler)(void * const aApp, const timesync_t aOffsetUsec, const bool aIsReliable, |
| const bool aIsServer, const uint8_t aNumContributor); |
| |
| /// if not set, the default behavior is taking all results, except for very small server corrections |
| SyncSucceededHandler OnSyncSucceeded; |
| |
| /** |
| * callback happens when sync is considered failed, including auto sync. |
| * note that callback doesn't happen if Abort is called to stop syncing |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * |
| * @param[in] aErrorCode reason for the failure |
| * |
| */ |
| typedef void (*SyncFailedHandler)(void * const aApp, const WEAVE_ERROR aErrorCode); |
| SyncFailedHandler OnSyncFailed; |
| |
| /// simple getter for client state |
| ClientState GetClientState(void) const; |
| |
| /// simple getter for the maximum number of contacts this engine is configured to store |
| int GetCapacityOfContactList(void) const; |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| /** |
| * extract the likelihood for persistent. |
| * the result would only be valid after sync operation is completed, within callbacks of OnSyncSucceeded and OnSyncFailed. |
| * otherwise it's transient and might be the current Likelihood rather than the next one to be used. |
| * |
| * @return likelihood for response to be used in the next request |
| * |
| */ |
| int8_t GetNextLikelihood(void) const; |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| /** |
| * enable auto sync. |
| * only available in idle state. |
| * discovery happens right away. |
| * not available in callbacks. |
| * |
| * @param[in] aSyncPeriod_msec number of msec between syncing |
| * |
| * @param[in] aNominalDiscoveryPeriod_msec number of msec between discovery, if no communication error is observed |
| * |
| * @param[in] aShortestDiscoveryPeriod_msec shortest time between discovery, in msec, if communication error has been observed |
| * |
| * @return WEAVE_NO_ERROR on success |
| * |
| */ |
| WEAVE_ERROR EnableAutoSync( |
| const int32_t aSyncPeriod_msec = WEAVE_CONFIG_TIME_CLIENT_SYNC_PERIOD_MSEC |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| , |
| const int32_t aNominalDiscoveryPeriod_msec = WEAVE_CONFIG_TIME_CLIENT_NOMINAL_DISCOVERY_PERIOD_MSEC, |
| const int32_t aShortestDiscoveryPeriod_msec = WEAVE_CONFIG_TIME_CLIENT_MINIMUM_DISCOVERY_PERIOD_MSEC |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| ); |
| |
| /// disable auto sync. |
| /// only available in idle state. |
| /// not available in callbacks. |
| void DisableAutoSync(void); |
| |
| /** |
| * sync using existing contacts. |
| * sync operation could fail if there is no valid contacts available. |
| * set aForceDiscoverAgain to true to force discovery immediately. |
| * only available in idle state. |
| * not available in callbacks. |
| * |
| * @param[in] aForceDiscoverAgain true if all existing contacts shall be flushed and |
| * discovery operation performed |
| * |
| * @return WEAVE_NO_ERROR on success |
| * |
| */ |
| WEAVE_ERROR Sync( |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| const bool aForceDiscoverAgain = false |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| ); |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| /** |
| * sync using the given TCP connection and associated encryption and key id. |
| * caller must take ownership of the TCP connection after sync finishes. |
| * no callback would be overwritten for the TCP connection, as a new Weave Exchange |
| * would be created and callbacks set on top of that context |
| * only available in idle state. |
| * not available in callbacks. |
| * |
| * @param[in] aConnection A pointer to Weave connection |
| * |
| * @return WEAVE_NO_ERROR on success |
| * |
| */ |
| WEAVE_ERROR SyncWithService(WeaveConnection * const aConnection); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| |
| /** |
| * sync using the given list of contacts. |
| * existing contact list would be flushed. |
| * only available in idle state. |
| * not available in callbacks. |
| * |
| * @param[in] aNumNode number of contact in array aNodes |
| * |
| * @param[in] aNodes array of contact records |
| * |
| * @return WEAVE_NO_ERROR on success |
| * |
| */ |
| WEAVE_ERROR SyncWithNodes(const int16_t aNumNode, const ServingNode aNodes[]); |
| |
| /** |
| * force the engine to go back to idle state, aborting anything it is doing. |
| * note no sync success or failure would be called. |
| * all Weave Exchanges would be closed. |
| * TCP connections would not be touched further. |
| * no operation if we're already in idle state. |
| * not available in callbacks. |
| * |
| * @return WEAVE_NO_ERROR on success |
| * |
| */ |
| WEAVE_ERROR Abort(void); |
| |
| /// encryption method for local communication |
| uint8_t mEncryptionType; |
| |
| /// key id used for local communication |
| uint16_t mKeyId; |
| #endif // WEAVE_CONFIG_TIME_ENABLE_CLIENT |
| |
| protected: |
| |
| /// pointer to higher layer data |
| void * mApp; |
| |
| /// Actual role of this node |
| TimeSyncRole mRole; |
| |
| /// true if we're in a callback to higher layer |
| bool mIsInCallback; |
| |
| |
| WEAVE_ERROR InitState(const TimeSyncRole aRole, |
| void * const aApp, WeaveExchangeManager * const aExchangeMgr); |
| |
| void ClearState(void); |
| |
| #if WEAVE_CONFIG_TIME_ENABLE_COORDINATOR |
| |
| /** |
| * stop the coordinator |
| * not available in callbacks. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR _ShutdownCoordinator(void); |
| |
| static bool _OnSyncSucceeded(void * const aApp, const nl::Weave::Profiles::Time::timesync_t aOffsetUsec, |
| const bool aIsReliable, |
| const bool aIsServer, const uint8_t aNumContributor); |
| #endif // WEAVE_CONFIG_TIME_ENABLE_COORDINATOR |
| |
| #if WEAVE_CONFIG_TIME_ENABLE_SERVER |
| |
| ServerState mServerState; |
| bool mIsAlwaysFresh; |
| uint8_t mNumContributorInLastLocalSync; |
| |
| /// note it has to be boot time as we need compensation for sleep time |
| timesync_t mTimestampLastCorrectionFromServerOrNtp_usec; |
| |
| /// note it has to be boot time as we need compensation for sleep time |
| timesync_t mTimestampLastLocalSync_usec; |
| |
| /** |
| * initialize for the Server role. |
| * Intended to be used internally by Init family of public functions. |
| * Must set mClientState before return. |
| * not available in callbacks |
| * |
| * @param[in] aIsAlwaysFresh could be set to true to indicate the server is always synced |
| * except for the initial unreliable time. |
| * shall be set to false for Coordinator. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR _InitServer(const bool aIsAlwaysFresh); |
| |
| |
| /** |
| * stop the server |
| * not available in callbacks. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR _ShutdownServer(void); |
| |
| /// callback from Weave Exchange when a time sync request arrives |
| static void HandleSyncRequest(ExchangeContext *ec, const IPPacketInfo *pktInfo, const WeaveMessageInfo *msgInfo, |
| uint32_t profileId, uint8_t msgType, PacketBuffer *payload); |
| |
| /// callback from Weave Timer when we passed the unreliable after boot barrier |
| static void HandleUnreliableAfterBootTimer(System::Layer* aSystemLayer, void* aAppState, System::Error aError); |
| |
| #endif // WEAVE_CONFIG_TIME_ENABLE_SERVER |
| |
| |
| #if WEAVE_CONFIG_TIME_ENABLE_CLIENT |
| |
| ClientState mClientState; |
| |
| //@{ |
| /// states used for auto sync feature. |
| bool mIsAutoSyncEnabled; |
| int32_t mSyncPeriod_msec; |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| bool mIsUrgentDiscoveryPending; |
| int32_t mNominalDiscoveryPeriod_msec; |
| int32_t mShortestDiscoveryPeriod_msec; |
| timesync_t mBootTimeForNextAutoDiscovery_usec; |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| //@} |
| |
| /// Contact information learned throughout discovery |
| Contact mContacts[WEAVE_CONFIG_TIME_CLIENT_MAX_NUM_CONTACTS]; |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| // contact information for talking to the service. this is independent from mContacts, so talking to the service |
| // doesn't wipe out results learned from discovery |
| Contact mServiceContact; |
| |
| /// TCP connection used to talk to the service |
| WeaveConnection * mConnectionToService; |
| #endif // WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| |
| //@{ |
| /// communication context. |
| //CommToken mCommToken[WEAVE_CONFIG_TIME_CLIENT_MAX_NUM_EXCHANGE_CONTEXTS]; |
| Contact * mActiveContact; |
| ExchangeContext * mExchangeContext; |
| timesync_t mUnadjTimestampLastSent_usec; |
| //@} |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| int8_t mLastLikelihoodSent; |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| /** |
| * initialize for the Client role. |
| * Intended to be used internally by Init family of public functions. |
| * Must set mClientState before return. |
| * not available in callbacks |
| * |
| * @param[in] aEncryptionType encryption type to be used for requests and responses |
| * |
| * @param[in] aKeyId key id to be used for requests and responses |
| * |
| * @param[in] aInitialLikelyhood initial likelihood to be used for discovery stage |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR _InitClient( |
| const uint8_t aEncryptionType, |
| const uint16_t aKeyId |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| , |
| const int8_t aInitialLikelyhood |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| ); |
| |
| |
| /** |
| * stop the client |
| * not available in callbacks. |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR _ShutdownClient(void); |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| /// invalidate contact to the service |
| void InvalidateServiceContact(void); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| |
| /// invalidate all local contacts |
| void InvalidateAllContacts(void); |
| |
| /// set all valid local contacts to idle state and clear the response. |
| /// this is called before we start contacting them one by one |
| int16_t SetAllValidContactsToIdleAndInvalidateResponse(void); |
| |
| /// reset all completed contacts to idle state again, but don't touch the response. |
| /// this is called between two rounds of communication to the same node |
| int16_t SetAllCompletedContactsToIdle(void); |
| |
| /// get the number of contacts that are valid, but we haven't talk to them yet. |
| int16_t GetNumNotYetCompletedContacts(void); |
| |
| /// get the number of 'reliable' responses collected so far. |
| /// called to determine if we have collected enough number of responses |
| int16_t GetNumReliableResponses(void); |
| |
| /// get the next valid and idle contact to talk to |
| Contact * GetNextIdleContact(void); |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| /// return a slot to store contact information |
| Contact * FindReplaceableContact(const uint64_t aNodeId, const IPAddress & aNodeAddr, |
| bool aIsTimeChangeNotification = false); |
| |
| /// process a response coming back from a multicast request |
| void UpdateMulticastSyncResponse(const uint64_t aNodeId, |
| const IPAddress & aNodeAddr, const TimeSyncResponse & aResponse); |
| |
| /// store the contact information of a node who just sent us a time change notification |
| void StoreNotifyingContact(const uint64_t aNodeId, const IPAddress & aNodeAddr); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| /// process a response coming back from a unicast request |
| void UpdateUnicastSyncResponse(const TimeSyncResponse & aResponse); |
| |
| // wrap up a local sync and calculate the correction |
| void EndLocalSyncAndTryCalculateTimeFix(void); |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| // wrap up a sync with the service and calculate the correction |
| void EndServiceSyncAndTryCalculateTimeFix(void); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| |
| /// induce callback to the application layer. |
| /// set aIsSuccessful to false to induce the error callback |
| WEAVE_ERROR CallbackForSyncCompletion(const bool aIsSuccessful, bool aShouldUpdate, |
| const bool aIsCorrectionReliable, const bool aIsFromServer, const uint8_t aNumContributor, |
| const timesync_t aSystemTimestamp_usec, const timesync_t aDiffTime_usec); |
| |
| /// internal abort if aCode is not WEAVE_NO_ERROR |
| void AbortOnError(const WEAVE_ERROR aCode); |
| |
| /// register communication error on a certain contact, and shorten auto discovery period if needed |
| /// aContact can be NULL to indicate we have no one to talk to, and hence just shorten the auto discovery period |
| void RegisterCommError(Contact * const aContact = NULL); |
| |
| /// close the Weave ExchangeContext |
| bool DestroyCommContext(void); |
| |
| /// create new Weave Exchange for unicast communication |
| WEAVE_ERROR SetupUnicastCommContext(Contact * const aContact); |
| |
| /// send unicast sync request to a contact. |
| /// *rIsMessageSent will be set to indicate if the message has been sent out. |
| /// communication errors like address not reachable is not returned, |
| /// so caller shall check both the return code and *rIsMessageSent. |
| WEAVE_ERROR SendSyncRequest(bool * const rIsMessageSent, Contact * const aContact); |
| |
| void SetClientState(const ClientState state); |
| const char * const GetClientStateName(void) const; |
| |
| /// internal function to kick off an auto sync session |
| void AutoSyncNow(void); |
| |
| //@{ |
| /// these state transition functions are internal and cannot return error code as the previous state would have no way |
| /// to handle them. any failure shall result to eventually another state transition (could be timeout) |
| /// if even the timer fails, we are out of trick and could hang in some wrong state |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| void EnterState_Discover(void); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| void EnterState_Sync_1(void); |
| void EnterState_Sync_2(void); |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| void EnterState_ServiceSync_1(void); |
| void EnterState_ServiceSync_2(void); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE |
| //@} |
| |
| static void HandleTimeChangeNotification(ExchangeContext *ec, const IPPacketInfo *pktInfo, |
| const WeaveMessageInfo *msgInfo, uint32_t profileId, uint8_t msgType, PacketBuffer *payload); |
| static void HandleUnicastSyncResponse(ExchangeContext *ec, const IPPacketInfo *pktInfo, |
| const WeaveMessageInfo *msgInfo, uint32_t profileId, uint8_t msgType, PacketBuffer *payload); |
| |
| #if WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| static void HandleMulticastResponseTimeout(System::Layer* aSystemLayer, void* aAppState, System::Error aError); |
| static void HandleMulticastSyncResponse(ExchangeContext *ec, const IPPacketInfo *pktInfo, |
| const WeaveMessageInfo *msgInfo, uint32_t profileId, uint8_t msgType, PacketBuffer *payload); |
| static void HandleAutoDiscoveryTimeout(System::Layer* aSystemLayer, void* aAppState, System::Error aError); |
| #endif // WEAVE_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY |
| |
| static void HandleUnicastResponseTimeout(ExchangeContext * const ec); |
| |
| static void HandleAutoSyncTimeout(System::Layer* aSystemLayer, void* aAppState, System::Error aError); |
| |
| #endif // WEAVE_CONFIG_TIME_ENABLE_CLIENT |
| |
| }; |
| |
| class NL_DLL_EXPORT SingleSourceTimeSyncClient |
| { |
| public: |
| |
| /// current state of this Time Sync Client |
| enum ClientState |
| { |
| kClientState_Idle, //< Initialized, waiting for Time Change Notification, but no actual time sync operation is happening |
| kClientState_Sync_1, //< Working on the first time sync attempt |
| kClientState_Sync_2, //< Working on the second time sync attempt |
| }; |
| |
| /** |
| * @brief |
| * Retrieve current state of this client |
| * |
| * @return current state |
| */ |
| ClientState GetClientState(void) const { return mClientState; }; |
| |
| /** |
| * @brief |
| * Initialize this client. Must be called before other functions can be used. |
| * Zero/NULL initialize all internal data and register with Time Change Notification. |
| * |
| * @param[in] aApp A pointer to higher layer data, used in callbacks to higher layer. |
| * |
| * @param[in] aExchangeMgr A pointer to Exchange Manager, which would be used in registering for Time Change Notification message handler |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| WEAVE_ERROR Init(void * const aApp, WeaveExchangeManager * const aExchangeMgr); |
| |
| /** |
| * @brief |
| * Abort current time sync operation. Release Binding. Abort active exchange. Move back to idle state. |
| * |
| */ |
| void Abort(void); |
| |
| /** |
| * @brief |
| * Callback to indicate we just received a Time Change Notification. |
| * Set to NULL at #Init. If not set, Time Change Notification would be ignored. |
| * App layer is allowed to call Abort and Sync in this callback. |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * @param[in] aEC Exchange context used for this incoming message, which can be used to validate its authenticity |
| * |
| */ |
| typedef void (*TimeChangeNotificationHandler)(void * const aApp, ExchangeContext * aEC); |
| TimeChangeNotificationHandler OnTimeChangeNotificationReceived; |
| |
| /** |
| * @brief |
| * Callback after both time sync attempts have been completed. If #aErrorCode is WEAVE_NO_ERROR, |
| * at least one attempt has succeeded. Otherwise both failed at #aErrorCode indicates the latest failure. |
| * |
| * @param[in] aApp A pointer to app layer data, set in Init. |
| * |
| * @param[in] aErrorCode #WEAVE_NO_ERROR if at least one time sync operation is successful |
| * |
| * @param[in] aCorrectedSystemTime Only valid if #aErrorCode is #WEAVE_NO_ERROR |
| */ |
| typedef void (*SyncCompletionHandler)(void * const aApp, const WEAVE_ERROR aErrorCode, const timesync_t aCorrectedSystemTime); |
| |
| /** |
| * @brief |
| * Sync using the given Binding and makes a callback using the pointer provided. |
| * If there is a time sync operation going on, it would be aborted implicitly without callback being made. |
| * Not available in callback #OnSyncCompleted, but allowed in #OnTimeChangeNotificationReceived . |
| * On error, Abort would be called implicitly before returning from this function. |
| * |
| * @param[in] aBinding Binding to be used in contacting the time server |
| * |
| * @param[in] OnSyncCompleted Callback function to be used after the time sync operations are completed |
| * |
| * @return #WEAVE_NO_ERROR on success |
| * |
| */ |
| WEAVE_ERROR Sync(Binding * const aBinding, SyncCompletionHandler OnSyncCompleted); |
| |
| protected: |
| |
| enum |
| { |
| kFlightTimeMinimum = 0, |
| kFlightTimeInvalid = -1 |
| }; |
| |
| void * mApp; |
| WeaveExchangeManager * mExchangeMgr; |
| Binding * mBinding; |
| bool mIsInCallback; |
| ClientState mClientState; |
| |
| ExchangeContext * mExchangeContext; |
| |
| /// used to store one way flight time. |
| int32_t mFlightTime_usec; |
| |
| timesync_t mUnadjTimestampLastSent_usec; |
| |
| /// used to store the system time of remote node, when the |
| /// response message was about to be sent |
| timesync_t mRemoteTimestamp_usec; |
| |
| /// used to store Timestamp when a result is registered |
| timesync_t mRegisterSyncResult_usec; |
| |
| SyncCompletionHandler mOnSyncCompleted; |
| |
| void RegisterSyncResultIfNewOrBetter(const timesync_t aNow_usec, const timesync_t aRemoteTimestamp_usec, const int32_t aFlightTime_usec); |
| |
| void _AbortWithCallback(const WEAVE_ERROR aErrorCode); |
| |
| WEAVE_ERROR SendSyncRequest(void); |
| |
| void SetClientState(const ClientState state); |
| const char * const GetClientStateName(void) const; |
| |
| static void HandleTimeChangeNotification(ExchangeContext *aEC, const IPPacketInfo *aPktInfo, |
| const WeaveMessageInfo *aMsgInfo, uint32_t aProfileId, uint8_t aMsgType, PacketBuffer *aPayload); |
| |
| static void HandleSyncResponse(ExchangeContext *aEC, const IPPacketInfo *aPktInfo, |
| const WeaveMessageInfo *aMsgInfo, uint32_t aProfileId, uint8_t aMsgType, PacketBuffer *aPayload); |
| |
| void OnSyncResponse(uint32_t aProfileId, uint8_t aMsgType, PacketBuffer *aPayload); |
| |
| static void HandleResponseTimeout(ExchangeContext *aEC); |
| void OnResponseTimeout(void); |
| |
| /// Invalidate the registered information for time correction |
| inline void InvalidateRegisteredResult(void) { mFlightTime_usec = kFlightTimeInvalid; }; |
| |
| /// Check if the registered information for time correction is valid |
| inline bool IsRegisteredResultValid(void) { return mFlightTime_usec >= kFlightTimeMinimum; }; |
| |
| void ProceedToNextState(void); |
| void EnterSync2(void); |
| void FinalProcessing(void); |
| }; |
| |
| } // namespace Time |
| |
| } // namespace Profiles |
| |
| /// Platform-provided time routines. |
| namespace Platform |
| { |
| |
| namespace Time |
| { |
| /** |
| * get CLOCK_MONOTONIC_RAW, CLOCK_MONOTONIC, or equivalent clock reading. |
| * This clock is used to timestamp events that happen with short time in between them. |
| * Higher resolution is expected but doesn't have to be compensated for sleep time. |
| * Note that it is okay if it comes with sleep time compensation, but higher resolution is the key. |
| * Without better alternatives, this can be implemented by GetSleepCompensatedMonotonicTime. |
| * |
| * @param[out] p_timestamp_usec A pointer to the clock reading |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| NL_DLL_EXPORT WEAVE_ERROR GetMonotonicRawTime(Profiles::Time::timesync_t * const p_timestamp_usec); |
| |
| /** |
| * get CLOCK_REALTIME or equivalent clock reading. |
| * |
| * @param[out] p_timestamp_usec A pointer to the clock reading |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| NL_DLL_EXPORT WEAVE_ERROR GetSystemTime(Profiles::Time::timesync_t * const p_timestamp_usec); |
| |
| /** |
| * get CLOCK_REALTIME or equivalent clock reading in ms. |
| * |
| * @param[out] p_timestamp_msec A pointer to the clock reading |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| NL_DLL_EXPORT WEAVE_ERROR GetSystemTimeMs(Profiles::Time::timesync_t * const p_timestamp_msec); |
| |
| /** |
| * set CLOCK_REALTIME or equivalent clock. |
| * |
| * @param[in] timestamp_usec intended new value for CLOCK_REALTIME |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| NL_DLL_EXPORT WEAVE_ERROR SetSystemTime(const Profiles::Time::timesync_t timestamp_usec); |
| |
| /** |
| * get CLOCK_BOOTTIME or equivalent clock reading. |
| * This clock is used to timestamp events that happen long time apart. |
| * Highest resolution is not the concern but it must be compensated for sleep time. |
| * |
| * @param[out] p_timestamp_usec A pointer to the clock reading |
| * |
| * @return WEAVE_NO_ERROR on success |
| */ |
| NL_DLL_EXPORT WEAVE_ERROR GetSleepCompensatedMonotonicTime(Profiles::Time::timesync_t * const p_timestamp_usec); |
| |
| } // namespace Time |
| |
| } // namespace Platform |
| |
| } // namespace Weave |
| |
| } // namespace nl |
| |
| #endif // WEAVE_TIME_H_ |
