001package jmri.jmrix;
002
003import java.util.Vector;
004import org.slf4j.Logger;
005import purejavacomm.PortInUseException;
006
007/**
008 * Enable basic setup of a serial interface for a jmrix implementation.
009 *
010 * @author Bob Jacobsen Copyright (C) 2001, 2003, 2008
011 * @see jmri.jmrix.SerialConfigException
012 */
013public interface SerialPortAdapter extends PortAdapter {
014
015    /**
016     * Provide a vector of valid port names, each a String.
017     * @return port names.
018     */
019    public Vector<String> getPortNames();
020
021    /**
022     * Open a specified port.
023     *
024     * @param portName name tu use for this port
025     * @param appName provided to the underlying OS during startup so
026     *                that it can show on status displays, etc.
027     * @return null indicates OK return, else error message.
028     */
029    public String openPort(String portName, String appName);
030
031    /**
032     * Configure all of the other jmrix widgets needed to work with this adapter.
033     */
034    @Override
035    public void configure();
036
037    /**
038     * {@inheritDoc}
039     */
040    @Override
041    public boolean status();
042
043    /**
044     * Remember the associated port name.
045     *
046     * @param s name of the port
047     */
048    public void setPort(String s);
049
050    @Override
051    public String getCurrentPortName();
052
053    /**
054     * Get an array of valid baud rate strings; used to display valid options in Connections Preferences.
055     *
056     * @return array of I18N display strings of port speed settings valid for this serial adapter,
057     * must match order and values from {@link #validBaudNumbers()}
058     */
059    public String[] validBaudRates();
060
061    /**
062     * Get an array of valid baud rate numbers; used to store/load adapter speed option.
063     *
064     * @return integer array of speeds, must match order and values from {@link #validBaudRates()}
065     */
066    public int[] validBaudNumbers();
067
068    /**
069     * Get the index of the default port speed for this adapter from the validSpeeds and validRates arrays.
070     *
071     * @return -1 to indicate not supported, unless overridden in adapter
072     */
073    public int defaultBaudIndex();
074
075    /**
076     * Set the baud rate description by port speed description.
077     * <p>
078     * Only to be used after construction, but before the openPort call.
079     *
080     * @param rate the baud rate as I18N description, eg. "28,800 baud"
081     */
082    public void configureBaudRate(String rate);
083
084    /**
085     * Set the baud rate description by port speed number (as a string) from validBaudRates[].
086     * <p>
087     * Only to be used after construction, but before the openPort call.
088     *
089     * @param index the port speed as unformatted number string, eg. "28800"
090     */
091    public void configureBaudRateFromNumber(String index);
092
093    /**
094     * Set the baud rate description by index (integer) from validBaudRates[].
095     *
096     * @param index the index to select from speeds[] array
097     */
098    public void configureBaudRateFromIndex(int index);
099
100    public String getCurrentBaudRate();
101
102    /**
103     * To store as XML attribute, get a string to represent current port speed.
104     *
105     * @return speed as number string
106     */
107    public String getCurrentBaudNumber();
108
109    public int getCurrentBaudIndex();
110
111    /**
112     * Set the first port option. Only to be used after construction, but before
113     * the openPort call.
114     */
115    @Override
116    public void configureOption1(String value);
117
118    /**
119     * Set the second port option. Only to be used after construction, but
120     * before the openPort call.
121     */
122    @Override
123    public void configureOption2(String value);
124
125    /**
126     * Set the third port option. Only to be used after construction, but before
127     * the openPort call.
128     */
129    @Override
130    public void configureOption3(String value);
131
132    /**
133     * Set the fourth port option. Only to be used after construction, but
134     * before the openPort call.
135     */
136    @Override
137    public void configureOption4(String value);
138
139    /**
140     * Error handling for busy port at open.
141     *
142     * @param p        the exception being handled, if additional information
143     *                 from it is desired.
144     * @param portName name of the port being accessed.
145     * @param log      where to log a status message.
146     * @return Localized message, in case separate presentation to user is
147     *         desired.
148     * @see jmri.jmrix.AbstractSerialPortController
149     */
150    public String handlePortBusy(PortInUseException p, String portName, Logger log);
151
152    /**
153     * Get the System Manufacturers Name.
154     */
155    @Override
156    public String getManufacturer();
157
158    /**
159     * Set the System Manufacturers Name.
160     */
161    @Override
162    public void setManufacturer(String Manufacturer);
163
164}