001package jmri.jmrix.dccpp;
002
003/**
004 * DCCppListener provides the call-back interface for notification when a new
005 * DCC++ message arrives from the layout.
006 * <p>
007 * Note that the DCCppListener implementation cannot assume that messages will be
008 * returned in any particular thread. We may eventually revisit this, as
009 * returning messages in the Swing GUI thread would result in some
010 * simplification of client code. We've not done that yet because we're not sure
011 * that deadlocks can be avoided in that case.
012 *
013 * @author Bob Jacobsen Copyright (C) 2002
014 * @author Bob Jacobsen Copyright (C) 2010
015 * @author Mark Underwood Copyright (C) 2015
016  *
017 * Based on XNetListener by Bob Jacobsen
018 */
019public interface DCCppListener extends jmri.jmrix.AbstractMRListener {
020
021    /**
022     * Member function that will be invoked by a DCCppInterface implementation to
023     * forward a DCC++ message from the layout.
024     *
025     * @param msg The received DCC++ message. Note that this same object may be
026     *            presented to multiple users. It should not be modified here.
027     */
028    void message(DCCppReply msg);
029
030    /**
031     * Member function that will be invoked by a DCCppInterface implementation to
032     * forward a DCC++ message sent to the layout. Normally, this function will
033     * do nothing.
034     *
035     * @param msg The received DCC++ message. Note that this same object may be
036     *            presented to multiple users. It should not be modified here.
037     */
038    void message(DCCppMessage msg);
039
040    /**
041     * Member function invoked by an DCCppInterface implementation to notify a
042     * sender that an outgoing message timed out and was dropped from the
043     * queue.
044     * @param msg the message that timed out.
045     */
046    void notifyTimeout(DCCppMessage msg);
047
048}
049