MTSBufferedIO.h

00001 #ifndef MTSBUFFEREDIO_H
00002 #define MTSBUFFEREDIO_H
00003 
00004 #include "MTSCircularBuffer.h"
00005 #include <cstdarg>
00006 
00007 namespace mts {
00008 
00009 /** This is an abstract class for lightweight buffered io to an underlying
00010 * data interface. Specifically the inheriting class will need to override
00011 * both the handleRead and handleWrite methods which transfer data between
00012 * the class's internal read and write buffers and the physical communications
00013 * link and its HW buffers.
00014 */
00015 
00016 class MTSBufferedIO
00017 {
00018 public:
00019     /** Creates a new BufferedIO object with the passed in static buffer sizes.
00020     * Note that because this class is abstract you cannot construct it directly.
00021     * Instead, please construct one of its derived classes like MTSSerial or
00022     * MTSSerialFlowControl.
00023     *
00024     * @param txBufferSize the size of the Tx or write buffer in bytes. The default is
00025     * 256 bytes.
00026     * @param rxBufferSize the size of the Rx or read buffer in bytes. The default is
00027     * 256 bytes.
00028     */
00029     MTSBufferedIO(int txBufferSize = 256, int rxBufferSize = 256);
00030 
00031     /** Destructs an MTSBufferedIO object and frees all related resources.
00032     */
00033     ~MTSBufferedIO();
00034 
00035     /** This method enables bulk writes to the Tx or write buffer. If more data
00036     * is requested to be written then space available the method writes
00037     * as much data as possible within the timeout period and returns the actual amount written.
00038     *
00039     * @param data the byte array to be written.
00040     * @param length the length of data to be written from the data parameter.
00041     * @timeoutMillis amount of time in milliseconds to complete operation.
00042     * @returns the number of bytes written to the buffer, which is 0 if
00043     * the buffer is full.
00044     */
00045     int write(const char* data, int length, unsigned int timeoutMillis);
00046 
00047     /** This method enables bulk writes to the Tx or write buffer. This method
00048     * blocks until all the bytes are written.
00049     *
00050     * @param data the byte array to be written.
00051     * @param length the length of data to be written from the data parameter.
00052     * @returns the number of bytes written to the buffer, which should be
00053     * equal to the length parameter since this method blocks.
00054     */
00055     int write(const char* data, int length);
00056 
00057     /** This method enables bulk writes to the Tx or write buffer. This method
00058     * blocks until all the bytes are written.
00059     *
00060     * @param format of the string to be written.
00061     * @param additional arguments will be placed in the format string.
00062     * @returns the number of bytes written to the buffer.
00063     */
00064     int writef(const char* format, ... );
00065 
00066     /** This method attempts to write a single byte to the tx buffer
00067     * within the timeout period.
00068     *
00069     * @param data the byte to be written as a char.
00070     * @timeoutMillis amount of time in milliseconds to complete operation.
00071     * @returns 1 if the byte was written or 0 if the buffer was full and the timeout
00072     * expired.
00073     */
00074     int write(char data, unsigned int timeoutMillis);
00075 
00076     /** This method writes a single byte as a char to the Tx or write buffer.
00077     * This method blocks until the byte is written.
00078     *
00079     * @param data the byte to be written as a char.
00080     * @returns 1 once the byte has been written.
00081     */
00082     int write(char data);
00083 
00084     /** This method is used to get the space available to write bytes to the Tx buffer.
00085     *
00086     * @returns the number of bytes that can be written, 0 if the buffer is full.
00087     */
00088     int writeable();
00089 
00090     /** This method enables bulk reads from the Rx or read buffer. It attempts
00091     * to read the amount specified, but will complete early if the specified timeout
00092     * expires.
00093     *
00094     * @param data the buffer where data read will be added to.
00095     * @param length the amount of data in bytes to be read into the buffer.
00096     * @timeoutMillis amount of time to complete operation.
00097     * @returns the total number of bytes that were read.
00098     */
00099     int read(char* data, int length, unsigned int timeoutMillis);
00100 
00101     /** This method enables bulk reads from the Rx or read buffer. This method
00102     * blocks until the amount of data requested is received.
00103     *
00104     * @param data the buffer where data read will be added to.
00105     * @param length the amount of data in bytes to be read into the buffer.
00106     * @returns the total number of bytes that were read. This should be equal
00107     * to the length parameter since this is a blocking call.
00108     */
00109     int read(char* data, int length);
00110 
00111     /** This method reads a single byte from the Rx or read buffer. This method
00112     * attempts to read a byte, but will return without reading one if the specified
00113     * timeout is reached.
00114     *
00115     * @param data char where the read byte will be stored.
00116     * @timeoutMillis amount of time to complete operation.
00117     * @returns 1 if byte is read or 0 if no byte is available.
00118     */
00119     int read(char& data, unsigned int timeoutMillis);
00120 
00121     /** This method reads a single byte from the Rx or read buffer.
00122     * This method blocks until the single byte is read.
00123     *
00124     * @param data char where the read byte will be stored.
00125     * @returns 1 once the byte has been read.
00126     */
00127     int read(char& data);
00128 
00129     /** This method is used to get the number of bytes available to read from
00130     * the Rx or read buffer.
00131     *
00132     * @returns the number of bytes available, 0 if there are no bytes to read.
00133     */
00134     int readable();
00135 
00136     /** This method determines if the Tx or write buffer is empty.
00137     *
00138     * @returns true if empty, otherwise false.
00139     */
00140     bool txEmpty();
00141 
00142     /** This method determines if the Rx or read buffer is empty.
00143     *
00144     * @returns true if empty, otherwise false.
00145     */
00146     bool rxEmpty();
00147 
00148     /** This method determines if the Tx or write buffer is full.
00149     *
00150     * @returns true if full, otherwise false.
00151     */
00152     bool txFull();
00153 
00154     /** This method determines if the Rx or read buffer is full.
00155     *
00156     * @returns true if full, otherwise false.
00157     */
00158     bool rxFull();
00159 
00160     /** This method clears all the data from the internal Tx or write buffer.
00161     */
00162     virtual void txClear();
00163 
00164     /** This method clears all the data from the internal Rx or read buffer.
00165     */
00166     virtual void rxClear();
00167 
00168     /** This abstract method should be used by the deriving class to transfer
00169     * data from the internal write buffer (txBuffer) to the physical interface.
00170     * Note that this function is called every time new data is written to the
00171     * txBuffer through one of the write calls.
00172     */
00173     virtual void handleWrite() = 0;
00174 
00175     /** This abstract method should be used by the deriving class to transfer
00176     * data from the physical interface to the internal read buffer (rxBuffer).
00177     * Note that this function is never called in this class and typically should
00178     * be called as part of a receive data interrupt routine.
00179     */
00180     virtual void handleRead() = 0;
00181 
00182 protected:
00183     MTSCircularBuffer txBuffer; // Internal write or transmit circular buffer
00184     MTSCircularBuffer rxBuffer; // Internal read or receive circular buffer
00185 };
00186 
00187 }
00188 
00189 #endif /* MTSBUFFEREDIO_H */