001package jmri.jmrix.dccpp;
002
003/**
004 * DCCppInterface defines the general connection to a DCC++ layout.
005 * <p>
006 * Use this interface to send messages to a DCC++ layout. Classes implementing
007 * the DCCppListener interface can register here to receive incoming DCC++
008 * messages as events.
009 * <p>
010 * The jmri.jrmix.dccpp.DCCppTrafficControler provides the first implementation of
011 * this interface.
012 * <p>
013 * How do you locate an implemenation of this interface? That's an interesting
014 * question. This is inherently DCC++ specific, so it would be inappropriate to
015 * put it in the jmri.InterfaceManager. And Java interfaces can't have static
016 * members, so we can't provide an implementation() member. For now, we use a
017 * static implementation member in the DCCppTrafficController implementation to
018 * locate _any_ implementation; this clearly needs to be improved.
019 * <p>
020 * DCCppListener implementations registering for traffic updates cannot assume
021 * that messages will be returned in any particular thread. See the DCCppListener
022 * doc for more background.
023 *
024 * @author Bob Jacobsen Copyright (C) 2001, 2002
025 * @author Mark Underwood Copyright (C) 2015
026 * @see jmri.jmrix.dccpp.DCCppListener
027 * @see jmri.jmrix.dccpp.DCCppTrafficController
028 *
029 * Based on jmri.jmrix.lenz.XNetInterface
030 */
031public interface DCCppInterface {
032
033    /**
034     * Request a message be sent to the attached DCC++. Return is immediate,
035     * with the message being queued for eventual sending.  If you're interested
036     * in a reply, you need to register a DCCppListener object to watch the
037     * message stream. When sending, you specify (in 2nd parameter) who
038     * you are, so you're not redundantly notified of this message.
039     *
040     * @param msg message to send.
041     * @param replyTo listener to receive replies.
042     */
043    void sendDCCppMessage(DCCppMessage msg, DCCppListener replyTo);
044
045    /**
046     * Request notification of things happening on the DCC++.
047     * <p>
048     * The same listener can register multiple times with different masks.
049     * (Multiple registrations with a single mask value are equivalent to a
050     * single registration) Mask values are defined as class constants. Note
051     * that these are bit masks, and should be OR'd, not added, if multiple
052     * values are desired.
053     * <p>
054     * The event notification contains the received message as source, not this
055     * object, so that we can notify of an incoming message to multiple places
056     * and then move on.
057     *
058     * @param mask The OR of the key values of messages to be reported (to
059     *             reduce traffic, provide for listeners interested in different
060     *             things)
061     *
062     * @param l    Object to be notified of new messages as they arrive.
063     *
064     */
065    void addDCCppListener(int mask, DCCppListener l);
066
067    /**
068     * Stop notification of things happening on the XNet. Note that mask and XNetListener
069     * must match a previous request exactly.
070     *
071     * @param mask The OR of the key values of messages to be reported (to
072     *             reduce traffic, provide for listeners interested in different
073     *             things)
074     *
075     * @param listener Object to be notified of removal.
076     */
077    void removeDCCppListener(int mask, DCCppListener listener);
078
079    /**
080     * Check whether an implementation is operational. True indicates OK.
081     *
082     * @return true if implementation is operational.
083     */
084    public boolean status();
085
086    /**
087     * Mask value to request notification of all incoming messages
088     */
089    int ALL = ~0;
090
091    /**
092     * Mask value to request notification of communications related messages
093     * generated by the computer interface
094     */
095    int COMMINFO = 1;
096
097    /**
098     * Mask value to request notification of Command Station informational
099     * messages This includes all broadcast messages, except for the feedback
100     * broadcast and all programming messages
101     */
102    int CS_INFO = 2;
103
104    /**
105     * Mask value to request notification of messages associated with
106     * programming
107     */
108    int PROGRAMMING = 4;
109
110    /**
111     * Mask value to request notification of FeedBack (i.e. sensor)
112     * related messages
113     */
114    int FEEDBACK = 8;
115
116    /**
117     * Mask value to request notification of messages associated with throttle
118     * status
119     *
120     */
121    int THROTTLE = 16;
122
123    /**
124     * Mask value to request notification of messages associated with consists
125     *
126     */
127    int CONSIST = 32;
128
129    /**
130     * Mask value to request notification of messages associated with consists
131     *
132     */
133    int INTERFACE = 64;
134
135}
136
137
138