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 *      http://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     * @return a datagram packet with the NTP parts already filled in
131     */
132    DatagramPacket getDatagramPacket();
133
134    /**
135     * @return leap indicator as defined in RFC-1305
136     */
137    int getLeapIndicator();
138
139    /**
140     * @return mode as defined in RFC-1305
141     */
142    int getMode();
143
144    /**
145     * @return mode as human readable string; e.g. 3=Client
146     */
147    String getModeName();
148
149    /**
150     * @return the {@code originate} time as defined in RFC-1305
151     */
152    TimeStamp getOriginateTimeStamp();
153
154    /**
155     * @return poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
156     */
157    int getPoll();
158
159    /**
160     * @return precision as defined in RFC-1305
161     */
162    int getPrecision();
163
164    /**
165     * @return the {@code receive} time as defined in RFC-1305
166     */
167    TimeStamp getReceiveTimeStamp();
168
169    /**
170     * @return the reference id (32-bit code) as defined in RFC-1305
171     */
172    int getReferenceId();
173
174    /**
175     * @return the reference id string
176     */
177    String getReferenceIdString();
178
179    /**
180     * @return the reference time as defined in RFC-1305
181     */
182    TimeStamp getReferenceTimeStamp();
183
184    /**
185     * @return root delay as defined in RFC-1305
186     */
187    int getRootDelay();
188
189    /**
190     * @return root delay in milliseconds
191     */
192    double getRootDelayInMillisDouble();
193
194    /**
195     * @return root dispersion as defined in RFC-1305
196     */
197    int getRootDispersion();
198
199    /**
200     * @return root dispersion in milliseconds
201     */
202    long getRootDispersionInMillis();
203
204    /**
205     * @return root dispersion in milliseconds
206     */
207    double getRootDispersionInMillisDouble();
208
209    /**
210     * @return stratum as defined in RFC-1305
211     */
212    int getStratum();
213
214    /**
215     * @return the {@code transmit} timestamp as defined in RFC-1305
216     */
217    TimeStamp getTransmitTimeStamp();
218
219    /**
220     * Return type of time packet. The values (e.g. NTP, TIME, ICMP, ...) correspond to the protocol used to obtain the timing information.
221     *
222     * @return packet type string identifier
223     */
224    String getType();
225
226    /**
227     * @return version as defined in RFC-1305
228     */
229    int getVersion();
230
231    /**
232     * Sets the contents of this object from the datagram packet
233     *
234     * @param dp the packet
235     */
236    void setDatagramPacket(DatagramPacket dp);
237
238    /**
239     * Sets leap indicator.
240     *
241     * @param li - leap indicator code
242     */
243    void setLeapIndicator(int li);
244
245    /**
246     * Sets mode as defined in RFC-1305
247     *
248     * @param mode the mode to set
249     */
250    void setMode(int mode);
251
252    /**
253     * Sets originate timestamp given NTP TimeStamp object.
254     *
255     * @param ts - timestamp
256     */
257    void setOriginateTimeStamp(TimeStamp ts);
258
259    /**
260     * Sets poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
261     *
262     * @param poll the interval to set
263     */
264    void setPoll(int poll);
265
266    /**
267     * Sets precision as defined in RFC-1305
268     *
269     * @param precision Precision
270     * @since 3.4
271     */
272    void setPrecision(int precision);
273
274    /**
275     * Sets receive timestamp given NTP TimeStamp object.
276     *
277     * @param ts - timestamp
278     */
279    void setReceiveTimeStamp(TimeStamp ts);
280
281    /**
282     * Sets reference clock identifier field.
283     *
284     * @param refId the clock id field to set
285     */
286    void setReferenceId(int refId);
287
288    /**
289     * Sets the reference timestamp given NTP TimeStamp object.
290     *
291     * @param ts - timestamp
292     */
293    void setReferenceTime(TimeStamp ts);
294
295    /**
296     * Sets root delay as defined in RFC-1305
297     *
298     * @param delay the delay to set
299     * @since 3.4
300     */
301    void setRootDelay(int delay);
302
303    /**
304     *
305     * @param dispersion the value to set
306     * @since 3.4
307     */
308    void setRootDispersion(int dispersion);
309
310    /**
311     * Sets stratum as defined in RFC-1305
312     *
313     * @param stratum the stratum to set
314     */
315    void setStratum(int stratum);
316
317    /**
318     * Sets the {@code transmit} timestamp given NTP TimeStamp object.
319     *
320     * @param ts - timestamp
321     */
322    void setTransmitTime(TimeStamp ts);
323
324    /**
325     * Sets version as defined in RFC-1305
326     *
327     * @param version the version to set
328     */
329    void setVersion(int version);
330
331}