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@13:643ad09fc0e0, 2020-09-11 (annotated)

Committer:
Jason Reiss
Date:
Fri Sep 11 11:26:01 2020 -0500
Revision:
13:643ad09fc0e0
Parent:
11:4afbbafcd6b3 
Sync to 42356b91d1700c77144ebf97df131503991c7317

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