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    void sendLocoNetMessage(LocoNetMessage msg);
037
038    /**
039     * Request notification of things happening on the LocoNet.
040     * <p>
041     * The same listener can register multiple times with different masks.
042     * (Multiple registrations with a single mask value are equivalent to a
043     * single registration) Mask values are defined as class constants. Note
044     * that these are bit masks, and should be OR'd, not added, if multiple
045     * values are desired.
046     * <p>
047     * The event notification contains the received message as source, not this
048     * object, so that we can notify of an incoming message to multiple places
049     * and then move on.
050     *
051     * @param mask     The OR of the key values of messages to be reported (to
052     *                 reduce traffic, provide for listeners interested in
053     *                 different things)
054     *
055     * @param listener Object to be notified of new messages as they arrive.
056     *
057     */
058    void addLocoNetListener(int mask, LocoNetListener listener);
059
060    /*
061     * Stop notification of things happening on the LocoNet. Note that mask and LocoNetListener
062     * must match a previous request exactly.
063     */
064    void removeLocoNetListener(int mask, LocoNetListener listener);
065
066    /**
067     * Check whether an implementation is operational.  Returns true if
068     * operational.
069     * 
070     * @return true if implementation is operational.
071     */
072    boolean status();
073
074    /**
075     * Mask value to request notification of all incoming messages
076     */
077    int ALL = ~0;
078
079    /**
080     * Mask value to request notification of messages effecting slot status,
081     * including the programming slot
082     */
083    int SLOTINFO = 1;
084
085    /**
086     * Mask value to request notification of messages associated with
087     * programming
088     */
089    int PROGRAMMING = 2;
090
091    /**
092     * Mask value to request notification of messages indicating changes in
093     * turnout status
094     */
095    int TURNOUTS = 4;
096
097    /**
098     * Mask value to request notification of messages indicating changes in
099     * sensor status
100     */
101    int SENSORS = 8;
102
103    /**
104     * Mask value to request notification of messages associated with layout
105     * power
106     */
107    int POWER = 16;
108
109    /**
110     * Set the system connection memo associated with this connection.
111     *
112     * @param m associated systemConnectionMemo object
113     */
114    void setSystemConnectionMemo(LocoNetSystemConnectionMemo m);
115
116    /**
117     * Get the system connection memo associated with this connection.
118     *
119     * @return the associated systemConnectionMemo object
120     */
121    LocoNetSystemConnectionMemo getSystemConnectionMemo();
122
123}