001package jmri.jmrix.loconet;
002
003/**
004 * LocoNetInterface defines the general connection to a LocoNet layout.
005 * <p>
006 * Use this interface to send messages to a LocoNet layout. Classes implementing
007 * the LocoNetListener interface can register here to receive incoming LocoNet
008 * messages as events.
009 * <p>
010 * The jmri.jrmix.loconet.LnTrafficController 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 LocoNet specific, so it would be inappropriate
015 * to 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 LnTrafficManager implementation to locate
018 * _any_ implementation; this clearly needs to be improved.
019 * <p>
020 * LocoNetListener implementations registering for traffic updates cannot assume
021 * that messages will be returned in any particular thread. See the
022 * LocoNetListener doc for more background.
023 *
024 * @author Bob Jacobsen Copyright (C) 2001
025 * @see jmri.jmrix.loconet.LocoNetListener
026 * @see jmri.jmrix.loconet.LnTrafficController
027 */
028public interface LocoNetInterface {
029
030    /*
031     * Request a message be sent to the attached LocoNet. Return is immediate,
032     * with the message being queued for eventual sending.  If you're interested
033     * in a reply, you need to register a LocoNetListener object to watch the
034     * message stream.
035     *
036     * @param msg message to send; will be updated with CRC
037     */
038    void sendLocoNetMessage(LocoNetMessage msg);
039
040    /*
041     * Request a message be sent to the attached LocoNet. Return is immediate,
042     * with the message being queued for eventual sending.  If you're interested
043     * in a reply, you need to register a LocoNetListener object to watch the
044     * message stream.
045     *
046     * @param msg message to send; will be updated with CRC
047     * @param requestIgnoreEcho If true: Notify listeners on enqueing message, ignore echo from line.
048     *             Only in effect if preference "LoconetUpdateSlotOnMessageCreation" is set.
049     */
050    void sendLocoNetMessage(LocoNetMessage msg, boolean requestIgnoreEcho);
051
052    /**
053     * Request notification of things happening on the LocoNet.
054     * <p>
055     * The same listener can register multiple times with different masks.
056     * (Multiple registrations with a single mask value are equivalent to a
057     * single registration) Mask values are defined as class constants. Note
058     * that these are bit masks, and should be OR'd, not added, if multiple
059     * values are desired.
060     * <p>
061     * The event notification contains the received message as source, not this
062     * object, so that we can notify of an incoming message to multiple places
063     * and then move on.
064     *
065     * @param mask     The OR of the key values of messages to be reported (to
066     *                 reduce traffic, provide for listeners interested in
067     *                 different things)
068     *
069     * @param listener Object to be notified of new messages as they arrive.
070     *
071     */
072    void addLocoNetListener(int mask, LocoNetListener listener);
073
074    /*
075     * Stop notification of things happening on the LocoNet. Note that mask and LocoNetListener
076     * must match a previous request exactly.
077     */
078    void removeLocoNetListener(int mask, LocoNetListener listener);
079
080    /**
081     * Check whether an implementation is operational.  Returns true if
082     * operational.
083     * 
084     * @return true if implementation is operational.
085     */
086    boolean status();
087
088    /**
089     * Mask value to request notification of all incoming messages
090     */
091    int ALL = ~0;
092
093    /**
094     * Mask value to request notification of messages effecting slot status,
095     * including the programming slot
096     */
097    int SLOTINFO = 1;
098
099    /**
100     * Mask value to request notification of messages associated with
101     * programming
102     */
103    int PROGRAMMING = 2;
104
105    /**
106     * Mask value to request notification of messages indicating changes in
107     * turnout status
108     */
109    int TURNOUTS = 4;
110
111    /**
112     * Mask value to request notification of messages indicating changes in
113     * sensor status
114     */
115    int SENSORS = 8;
116
117    /**
118     * Mask value to request notification of messages associated with layout
119     * power
120     */
121    int POWER = 16;
122
123    /**
124     * Set the system connection memo associated with this connection.
125     *
126     * @param m associated systemConnectionMemo object
127     */
128    void setSystemConnectionMemo(LocoNetSystemConnectionMemo m);
129
130    /**
131     * Get the system connection memo associated with this connection.
132     *
133     * @return the associated systemConnectionMemo object
134     */
135    LocoNetSystemConnectionMemo getSystemConnectionMemo();
136
137}