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