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