Xclox
C++11 header-only cross-platform date and time library with an asynchronous NTP client
xclox::ntp::Packet Class Reference

Packet is an immutable raw NTP packet. More...

#include <packet.hpp>

Public Types

using DataType = internal::DataType
 Type of packet's underlying data.
 

Public Member Functions

 Packet (uint8_t leap, uint8_t version, uint8_t mode, uint8_t stratum, int8_t poll, int8_t precision, uint32_t rootDelay, uint32_t rootDispersion, uint32_t referenceID, uint64_t referenceTimestamp, uint64_t originTimestamp, uint64_t receiveTimestamp, uint64_t transmitTimestamp)
 Constructs a NTP packet from the given values.
 
 Packet (const DataType &data)
 Constructs a NTP packet from the given raw data buffer.
 
 Packet ()=default
 Constructs a null NTP packet that has no underlying data. More...
 
 ~Packet ()=default
 Default destructor.
 
 Packet (const Packet &)=default
 Copy constructor.
 
 Packet (Packet &&)=default
 Move constructor.
 
Packetoperator= (const Packet &)=delete
 Copy assignment operator.
 
Packetoperator= (Packet &&)=delete
 Move assignment operator.
 
bool operator== (const Packet &other) const
 Equality operator.
 
bool operator!= (const Packet &other) const
 Inequality operator.
 
DataType data () const
 Returns a raw data representation of the underlying packet.
 
bool isNull () const
 Returns whether the underlying data is all zeros.
 
uint8_t leap () const
 Returns an integer warning of an impending leap second to be inserted or deleted in the last minute of the current month. More...
 
uint8_t version () const
 Returns an unsigned integer representing the NTP version number.
 
uint8_t mode () const
 Returns an unsigned integer representing the relationship between two NTP speakers. More...
 
uint8_t stratum () const
 Returns an unsigned integer representing the level of the server in the NTP hierarchy. More...
 
int8_t poll () const
 Returns a signed integer representing the maximum interval between successive messages, in log2 seconds.
 
int8_t precision () const
 Returns a signed integer representing the precision of the system clock, in log2 seconds.
 
uint32_t rootDelay () const
 Returns the total round-trip delay to the reference clock, in NTP short format.
 
uint32_t rootDispersion () const
 Returns the total dispersion to the reference clock, in NTP short format.
 
uint32_t referenceID () const
 Returns a 32-bit code identifying the particular server or reference clock.
 
uint64_t referenceTimestamp () const
 Returns the server's time at which the system clock was last set or corrected.
 
uint64_t originTimestamp () const
 Returns the client's time at which the packet departed to the server.
 
uint64_t receiveTimestamp () const
 Returns the server's time at which the packet arrived from the client.
 
uint64_t transmitTimestamp () const
 Returns the server's time at which the packet departed to the client.
 
std::chrono::system_clock::duration delay (uint64_t destination) const
 Returns the round-trip delay of the NTP packet passed from client to server and back again. More...
 
std::chrono::system_clock::duration offset (uint64_t destination) const
 Returns the time offset of the server relative to the client. More...
 
std::chrono::system_clock::duration offset (const std::chrono::system_clock::time_point &destination) const
 Returns the time offset of the server relative to the client. More...
 

Detailed Description

Packet is an immutable raw NTP packet.

Packet internally holds only the required NTP fields (48 bytes).

A packet is null if all its data is zeros, and this can be checked with isNull(). Packet is serializable to raw data via toData(). Packet objects are comparable to each other in terms of equality through operators.

Delay and offset calculations can be carried out via delay() and offset(), respectively. The calculations are correct only if:

  • The client clock is consistent across the departure and arrival of the NTP packet.
  • The client clock is within 68 years of the server; otherwise, the returned offset is ambiguous and cannot be resolved correctly to a real timestamp.
See also
The unit tests in packet.h for further details.

Constructor & Destructor Documentation

◆ Packet()

xclox::ntp::Packet::Packet ( )
default

Constructs a null NTP packet that has no underlying data.

See also
isNull()

Member Function Documentation

◆ delay()

std::chrono::system_clock::duration xclox::ntp::Packet::delay ( uint64_t  destination) const
inline

Returns the round-trip delay of the NTP packet passed from client to server and back again.

In some scenarios, it is possible for the delay computation to become negative and misleads the subsequent computations. So, the returned value has to be clamped or checked before further processing.

Parameters
destinationthe client's time at which the packet arrived from the server.

◆ leap()

uint8_t xclox::ntp::Packet::leap ( ) const
inline

Returns an integer warning of an impending leap second to be inserted or deleted in the last minute of the current month.

Value Meaning
0 no warning
1 last minute of the day has 61 seconds
2 last minute of the day has 59 seconds
3 unknown (clock unsynchronized)

◆ mode()

uint8_t xclox::ntp::Packet::mode ( ) const
inline

Returns an unsigned integer representing the relationship between two NTP speakers.

Value Meaning
0 reserved
1 symmetric active
2 symmetric passive
3 client
4 server
5 broadcast
6 NTP control message
7 reserved for private use

◆ offset() [1/2]

std::chrono::system_clock::duration xclox::ntp::Packet::offset ( const std::chrono::system_clock::time_point &  destination) const
inline

Returns the time offset of the server relative to the client.

The time offset can range from 68 years in the past to 68 years in the future. So, the client clock must be set within 68 years of the server before the service is started. This method can calculate the offset correctly for timestamps in the same or adjacent eras.

Parameters
destinationthe client's time at which the packet arrived from the server.

◆ offset() [2/2]

std::chrono::system_clock::duration xclox::ntp::Packet::offset ( uint64_t  destination) const
inline

Returns the time offset of the server relative to the client.

The time offset can range from 136 years in the past to 136 years in the future. However, because timestamps can belong to different eras, ambiguous values may be returned. So, this method is not intended to be used directly, as it works only with timestamps in the same era. Instead, use the overload of this method, which takes a time point to get the correct offset for timestamps in different eras.

Parameters
destinationthe client's time at which the packet arrived from the server.

◆ stratum()

uint8_t xclox::ntp::Packet::stratum ( ) const
inline

Returns an unsigned integer representing the level of the server in the NTP hierarchy.

Value Meaning
0 unspecified or invalid
1 primary server (e.g., equipped with a GPS receiver)
2..15 secondary server (via NTP)
16 unsynchronized
17..255 reserved

The documentation for this class was generated from the following file: