NtpPacket Class

Namespace

GuerrillaNtp (view all)

Assembly

GuerrillaNtp.dll

Represents RFC4330 SNTP packet used for communication to and from a network time server.

public class NtpPacket

Remarks

See project homepage for guidance on how to use GuerrillaNtp. Most applications should just use the CorrectionOffset property or even better call NtpClient.GetCorrectionOffset().

The same data structure represents both request and reply packets. Request and reply differ in which properties are set and to what values.

The only real property is Bytes. All other properties read from and write to the underlying byte array with the exception of DestinationTimestamp, which is not part of the packet on network and it is instead set locally after receiving the packet.

See also

Constructors

NtpPacket()

Initializes default request packet.

Properties

Bytes

Gets RFC4330-encoded SNTP packet.

CorrectionOffset

Gets the offset that should be added to local time to synchronize it with server time.

DestinationTimestamp

Gets or sets the time of reception of response SNTP packet on the client.

LeapIndicator

Gets the leap second indicator.

Mode

Gets or sets SNTP packet mode, i.e. whether this is client or server packet.

OriginTimestamp

Gets or sets the time when the client sent its request.

Poll

Gets server's preferred polling interval.

Precision

Gets the precision of server clock.

ReceiveTimestamp

Gets or sets the time when the request was received by the server.

ReferenceId

Gets the ID of the time source used by the server or Kiss-o'-Death code sent by the server.

ReferenceTimestamp

Gets or sets the time when the server clock was last set or corrected.

RootDelay

Gets the total round-trip delay from the server to the reference clock.

RootDispersion

Gets the estimated error in time reported by the server.

RoundTripTime

Gets the round-trip time to the server.

Stratum

Gets server's distance from the reference clock.

TransmitTimestamp

Gets or sets the time when the packet was sent.

VersionNumber

Gets or sets protocol version number.

NtpPacket() Constructor

Initializes default request packet.

public NtpPacket();

Remarks

Created request packet can be passed to NtpClient.Query(NtpPacket). Properties Mode and VersionNumber are set appropriately for request packet. Property TransmitTimestamp is set to DateTime.UtcNow.

See also

Bytes Property

Gets RFC4330-encoded SNTP packet.

public byte[] Bytes { get; }

Value

Byte[]

Byte array containing RFC4330-encoded SNTP packet. It is at least 48 bytes long.

Remarks

This is the only real property. All other properties except DestinationTimestamp read from or write to this byte array.

CorrectionOffset Property

Gets the offset that should be added to local time to synchronize it with server time.

public TimeSpan CorrectionOffset { get; }

Value

TimeSpan

Time difference between server and client. It should be added to local time to get server time. It is calculated from timestamps in the packet as 0.5 * ((t1 - t0) - (t3 - t2)) where t0 is OriginTimestamp, t1 is ReceiveTimestamp, t2 is TransmitTimestamp, and t3 is DestinationTimestamp. This property throws an exception in request packets.

Exceptions

NtpException

Thrown when one of the required timestamps is not present.

See also

DestinationTimestamp Property

Gets or sets the time of reception of response SNTP packet on the client.

public DateTime? DestinationTimestamp { get; set; }

Value

Nullable<DateTime>

Time of reception of response SNTP packet on the client. It is null in request packets.

Remarks

This property is not part of the protocol. It is set by NtpClient when reply packet is received.

See also

LeapIndicator Property

Gets the leap second indicator.

public NtpLeapIndicator LeapIndicator { get; }

Value

NtpLeapIndicator

Leap second warning, if any. Special value NtpLeapIndicator.AlarmCondition indicates unsynchronized server clock. Default is NtpLeapIndicator.NoWarning.

Remarks

Only servers fill in this property. Clients can consult this property for possible leap second warning.

Mode Property

Gets or sets SNTP packet mode, i.e. whether this is client or server packet.

public NtpMode Mode { get; set; }

Value

NtpMode

