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    int LI_NO_WARNING = 0;
033    int LI_LAST_MINUTE_HAS_61_SECONDS = 1;
034    int LI_LAST_MINUTE_HAS_59_SECONDS = 2;
035    int LI_ALARM_CONDITION = 3;
036
037    // mode options
038    /** Mode option {@value}. */
039    int MODE_RESERVED = 0;
040
041    /** Mode option {@value}. */
042    int MODE_SYMMETRIC_ACTIVE = 1;
043
044    /** Mode option {@value}. */
045    int MODE_SYMMETRIC_PASSIVE = 2;
046
047    /** Mode option {@value}. */
048    int MODE_CLIENT = 3;
049
050    /** Mode option {@value}. */
051    int MODE_SERVER = 4;
052
053    /** Mode option {@value}. */
054    int MODE_BROADCAST = 5;
055
056    /** Mode option {@value}. */
057    int MODE_CONTROL_MESSAGE = 6;
058
059    /** Mode option {@value}. */
060    int MODE_PRIVATE = 7;
061
062    int NTP_MINPOLL = 4; // 16 seconds
063    int NTP_MAXPOLL = 14; // 16284 seconds
064
065    int NTP_MINCLOCK = 1;
066    int NTP_MAXCLOCK = 10;
067
068    int VERSION_3 = 3;
069    int VERSION_4 = 4;
070
071    /*
072     * possible getType values such that other time-related protocols can have its information represented as NTP packets
073     */
074    String TYPE_NTP = "NTP"; // RFC-1305/2030
075    String TYPE_ICMP = "ICMP"; // RFC-792
076    String TYPE_TIME = "TIME"; // RFC-868
077    String TYPE_DAYTIME = "DAYTIME"; // RFC-867
078
079    /**
080     * @return a datagram packet with the NTP parts already filled in
081     */
082    DatagramPacket getDatagramPacket();
083
084    /**
085     * @return leap indicator as defined in RFC-1305
086     */
087    int getLeapIndicator();
088
089    /**
090     * @return mode as defined in RFC-1305
091     */
092    int getMode();
093
094    /**
095     * @return mode as human readable string; e.g. 3=Client
096     */
097    String getModeName();
098
099    /**
100     * @return the {@code originate} time as defined in RFC-1305
101     */
102    TimeStamp getOriginateTimeStamp();
103
104    /**
105     * @return poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
106     */
107    int getPoll();
108
109    /**
110     * @return precision as defined in RFC-1305
111     */
112    int getPrecision();
113
114    /**
115     * @return the {@code receive} time as defined in RFC-1305
116     */
117    TimeStamp getReceiveTimeStamp();
118
119    /**
120     * @return the reference id (32-bit code) as defined in RFC-1305
121     */
122    int getReferenceId();
123
124    /**
125     * @return the reference id string
126     */
127    String getReferenceIdString();
128
129    /**
130     * @return the reference time as defined in RFC-1305
131     */
132    TimeStamp getReferenceTimeStamp();
133
134    /**
135     * @return root delay as defined in RFC-1305
136     */
137    int getRootDelay();
138
139    /**
140     * @return root delay in milliseconds
141     */
142    double getRootDelayInMillisDouble();
143
144    /**
145     * @return root dispersion as defined in RFC-1305
146     */
147    int getRootDispersion();
148
149    /**
150     * @return root dispersion in milliseconds
151     */
152    long getRootDispersionInMillis();
153
154    /**
155     * @return root dispersion in milliseconds
156     */
157    double getRootDispersionInMillisDouble();
158
159    /**
160     * @return stratum as defined in RFC-1305
161     */
162    int getStratum();
163
164    /**
165     * @return the {@code transmit} timestamp as defined in RFC-1305
166     */
167    TimeStamp getTransmitTimeStamp();
168
169    /**
170     * Return type of time packet. The values (e.g. NTP, TIME, ICMP, ...) correspond to the protocol used to obtain the timing information.
171     *
172     * @return packet type string identifier
173     */
174    String getType();
175
176    /**
177     * @return version as defined in RFC-1305
178     */
179    int getVersion();
180
181    /**
182     * Set the contents of this object from the datagram packet
183     *
184     * @param dp the packet
185     */
186    void setDatagramPacket(DatagramPacket dp);
187
188    /**
189     * Set leap indicator.
190     *
191     * @param li - leap indicator code
192     */
193    void setLeapIndicator(int li);
194
195    /**
196     * Set mode as defined in RFC-1305
197     *
198     * @param mode the mode to set
199     */
200    void setMode(int mode);
201
202    /**
203     * Set originate timestamp given NTP TimeStamp object.
204     *
205     * @param ts - timestamp
206     */
207    void setOriginateTimeStamp(TimeStamp ts);
208
209    /**
210     * Set poll interval as defined in RFC-1305. Field range between NTP_MINPOLL and NTP_MAXPOLL.
211     *
212     * @param poll the interval to set
213     */
214    void setPoll(int poll);
215
216    /**
217     * Set precision as defined in RFC-1305
218     *
219     * @param precision Precision
220     * @since 3.4
221     */
222    void setPrecision(int precision);
223
224    /**
225     * Set receive timestamp given NTP TimeStamp object.
226     *
227     * @param ts - timestamp
228     */
229    void setReceiveTimeStamp(TimeStamp ts);
230
231    /**
232     * Set reference clock identifier field.
233     *
234     * @param refId the clock id field to set
235     */
236    void setReferenceId(int refId);
237
238    /**
239     * Set the reference timestamp given NTP TimeStamp object.
240     *
241     * @param ts - timestamp
242     */
243    void setReferenceTime(TimeStamp ts);
244
245    /**
246     * Set root delay as defined in RFC-1305
247     *
248     * @param delay the delay to set
249     * @since 3.4
250     */
251    void setRootDelay(int delay);
252
253    /**
254     *
255     * @param dispersion the value to set
256     * @since 3.4
257     */
258    void setRootDispersion(int dispersion);
259
260    /**
261     * Set stratum as defined in RFC-1305
262     *
263     * @param stratum the stratum to set
264     */
265    void setStratum(int stratum);
266
267    /**
268     * Set the {@code transmit} timestamp given NTP TimeStamp object.
269     *
270     * @param ts - timestamp
271     */
272    void setTransmitTime(TimeStamp ts);
273
274    /**
275     * Set version as defined in RFC-1305
276     *
277     * @param version the version to set
278     */
279    void setVersion(int version);
280
281}