    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 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}