    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}