001package jmri;
002
003/**
004 * Allow notification of the completion of programming operations.
005 * <p>
006 * This allows a {@link Programmer} object to return delayed status, including
007 * the CV value from a read operation.
008 * For simplicity, expect these to be returned to be on the
009 * <a href="http://jmri.org/help/en/html/doc/Technical/Threads.shtml">GUI thread</a>.
010 * See the discussion in the {@link Programmer#readCV(String CV, ProgListener p) Programmer.readCV(...)}, 
011 * {@link Programmer#writeCV(String CV, int val, ProgListener p) Programmer.writeCV(...)} and
012 * {@link Programmer#confirmCV(String CV, int val, ProgListener p) Programmer.confirmCV(...)} methods.
013 *
014 * <hr>
015 * This file is part of JMRI.
016 * <p>
017 * JMRI is free software; you can redistribute it and/or modify it under the
018 * terms of version 2 of the GNU General Public License as published by the Free
019 * Software Foundation. See the "COPYING" file for a copy of this license.
020 * <p>
021 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
022 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
023 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
024 *
025 * @author Bob Jacobsen Copyright (C) 2001
026 */
027public interface ProgListener extends java.util.EventListener {
028
029    /**
030     * Receive a callback at the end of a programming operation.
031     *
032     * @param value  Value from a read operation, or value written on a write
033     * @param status Denotes the completion code. Note that this is a bitwise
034     *               combination of the various status coded defined in this
035     *               interface.
036     */
037    void programmingOpReply(int value, int status);
038
039    /**
040     * Constant denoting that the request completed correctly. Note this is a
041     * specific value; all others are bitwise combinations
042     */
043    static final int OK = 0;
044
045    /**
046     * Constant denoting the request failed, but no specific reason is known
047     */
048    static final int UnknownError = 1;
049
050    /**
051     * Constant denoting that no decoder was detected on the programming track
052     */
053    static final int NoLocoDetected = 2;
054
055    /**
056     * Constant denoting that the request failed because the decoding hardware
057     * was already busy
058     */
059    static final int ProgrammerBusy = 4;
060
061    /**
062     * Constant denoting that the request failed because it requested some
063     * unimplemented capability. Note that this can also result in an exception
064     * during the original request; which happens is implementation dependent
065     */
066    static final int NotImplemented = 8;
067
068    /**
069     * Constant denoting that the user (human or software) aborted the request
070     * before completion
071     */
072    static final int UserAborted = 0x10;
073
074    /**
075     * Constant denoting there was no acknowledge from the locomotive, so the CV
076     * may or may not have been written on a write. No value was read.
077     */
078    static final int NoAck = 0x20;
079
080    /**
081     * Constant denoting that confirm failed, likely due to another value being
082     * present
083     */
084    static final int ConfirmFailed = 0x40;
085
086    /**
087     * Constant denoting that the programming operation timed out
088     */
089    static final int FailedTimeout = 0x80;
090
091    /**
092     * Constant denoting that a short circuit occurred while programming
093     */
094    static final int ProgrammingShort = 0x100;
095
096    /**
097     * Constant denoting that there was an error with the programming sequence
098     * (such as early exit)
099     */
100    static final int SequenceError = 0x200;
101
102    /**
103     * Constant denoting that a communications error occurred between the command
104     * station and the PC during programming
105     */
106    static final int CommError = 0x400;
107
108}