MultiTech / MTS-Serial

Serial library for MTS Socket Modem Arduino Shield devices from Multi-Tech Systems

Dependents:   mDot_AT_firmware mtsas mtsas MTDOT-EVB-LinkCheck-AL ... more

MTSBufferedIO.h@1:d34b566d6f47, 2014-05-19 (annotated)

Committer:
Mike Fiore
Date:
Mon May 19 11:18:10 2014 -0500
Revision:
1:d34b566d6f47
Parent:
0:6585b7c8cd41
Child:
2:d2cb8c8ecd6e
add MTSBufferedIO, MTSSerial, and MTSSerialFlowControl

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mfiore 0:6585b7c8cd41 1 #ifndef MTSBUFFEREDIO_H
mfiore 0:6585b7c8cd41 2 #define MTSBUFFEREDIO_H
mfiore 0:6585b7c8cd41 3
Mike Fiore 1:d34b566d6f47 4 #include "MTSCircularBuffer.h"
Mike Fiore 1:d34b566d6f47 5
Mike Fiore 1:d34b566d6f47 6 namespace mts {
Mike Fiore 1:d34b566d6f47 7
Mike Fiore 1:d34b566d6f47 8 /** This is an abstract class for lightweight buffered io to an underlying
Mike Fiore 1:d34b566d6f47 9 * data interface. Specifically the inheriting class will need to override
Mike Fiore 1:d34b566d6f47 10 * both the handleRead and handleWrite methods which transfer data between
Mike Fiore 1:d34b566d6f47 11 * the class's internal read and write buffers and the physical communications
Mike Fiore 1:d34b566d6f47 12 * link and its HW buffers.
Mike Fiore 1:d34b566d6f47 13 */
Mike Fiore 1:d34b566d6f47 14
Mike Fiore 1:d34b566d6f47 15 class MTSBufferedIO
Mike Fiore 1:d34b566d6f47 16 {
Mike Fiore 1:d34b566d6f47 17 public:
Mike Fiore 1:d34b566d6f47 18 /** Creates a new BufferedIO object with the passed in static buffer sizes.
Mike Fiore 1:d34b566d6f47 19 * Note that because this class is abstract you cannot construct it directly.
Mike Fiore 1:d34b566d6f47 20 * Instead, please construct one of its derived classes like MTSSerial or
Mike Fiore 1:d34b566d6f47 21 * MTSSerialFlowControl.
Mike Fiore 1:d34b566d6f47 22 *
Mike Fiore 1:d34b566d6f47 23 * @param txBufferSize the size of the Tx or write buffer in bytes. The default is
Mike Fiore 1:d34b566d6f47 24 * 256 bytes.
Mike Fiore 1:d34b566d6f47 25 * @param rxBufferSize the size of the Rx or read buffer in bytes. The default is
Mike Fiore 1:d34b566d6f47 26 * 256 bytes.
Mike Fiore 1:d34b566d6f47 27 */
Mike Fiore 1:d34b566d6f47 28 MTSBufferedIO(int txBufferSize = 256, int rxBufferSize = 256);
Mike Fiore 1:d34b566d6f47 29
Mike Fiore 1:d34b566d6f47 30 /** Destructs an MTSBufferedIO object and frees all related resources.
Mike Fiore 1:d34b566d6f47 31 */
Mike Fiore 1:d34b566d6f47 32 ~MTSBufferedIO();
Mike Fiore 1:d34b566d6f47 33
Mike Fiore 1:d34b566d6f47 34 /** This method enables bulk writes to the Tx or write buffer. If more data
Mike Fiore 1:d34b566d6f47 35 * is requested to be written then space available the method writes
Mike Fiore 1:d34b566d6f47 36 * as much data as possible within the timeout period and returns the actual amount written.
Mike Fiore 1:d34b566d6f47 37 *
Mike Fiore 1:d34b566d6f47 38 * @param data the byte array to be written.
Mike Fiore 1:d34b566d6f47 39 * @param length the length of data to be written from the data parameter.
Mike Fiore 1:d34b566d6f47 40 * @timeoutMillis amount of time in milliseconds to complete operation.
Mike Fiore 1:d34b566d6f47 41 * @returns the number of bytes written to the buffer, which is 0 if
Mike Fiore 1:d34b566d6f47 42 * the buffer is full.
Mike Fiore 1:d34b566d6f47 43 */
Mike Fiore 1:d34b566d6f47 44 int write(const char* data, int length, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 45
Mike Fiore 1:d34b566d6f47 46 /** This method enables bulk writes to the Tx or write buffer. This method
Mike Fiore 1:d34b566d6f47 47 * blocks until all the bytes are written.
Mike Fiore 1:d34b566d6f47 48 *
Mike Fiore 1:d34b566d6f47 49 * @param data the byte array to be written.
Mike Fiore 1:d34b566d6f47 50 * @param length the length of data to be written from the data parameter.
Mike Fiore 1:d34b566d6f47 51 * @returns the number of bytes written to the buffer, which should be
Mike Fiore 1:d34b566d6f47 52 * equal to the length parameter since this method blocks.
Mike Fiore 1:d34b566d6f47 53 */
Mike Fiore 1:d34b566d6f47 54 int write(const char* data, int length);
Mike Fiore 1:d34b566d6f47 55
Mike Fiore 1:d34b566d6f47 56 /** This method attempts to write a single byte to the tx buffer
Mike Fiore 1:d34b566d6f47 57 * within the timeout period.
Mike Fiore 1:d34b566d6f47 58 *
Mike Fiore 1:d34b566d6f47 59 * @param data the byte to be written as a char.
Mike Fiore 1:d34b566d6f47 60 * @timeoutMillis amount of time in milliseconds to complete operation.
Mike Fiore 1:d34b566d6f47 61 * @returns 1 if the byte was written or 0 if the buffer was full and the timeout
Mike Fiore 1:d34b566d6f47 62 * expired.
Mike Fiore 1:d34b566d6f47 63 */
Mike Fiore 1:d34b566d6f47 64 int write(char data, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 65
Mike Fiore 1:d34b566d6f47 66 /** This method writes a signle byte as a char to the Tx or write buffer.
Mike Fiore 1:d34b566d6f47 67 * This method blocks until the byte is written.
Mike Fiore 1:d34b566d6f47 68 *
Mike Fiore 1:d34b566d6f47 69 * @param data the byte to be written as a char.
Mike Fiore 1:d34b566d6f47 70 * @returns 1 once the byte has been written.
Mike Fiore 1:d34b566d6f47 71 */
Mike Fiore 1:d34b566d6f47 72 int write(char data);
Mike Fiore 1:d34b566d6f47 73
Mike Fiore 1:d34b566d6f47 74 /** This method is used to get the space available to write bytes to the Tx buffer.
Mike Fiore 1:d34b566d6f47 75 *
Mike Fiore 1:d34b566d6f47 76 * @returns the number of bytes that can be written, 0 if the buffer is full.
Mike Fiore 1:d34b566d6f47 77 */
Mike Fiore 1:d34b566d6f47 78 int writeable();
Mike Fiore 1:d34b566d6f47 79
Mike Fiore 1:d34b566d6f47 80 /** This method enables bulk reads from the Rx or read buffer. It attempts
Mike Fiore 1:d34b566d6f47 81 * to read the amount specified, but will complete early if the specified timeout
Mike Fiore 1:d34b566d6f47 82 * expires.
Mike Fiore 1:d34b566d6f47 83 *
Mike Fiore 1:d34b566d6f47 84 * @param data the buffer where data read will be added to.
Mike Fiore 1:d34b566d6f47 85 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:d34b566d6f47 86 * @timeoutMillis amount of time to complete operation.
Mike Fiore 1:d34b566d6f47 87 * @returns the total number of bytes that were read.
Mike Fiore 1:d34b566d6f47 88 */
Mike Fiore 1:d34b566d6f47 89 int read(char* data, int length, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 90
Mike Fiore 1:d34b566d6f47 91 /** This method enables bulk reads from the Rx or read buffer. This method
Mike Fiore 1:d34b566d6f47 92 * blocks until the amount of data requested is received.
Mike Fiore 1:d34b566d6f47 93 *
Mike Fiore 1:d34b566d6f47 94 * @param data the buffer where data read will be added to.
Mike Fiore 1:d34b566d6f47 95 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:d34b566d6f47 96 * @returns the total number of bytes that were read. This should be equal
Mike Fiore 1:d34b566d6f47 97 * to the length parameter since this is a blocking call.
Mike Fiore 1:d34b566d6f47 98 */
Mike Fiore 1:d34b566d6f47 99 int read(char* data, int length);
Mike Fiore 1:d34b566d6f47 100
Mike Fiore 1:d34b566d6f47 101 /** This method reads a single byte from the Rx or read buffer. This method
Mike Fiore 1:d34b566d6f47 102 * attempts to read a byte, but will return without reading one if the specified
Mike Fiore 1:d34b566d6f47 103 * timeout is reached.
Mike Fiore 1:d34b566d6f47 104 *
Mike Fiore 1:d34b566d6f47 105 * @param data char where the read byte will be stored.
Mike Fiore 1:d34b566d6f47 106 * @timeoutMillis amount of time to complete operation.
Mike Fiore 1:d34b566d6f47 107 * @returns 1 if byte is read or 0 if no byte is available.
Mike Fiore 1:d34b566d6f47 108 */
Mike Fiore 1:d34b566d6f47 109 int read(char& data, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 110
Mike Fiore 1:d34b566d6f47 111 /** This method reads a single byte from the Rx or read buffer.
Mike Fiore 1:d34b566d6f47 112 * This method blocks until the single byte is read.
Mike Fiore 1:d34b566d6f47 113 *
Mike Fiore 1:d34b566d6f47 114 * @param data char where the read byte will be stored.
Mike Fiore 1:d34b566d6f47 115 * @returns 1 once the byte has been read.
Mike Fiore 1:d34b566d6f47 116 */
Mike Fiore 1:d34b566d6f47 117 int read(char& data);
Mike Fiore 1:d34b566d6f47 118
Mike Fiore 1:d34b566d6f47 119 /** This method is used to get the number of bytes available to read from
Mike Fiore 1:d34b566d6f47 120 * the Rx or read buffer.
Mike Fiore 1:d34b566d6f47 121 *
Mike Fiore 1:d34b566d6f47 122 * @returns the number of bytes available, 0 if there are no bytes to read.
Mike Fiore 1:d34b566d6f47 123 */
Mike Fiore 1:d34b566d6f47 124 int readable();
Mike Fiore 1:d34b566d6f47 125
Mike Fiore 1:d34b566d6f47 126 /** This method determines if the Tx or write buffer is empty.
Mike Fiore 1:d34b566d6f47 127 *
Mike Fiore 1:d34b566d6f47 128 * @returns true if empty, otherwise false.
Mike Fiore 1:d34b566d6f47 129 */
Mike Fiore 1:d34b566d6f47 130 bool txEmpty();
Mike Fiore 1:d34b566d6f47 131
Mike Fiore 1:d34b566d6f47 132 /** This method determines if the Rx or read buffer is empty.
Mike Fiore 1:d34b566d6f47 133 *
Mike Fiore 1:d34b566d6f47 134 * @returns true if empty, otherwise false.
Mike Fiore 1:d34b566d6f47 135 */
Mike Fiore 1:d34b566d6f47 136 bool rxEmpty();
Mike Fiore 1:d34b566d6f47 137
Mike Fiore 1:d34b566d6f47 138 /** This method determines if the Tx or write buffer is full.
Mike Fiore 1:d34b566d6f47 139 *
Mike Fiore 1:d34b566d6f47 140 * @returns true if full, otherwise false.
Mike Fiore 1:d34b566d6f47 141 */
Mike Fiore 1:d34b566d6f47 142 bool txFull();
Mike Fiore 1:d34b566d6f47 143
Mike Fiore 1:d34b566d6f47 144 /** This method determines if the Rx or read buffer is full.
Mike Fiore 1:d34b566d6f47 145 *
Mike Fiore 1:d34b566d6f47 146 * @returns true if full, otherwise false.
Mike Fiore 1:d34b566d6f47 147 */
Mike Fiore 1:d34b566d6f47 148 bool rxFull();
Mike Fiore 1:d34b566d6f47 149
Mike Fiore 1:d34b566d6f47 150 /** This method clears all the data from the internal Tx or write buffer.
Mike Fiore 1:d34b566d6f47 151 */
Mike Fiore 1:d34b566d6f47 152 virtual void txClear();
Mike Fiore 1:d34b566d6f47 153
Mike Fiore 1:d34b566d6f47 154 /** This method clears all the data from the internal Rx or read buffer.
Mike Fiore 1:d34b566d6f47 155 */
Mike Fiore 1:d34b566d6f47 156 virtual void rxClear();
Mike Fiore 1:d34b566d6f47 157
Mike Fiore 1:d34b566d6f47 158 /** This abstract method should be used by the deriving class to transfer
Mike Fiore 1:d34b566d6f47 159 * data from the internal write buffer (txBuffer) to the physical interface.
Mike Fiore 1:d34b566d6f47 160 * Note that this function is called everytime new data is written to the
Mike Fiore 1:d34b566d6f47 161 * txBuffer through one of the write calls.
Mike Fiore 1:d34b566d6f47 162 */
Mike Fiore 1:d34b566d6f47 163 virtual void handleWrite() = 0;
Mike Fiore 1:d34b566d6f47 164
Mike Fiore 1:d34b566d6f47 165 /** This abstract method should be used by the deriving class to transfer
Mike Fiore 1:d34b566d6f47 166 * data from the physical interface ot the internal read buffer (rxBuffer).
Mike Fiore 1:d34b566d6f47 167 * Note that this function is never called in this class and typically should
Mike Fiore 1:d34b566d6f47 168 * be called as part of a receive data interrupt routine.
Mike Fiore 1:d34b566d6f47 169 */
Mike Fiore 1:d34b566d6f47 170 virtual void handleRead() = 0;
Mike Fiore 1:d34b566d6f47 171
Mike Fiore 1:d34b566d6f47 172 protected:
Mike Fiore 1:d34b566d6f47 173 MTSCircularBuffer txBuffer; // Internal write or transmit circular buffer
Mike Fiore 1:d34b566d6f47 174 MTSCircularBuffer rxBuffer; // Internal read or receieve circular buffer
Mike Fiore 1:d34b566d6f47 175 };
Mike Fiore 1:d34b566d6f47 176
Mike Fiore 1:d34b566d6f47 177 }
Mike Fiore 1:d34b566d6f47 178
Mike Fiore 1:d34b566d6f47 179 #endif /* MTSBUFFEREDIO_H */