SNTP packet mode. Default is NtpMode.Client in newly created packets. Server reply should have this property set to NtpMode.Server.

OriginTimestamp Property

Gets or sets the time when the client sent its request.

public DateTime? OriginTimestamp { get; set; }

Value

Nullable<DateTime>

This property is null in request packets. In reply packets, it is the time when the client sent its request. Servers copy this value from TransmitTimestamp that they find in received request packet.

See also

Poll Property

Gets server's preferred polling interval.

public int Poll { get; }

Value

Int32

Polling interval in log₂ seconds, e.g. 4 stands for 16s and 17 means 131,072s.

Precision Property

Gets the precision of server clock.

public int Precision { get; }

Value

Int32

Clock precision in log₂ seconds, e.g. -20 for microsecond precision.

ReceiveTimestamp Property

Gets or sets the time when the request was received by the server.

public DateTime? ReceiveTimestamp { get; set; }

Value

Nullable<DateTime>

This property is null in request packets. In reply packets, it is the time when the server received client request.

See also

ReferenceId Property

Gets the ID of the time source used by the server or Kiss-o'-Death code sent by the server.

public uint ReferenceId { get; }

Value

UInt32

ID of server's time source or Kiss-o'-Death code. Purpose of this property depends on value of Stratum property.

Stratum 1 servers write here one of several special values that describe the kind of hardware clock they use.

Stratum 2 and lower servers set this property to IPv4 address of their upstream server. If upstream server has IPv6 address, the address is hashed, because it doesn't fit in this property.

When server sets Stratum to special value 0, this property contains so called kiss code that instructs the client to stop querying the server.

ReferenceTimestamp Property

Gets or sets the time when the server clock was last set or corrected.

public DateTime? ReferenceTimestamp { get; set; }

Value

Nullable<DateTime>

Time when the server clock was last set or corrected or null when not specified.

Remarks

This Property is usually set only by servers. It usually lags server's current time by several minutes, so don't use this property for time synchronization.

RootDelay Property

Gets the total round-trip delay from the server to the reference clock.

public TimeSpan RootDelay { get; }

Value

TimeSpan

Round-trip delay to the reference clock. Normally a positive value smaller than one second.

RootDispersion Property

Gets the estimated error in time reported by the server.

public TimeSpan RootDispersion { get; }

Value

TimeSpan

Estimated error in time reported by the server. Normally a positive value smaller than one second.

RoundTripTime Property

Gets the round-trip time to the server.

public TimeSpan RoundTripTime { get; }

Value

TimeSpan

Time the request spent travelling to the server plus the time the reply spent travelling back. This is calculated from timestamps in the packet as (t1 - t0) + (t3 - t2) where t0 is OriginTimestamp, t1 is ReceiveTimestamp, t2 is TransmitTimestamp, and t3 is DestinationTimestamp. This property throws an exception in request packets.

Exceptions

NtpException

Thrown when one of the required timestamps is not present.

See also

Stratum Property

Gets server's distance from the reference clock.

public int Stratum { get; }

Value

Int32

Distance from the reference clock. This property is set only in server reply packets. Servers connected directly to reference clock hardware set this property to 1. Statum number is incremented by 1 on every hop down the NTP server hierarchy.

Special value 0 indicates that this packet is a Kiss-o'-Death message with kiss code stored in ReferenceId.

TransmitTimestamp Property

Gets or sets the time when the packet was sent.

public DateTime? TransmitTimestamp { get; set; }

Value

Nullable<DateTime>

Time when the packet was sent. It should never be null. Default value is DateTime.UtcNow.

Remarks

This property must be set by both clients and servers.

See also

VersionNumber Property

Gets or sets protocol version number.

public int VersionNumber { get; set; }

Value

Int32

SNTP protocol version. Default is 4, which is the latest version at the time of this writing.

Remarks

In request packets, clients should leave this property at default value 4. Servers usually reply with the same protocol version.