diff --git a/GuerrillaNtp/NtpClient.cs b/GuerrillaNtp/NtpClient.cs index 43570d0..fc975f3 100644 --- a/GuerrillaNtp/NtpClient.cs +++ b/GuerrillaNtp/NtpClient.cs @@ -9,15 +9,22 @@ namespace GuerrillaNtp /// Represents UDP socket used to communicate with RFC4330-compliant SNTP/NTP server. /// /// - /// This class holds unmanaged resources (the socket) and callers are responsible - /// for calling when they are done, - /// perhaps by instantiating this class in using block. + /// + /// See project homepage for guidance on how to use GuerrillaNtp. /// Most applications should just call /// after instantiating this class. Method /// can be used to obtain additional details stored in reply . + /// + /// + /// This class holds unmanaged resources (the socket) and callers are responsible + /// for calling when they are done, + /// perhaps by instantiating this class in using block. + /// + /// /// It is application responsibility to be a good netizen, /// which most importantly means using reasonable polling intervals /// and exponential backoff when querying public NTP server. + /// /// public class NtpClient : IDisposable { @@ -44,6 +51,8 @@ public TimeSpan Timeout /// Creates new from server endpoint. /// /// Endpoint of the remote SNTP server. + /// + /// public NtpClient(IPEndPoint endpoint) { socket = new Socket(endpoint.AddressFamily, SocketType.Dgram, ProtocolType.Udp); @@ -63,7 +72,9 @@ public NtpClient(IPEndPoint endpoint) /// Creates new from server's IP address and optional port. /// /// IP address of remote SNTP server - /// Port of remote SNTP server. Default is 123 (standard SNTP port). + /// Port of remote SNTP server. Default is 123 (standard NTP port). + /// + /// public NtpClient(IPAddress address, int port = 123) : this(new IPEndPoint(address, port)) { } /// @@ -78,14 +89,21 @@ public NtpClient(IPAddress address, int port = 123) : this(new IPEndPoint(addres /// /// Queries the SNTP server and returns correction offset. /// + /// + /// Use this method if you just want correction offset from the server. + /// Call to obtain + /// with additional information besides . + /// /// - /// Time that should be added to local time to synchronize it with SNTP server's time. + /// Offset that should be added to local time to match server time. /// /// Thrown when the server responds with invalid reply packet. /// /// Thrown when no reply is received before is reached /// or when there is an error communicating with the server. /// + /// + /// public TimeSpan GetCorrectionOffset() { return Query().CorrectionOffset; } /// @@ -94,8 +112,11 @@ public NtpClient(IPAddress address, int port = 123) : this(new IPEndPoint(addres /// SNTP request packet to use when querying the network time server. /// SNTP reply packet returned by the server. /// - /// Default constructor of creates valid request packet - /// except for property that must be set explicitly. + /// constructor + /// creates valid request packet, which you can further customize. + /// If you don't need any customization of the request packet, call instead. + /// Returned contains correction offset in + /// property. /// /// /// Thrown when the request packet is invalid or when the server responds with invalid reply packet. @@ -104,6 +125,9 @@ public NtpClient(IPAddress address, int port = 123) : this(new IPEndPoint(addres /// Thrown when no reply is received before is reached /// or when there is an error communicating with the server. /// + /// + /// + /// public NtpPacket Query(NtpPacket request) { request.ValidateRequest(); @@ -120,12 +144,21 @@ public NtpPacket Query(NtpPacket request) /// /// Queries the SNTP server with default options. /// + /// + /// Use this method to obtain additional details from the returned + /// besides . + /// If you just need the correction offset, call instead. + /// You can customize request packed by calling . + /// /// SNTP reply packet returned by the server. /// Thrown when the server responds with invalid reply packet. /// /// Thrown when no reply is received before is reached /// or when there is an error communicating with the server. /// - public NtpPacket Query() { return Query(new NtpPacket() { TransmitTimestamp = DateTime.UtcNow }); } + /// + /// + /// + public NtpPacket Query() { return Query(new NtpPacket()); } } } \ No newline at end of file diff --git a/GuerrillaNtp/NtpException.cs b/GuerrillaNtp/NtpException.cs index 695b856..3bb6970 100644 --- a/GuerrillaNtp/NtpException.cs +++ b/GuerrillaNtp/NtpException.cs @@ -12,7 +12,7 @@ public class NtpException : Exception /// Gets the SNTP packet that caused this exception, if any. /// /// - /// SNTP packet that caused this exception, especially reply packet, + /// SNTP packet that caused this exception, usually reply packet, /// or null if the error is not specific to any packet. /// public NtpPacket Packet { get; private set; } diff --git a/GuerrillaNtp/NtpPacket.cs b/GuerrillaNtp/NtpPacket.cs index 96e1193..2225019 100644 --- a/GuerrillaNtp/NtpPacket.cs +++ b/GuerrillaNtp/NtpPacket.cs @@ -7,13 +7,21 @@ namespace GuerrillaNtp /// Represents RFC4330 SNTP packet used for communication to and from a network time server. /// /// + /// + /// See project homepage for guidance on how to use GuerrillaNtp. + /// Most applications should just use the property + /// or even better call . + /// + /// /// 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 . - /// All other properties read from or write to the underlying byte array. - /// The only exception is - /// that is not part of the protocol. - /// Most appliucations should just use the property. + /// All other properties read from and write to the underlying byte array + /// with the exception of , + /// which is not part of the packet on network and it is instead set locally after receiving the packet. + /// /// /// /// @@ -83,9 +91,15 @@ public NtpMode Mode /// Gets server's distance from the reference clock. /// /// + /// /// 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 . + /// /// public int Stratum { get { return Bytes[1]; } } @@ -106,7 +120,7 @@ public NtpMode Mode public int Precision { get { return (sbyte)Bytes[3]; } } /// - /// Gets the total round trip delay from the server to the reference clock. + /// Gets the total round-trip delay from the server to the reference clock. /// /// /// Round-trip delay to the reference clock. Normally a positive value smaller than one second. @@ -122,14 +136,24 @@ public NtpMode Mode public TimeSpan RootDispersion { get { return GetTimeSpan32(8); } } /// - /// Gets the ID of the time source the server is using or Kiss-o'-Death code sent by the server. + /// Gets the ID of the time source used by the server or Kiss-o'-Death code sent by the server. /// /// + /// /// ID of server's time source or Kiss-o'-Death code. - /// Stratum 1 servers have one of predefined special values here describing the kind of hardware clock used. + /// Purpose of this property depends on value of 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. - /// IPv6 addresses are hashed since they don't fit in this property. - /// When server sets stratum to special value 0, this property contains Kiss-o'-Death code. + /// If upstream server has IPv6 address, the address is hashed, because it doesn't fit in this property. + /// + /// + /// When server sets to special value 0, + /// this property contains so called kiss code that instructs the client to stop querying the server. + /// /// public uint ReferenceId { get { return GetUInt32BE(12); } } @@ -151,7 +175,8 @@ public NtpMode Mode /// /// 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 in request packet. + /// Servers copy this value from + /// that they find in received request packet. /// /// /// @@ -173,6 +198,7 @@ public NtpMode Mode /// /// /// Time when the packet was sent. It should never be null. + /// Default value is . /// /// /// This property must be set by both clients and servers. @@ -189,21 +215,29 @@ public NtpMode Mode /// /// /// This property is not part of the protocol. - /// It is set by on received reply packets. + /// It is set by when reply packet is received. /// /// /// public DateTime? DestinationTimestamp { get; set; } /// - /// Gets the time spent on the wire in both directions together. + /// Gets the round-trip time to the server. /// /// /// 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 (receive - origin) + (destination - transmit). + /// This is calculated from timestamps in the packet as (t1 - t0) + (t3 - t2) + /// where t0 is , + /// t1 is , + /// t2 is , + /// and t3 is . /// This property throws an exception in request packets. /// /// Thrown when one of the required timestamps is not present. + /// + /// + /// + /// /// public TimeSpan RoundTripTime { @@ -219,11 +253,19 @@ public TimeSpan RoundTripTime /// /// /// 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 (receive - origin) - (destination - transmit). + /// It is calculated from timestamps in the packet as 0.5 * ((t1 - t0) - (t3 - t2)) + /// where t0 is , + /// t1 is , + /// t2 is , + /// and t3 is . /// This property throws an exception in request packets. /// /// Thrown when one of the required timestamps is not present. /// + /// + /// + /// + /// /// public TimeSpan CorrectionOffset { @@ -238,15 +280,18 @@ public TimeSpan CorrectionOffset /// Initializes default request packet. /// /// + /// Created request packet can be passed to . /// Properties and - /// are set appropriately for client packet. Property - /// must be set before the packet is sent. + /// are set appropriately for request packet. Property + /// is set to . /// + /// public NtpPacket() : this(new byte[48]) { Mode = NtpMode.Client; VersionNumber = 4; + TransmitTimestamp = DateTime.UtcNow; } internal NtpPacket(byte[] bytes)