001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.net.ntp;
019
020import java.net.DatagramPacket;
021
022/**
023 * Interface for a NtpV3Packet with get/set methods corresponding to the fields in the NTP Data Message Header described in RFC 1305.
024 */
025public interface NtpV3Packet {
026
027    /**
028     * Standard NTP UDP port
029     */
030    int NTP_PORT = 123;
031
032    /**
033     * {@value}
034     */
035    int LI_NO_WARNING = 0;
036
037    /**
038     * {@value}
039     */
040    int LI_LAST_MINUTE_HAS_61_SECONDS = 1;
041
042    /**
043     * {@value}
044     */
045    int LI_LAST_MINUTE_HAS_59_SECONDS = 2;
046
047    /**
048     * {@value}
049     */
050    int LI_ALARM_CONDITION = 3;
051
052    /** Mode option {@value}. */
053    int MODE_RESERVED = 0;
054
055    /** Mode option {@value}. */
056    int MODE_SYMMETRIC_ACTIVE = 1;
057
058    /** Mode option {@value}. */
059    int MODE_SYMMETRIC_PASSIVE = 2;
060
061    /** Mode option {@value}. */
062    int MODE_CLIENT = 3;
063
064    /** Mode option {@value}. */
065    int MODE_SERVER = 4;
066
067    /** Mode option {@value}. */
068    int MODE_BROADCAST = 5;
069
070    /** Mode option {@value}. */
071    int MODE_CONTROL_MESSAGE = 6;
072
073    /** Mode option {@value}. */
074    int MODE_PRIVATE = 7;
075
076    /**
077     * {@value}
078     */
079    int NTP_MINPOLL = 4; // 16 seconds
080
081    /**
082     * {@value}
083     */
084    int NTP_MAXPOLL = 14; // 16284 seconds
085
086    /**
087     * {@value}
088     */
089    int NTP_MINCLOCK = 1;
090
091    /**
092     * {@value}
093     */
094    int NTP_MAXCLOCK = 10;
095
096    /**
097     * {@value}
098     */
099    int VERSION_3 = 3;
100
101    /**
102     * {@value}
103     */
104    int VERSION_4 = 4;
105
106    //
107    // possible getType values such that other time-related protocols can have its information represented as NTP packets
108    //
109    /**
110     * {@value}
111     */
112    String TYPE_NTP = "NTP"; // RFC-1305/2030
113
114    /**
115     * {@value}
116     */
117    String TYPE_ICMP = "ICMP"; // RFC-792
118
119    /**
120     * {@value}
121     */
122    String TYPE_TIME = "TIME"; // RFC-868
123
124    /**
125     * {@value}
126     */
127    String TYPE_DAYTIME = "DAYTIME"; // RFC-867
128
129    /**
130     * Gets a datagram packet with the NTP parts already filled in.
131     *
132     * @return a datagram packet with the NTP parts already filled in.
133     */
134    DatagramPacket getDatagramPacket();
135
136    /**
137     * Gets the leap indicator as defined in RFC-1305.
138     *
139     * @return the leap indicator as defined in RFC-1305.
140     */
141    int getLeapIndicator();
142
143    /**
144     * Gets the mode as defined in RFC-1305.
145     *
146     * @return the mode as defined in RFC-1305.
147     */
148    int getMode();
149
150    /**
151     * Gets the  mode as human readable string; for example, 3=Client.
152     *
153     * @return the mode as human readable string; for example, 3=Client.
154     */
155    String getModeName();
156
157    /**
158     * Gets the {@code originate} time as defined in RFC-1305.
159     *
160     * @return the {@code originate} time as defined in RFC-1305.
161     */
162    TimeStamp getOriginateTimeStamp();
163
164    /**
165     * Gets the poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
166     *
167     * @return the poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
168     */
169    int getPoll();
170
171    /**
172     * Gets the precision as defined in RFC-1305.
173     *
174     * @return the precision as defined in RFC-1305.
175     */
176    int getPrecision();
177
178    /**
179     * Gets the {@code receive} time as defined in RFC-1305.
180     *
181     * @return the {@code receive} time as defined in RFC-1305.
182     */
183    TimeStamp getReceiveTimeStamp();
184
185    /**
186     * Gets the reference id (32-bit code) as defined in RFC-1305.
187     *
188     * @return the reference id (32-bit code) as defined in RFC-1305.
189     */
190    int getReferenceId();
191
192    /**
193     * Gets the reference ID string.
194     *
195     * @return the reference ID string.
196     */
197    String getReferenceIdString();
198
199    /**
200     * Gets the reference time as defined in RFC-1305.
201     *
202     * @return the reference time as defined in RFC-1305.
203     */
204    TimeStamp getReferenceTimeStamp();
205
206    /**
207     * Gets the root delay as defined in RFC-1305.
208     *
209     * @return the root delay as defined in RFC-1305.
210     */
211    int getRootDelay();
212
213    /**
214     * Gets root delay in milliseconds.
215     *
216     * @return root delay in milliseconds.
217     */
218    double getRootDelayInMillisDouble();
219
220    /**
221     * Gets the root dispersion as defined in RFC-1305.
222     *
223     * @return the root dispersion as defined in RFC-1305.
224     */
225    int getRootDispersion();
226
227    /**
228     * Gets the the root dispersion in milliseconds.
229     *
230     * @return the root dispersion in milliseconds.
231     */
232    long getRootDispersionInMillis();
233
234    /**
235     * Gets the root dispersion in milliseconds.
236     *
237     * @return the root dispersion in milliseconds.
238     */
239    double getRootDispersionInMillisDouble();
240
241    /**
242     * Gets the stratum as defined in RFC-1305.
243     *
244     * @return the stratum as defined in RFC-1305.
245     */
246    int getStratum();
247
248    /**
249     * Gets the {@code transmit} timestamp as defined in RFC-1305.
250     *
251     * @return the {@code transmit} timestamp as defined in RFC-1305.
252     */
253    TimeStamp getTransmitTimeStamp();
254
255    /**
256     * Gets the type of time packet. The values (e.g. NTP, TIME, ICMP, ...) correspond to the protocol used to obtain the timing information.
257     *
258     * @return packet type string identifier
259     */
260    String getType();
261
262    /**
263     * Gets version as defined in RFC-1305.
264     *
265     * @return version as defined in RFC-1305.
266     */
267    int getVersion();
268
269    /**
270     * Sets the contents of this object from the datagram packet
271     *
272     * @param dp the packet
273     */
274    void setDatagramPacket(DatagramPacket dp);
275
276    /**
277     * Sets leap indicator.
278     *
279     * @param li   leap indicator code
280     */
281    void setLeapIndicator(int li);
282
283    /**
284     * Sets mode as defined in RFC-1305
285     *
286     * @param mode the mode to set
287     */
288    void setMode(int mode);
289
290    /**
291     * Sets originate timestamp given NTP TimeStamp object.
292     *
293     * @param ts   timestamp
294     */
295    void setOriginateTimeStamp(TimeStamp ts);
296
297    /**
298     * Sets poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
299     *
300     * @param poll the interval to set
301     */
302    void setPoll(int poll);
303
304    /**
305     * Sets precision as defined in RFC-1305
306     *
307     * @param precision Precision
308     * @since 3.4
309     */
310    void setPrecision(int precision);
311
312    /**
313     * Sets receive timestamp given NTP TimeStamp object.
314     *
315     * @param ts   timestamp
316     */
317    void setReceiveTimeStamp(TimeStamp ts);
318
319    /**
320     * Sets reference clock identifier field.
321     *
322     * @param refId the clock id field to set
323     */
324    void setReferenceId(int refId);
325
326    /**
327     * Sets the reference timestamp given NTP TimeStamp object.
328     *
329     * @param ts   timestamp
330     */
331    void setReferenceTime(TimeStamp ts);
332
333    /**
334     * Sets root delay as defined in RFC-1305
335     *
336     * @param delay the delay to set
337     * @since 3.4
338     */
339    void setRootDelay(int delay);
340
341    /**
342     * Sets the dispersion value.
343     *
344     * @param dispersion the value.
345     * @since 3.4
346     */
347    void setRootDispersion(int dispersion);
348
349    /**
350     * Sets stratum as defined in RFC-1305
351     *
352     * @param stratum the stratum to set
353     */
354    void setStratum(int stratum);
355
356    /**
357     * Sets the {@code transmit} timestamp given NTP TimeStamp object.
358     *
359     * @param ts   timestamp
360     */
361    void setTransmitTime(TimeStamp ts);
362
363    /**
364     * Sets version as defined in RFC-1305
365     *
366     * @param version the version to set
367     */
368    void setVersion(int version);
369
370}