Multi-Hackers / SocketModem

A library for talking to Multi-Tech's Cellular SocketModem Devices.

Dependents:   M2X_dev axeda_wrapper_dev MTS_M2x_Example1 MTS_Cellular_Connect_Example ... more

io/MTSBufferedIO.h@81:45e1359a5c69, 2013-12-27 (annotated)

Committer:
jengbrecht
Date:
Fri Dec 27 15:19:49 2013 +0000
Revision:
81:45e1359a5c69
Parent:
68:c490e4a51778
Child:
86:186bbf974c7c
Made update to MTSSerial to make it more robust.

Who changed what in which revision?

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