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@2:d2cb8c8ecd6e, 2014-05-19 (annotated)

Committer:
Mike Fiore
Date:
Mon May 19 12:35:18 2014 -0500
Revision:
2:d2cb8c8ecd6e
Parent:
1:d34b566d6f47
Child:
4:d348d001283b
add "mbed.h" to headers

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 2:d2cb8c8ecd6e 4 #include "mbed.h"
Mike Fiore 1:d34b566d6f47 5 #include "MTSCircularBuffer.h"
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);
Mike Fiore 1:d34b566d6f47 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 */
Mike Fiore 1:d34b566d6f47 55 int write(const char* data, int length);
Mike Fiore 1:d34b566d6f47 56
Mike Fiore 1:d34b566d6f47 57 /** This method attempts to write a single byte to the tx buffer
Mike Fiore 1:d34b566d6f47 58 * within the timeout period.
Mike Fiore 1:d34b566d6f47 59 *
Mike Fiore 1:d34b566d6f47 60 * @param data the byte to be written as a char.
Mike Fiore 1:d34b566d6f47 61 * @timeoutMillis amount of time in milliseconds to complete operation.
Mike Fiore 1:d34b566d6f47 62 * @returns 1 if the byte was written or 0 if the buffer was full and the timeout
Mike Fiore 1:d34b566d6f47 63 * expired.
Mike Fiore 1:d34b566d6f47 64 */
Mike Fiore 1:d34b566d6f47 65 int write(char data, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 66
Mike Fiore 1:d34b566d6f47 67 /** This method writes a signle byte as a char to the Tx or write buffer.
Mike Fiore 1:d34b566d6f47 68 * This method blocks until the byte is written.
Mike Fiore 1:d34b566d6f47 69 *
Mike Fiore 1:d34b566d6f47 70 * @param data the byte to be written as a char.
Mike Fiore 1:d34b566d6f47 71 * @returns 1 once the byte has been written.
Mike Fiore 1:d34b566d6f47 72 */
Mike Fiore 1:d34b566d6f47 73 int write(char data);
Mike Fiore 1:d34b566d6f47 74
Mike Fiore 1:d34b566d6f47 75 /** This method is used to get the space available to write bytes to the Tx buffer.
Mike Fiore 1:d34b566d6f47 76 *
Mike Fiore 1:d34b566d6f47 77 * @returns the number of bytes that can be written, 0 if the buffer is full.
Mike Fiore 1:d34b566d6f47 78 */
Mike Fiore 1:d34b566d6f47 79 int writeable();
Mike Fiore 1:d34b566d6f47 80
Mike Fiore 1:d34b566d6f47 81 /** This method enables bulk reads from the Rx or read buffer. It attempts
Mike Fiore 1:d34b566d6f47 82 * to read the amount specified, but will complete early if the specified timeout
Mike Fiore 1:d34b566d6f47 83 * expires.
Mike Fiore 1:d34b566d6f47 84 *
Mike Fiore 1:d34b566d6f47 85 * @param data the buffer where data read will be added to.
Mike Fiore 1:d34b566d6f47 86 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:d34b566d6f47 87 * @timeoutMillis amount of time to complete operation.
Mike Fiore 1:d34b566d6f47 88 * @returns the total number of bytes that were read.
Mike Fiore 1:d34b566d6f47 89 */
Mike Fiore 1:d34b566d6f47 90 int read(char* data, int length, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 91
Mike Fiore 1:d34b566d6f47 92 /** This method enables bulk reads from the Rx or read buffer. This method
Mike Fiore 1:d34b566d6f47 93 * blocks until the amount of data requested is received.
Mike Fiore 1:d34b566d6f47 94 *
Mike Fiore 1:d34b566d6f47 95 * @param data the buffer where data read will be added to.
Mike Fiore 1:d34b566d6f47 96 * @param length the amount of data in bytes to be read into the buffer.
Mike Fiore 1:d34b566d6f47 97 * @returns the total number of bytes that were read. This should be equal
Mike Fiore 1:d34b566d6f47 98 * to the length parameter since this is a blocking call.
Mike Fiore 1:d34b566d6f47 99 */
Mike Fiore 1:d34b566d6f47 100 int read(char* data, int length);
Mike Fiore 1:d34b566d6f47 101
Mike Fiore 1:d34b566d6f47 102 /** This method reads a single byte from the Rx or read buffer. This method
Mike Fiore 1:d34b566d6f47 103 * attempts to read a byte, but will return without reading one if the specified
Mike Fiore 1:d34b566d6f47 104 * timeout is reached.
Mike Fiore 1:d34b566d6f47 105 *
Mike Fiore 1:d34b566d6f47 106 * @param data char where the read byte will be stored.
Mike Fiore 1:d34b566d6f47 107 * @timeoutMillis amount of time to complete operation.
Mike Fiore 1:d34b566d6f47 108 * @returns 1 if byte is read or 0 if no byte is available.
Mike Fiore 1:d34b566d6f47 109 */
Mike Fiore 1:d34b566d6f47 110 int read(char& data, unsigned int timeoutMillis);
Mike Fiore 1:d34b566d6f47 111
Mike Fiore 1:d34b566d6f47 112 /** This method reads a single byte from the Rx or read buffer.
Mike Fiore 1:d34b566d6f47 113 * This method blocks until the single byte is read.
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 * @returns 1 once the byte has been read.
Mike Fiore 1:d34b566d6f47 117 */
Mike Fiore 1:d34b566d6f47 118 int read(char& data);
Mike Fiore 1:d34b566d6f47 119
Mike Fiore 1:d34b566d6f47 120 /** This method is used to get the number of bytes available to read from
Mike Fiore 1:d34b566d6f47 121 * the Rx or read buffer.
Mike Fiore 1:d34b566d6f47 122 *
Mike Fiore 1:d34b566d6f47 123 * @returns the number of bytes available, 0 if there are no bytes to read.
Mike Fiore 1:d34b566d6f47 124 */
Mike Fiore 1:d34b566d6f47 125 int readable();
Mike Fiore 1:d34b566d6f47 126
Mike Fiore 1:d34b566d6f47 127 /** This method determines if the Tx or write buffer is empty.
Mike Fiore 1:d34b566d6f47 128 *
Mike Fiore 1:d34b566d6f47 129 * @returns true if empty, otherwise false.
Mike Fiore 1:d34b566d6f47 130 */
Mike Fiore 1:d34b566d6f47 131 bool txEmpty();
Mike Fiore 1:d34b566d6f47 132
Mike Fiore 1:d34b566d6f47 133 /** This method determines if the Rx or read buffer is empty.
Mike Fiore 1:d34b566d6f47 134 *
Mike Fiore 1:d34b566d6f47 135 * @returns true if empty, otherwise false.
Mike Fiore 1:d34b566d6f47 136 */
Mike Fiore 1:d34b566d6f47 137 bool rxEmpty();
Mike Fiore 1:d34b566d6f47 138
Mike Fiore 1:d34b566d6f47 139 /** This method determines if the Tx or write buffer is full.
Mike Fiore 1:d34b566d6f47 140 *
Mike Fiore 1:d34b566d6f47 141 * @returns true if full, otherwise false.
Mike Fiore 1:d34b566d6f47 142 */
Mike Fiore 1:d34b566d6f47 143 bool txFull();
Mike Fiore 1:d34b566d6f47 144
Mike Fiore 1:d34b566d6f47 145 /** This method determines if the Rx or read buffer is full.
Mike Fiore 1:d34b566d6f47 146 *
Mike Fiore 1:d34b566d6f47 147 * @returns true if full, otherwise false.
Mike Fiore 1:d34b566d6f47 148 */
Mike Fiore 1:d34b566d6f47 149 bool rxFull();
Mike Fiore 1:d34b566d6f47 150
Mike Fiore 1:d34b566d6f47 151 /** This method clears all the data from the internal Tx or write buffer.
Mike Fiore 1:d34b566d6f47 152 */
Mike Fiore 1:d34b566d6f47 153 virtual void txClear();
Mike Fiore 1:d34b566d6f47 154
Mike Fiore 1:d34b566d6f47 155 /** This method clears all the data from the internal Rx or read buffer.
Mike Fiore 1:d34b566d6f47 156 */
Mike Fiore 1:d34b566d6f47 157 virtual void rxClear();
Mike Fiore 1:d34b566d6f47 158
Mike Fiore 1:d34b566d6f47 159 /** This abstract method should be used by the deriving class to transfer
Mike Fiore 1:d34b566d6f47 160 * data from the internal write buffer (txBuffer) to the physical interface.
Mike Fiore 1:d34b566d6f47 161 * Note that this function is called everytime new data is written to the
Mike Fiore 1:d34b566d6f47 162 * txBuffer through one of the write calls.
Mike Fiore 1:d34b566d6f47 163 */
Mike Fiore 1:d34b566d6f47 164 virtual void handleWrite() = 0;
Mike Fiore 1:d34b566d6f47 165
Mike Fiore 1:d34b566d6f47 166 /** This abstract method should be used by the deriving class to transfer
Mike Fiore 1:d34b566d6f47 167 * data from the physical interface ot the internal read buffer (rxBuffer).
Mike Fiore 1:d34b566d6f47 168 * Note that this function is never called in this class and typically should
Mike Fiore 1:d34b566d6f47 169 * be called as part of a receive data interrupt routine.
Mike Fiore 1:d34b566d6f47 170 */
Mike Fiore 1:d34b566d6f47 171 virtual void handleRead() = 0;
Mike Fiore 1:d34b566d6f47 172
Mike Fiore 1:d34b566d6f47 173 protected:
Mike Fiore 1:d34b566d6f47 174 MTSCircularBuffer txBuffer; // Internal write or transmit circular buffer
Mike Fiore 1:d34b566d6f47 175 MTSCircularBuffer rxBuffer; // Internal read or receieve circular buffer
Mike Fiore 1:d34b566d6f47 176 };
Mike Fiore 1:d34b566d6f47 177
Mike Fiore 1:d34b566d6f47 178 }
Mike Fiore 1:d34b566d6f47 179
Mike Fiore 1:d34b566d6f47 180 #endif /* MTSBUFFEREDIO_H */