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@45:40745c2036cf, 2013-12-19 (annotated)

Committer:
jengbrecht
Date:
Thu Dec 19 21:38:01 2013 +0000
Revision:
45:40745c2036cf
Parent:
36:bb6b293c7495
Child:
46:b30547bf07d5
Added a ton of documentation, made the notify start and stop methods private in MTSSerialFlowControl, added format method to the serial classes, fixed an issue in the bulk write method of MTSCircularBuffer

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
jengbrecht 36:bb6b293c7495 7 /** This is an abstract class for lightweight buffered io to an underlying
jengbrecht 36:bb6b293c7495 8 * data interface. Specifically the inheriting class will need to override
jengbrecht 45:40745c2036cf 9 * both the handleRead and handleWrite methods which transfer data between
jengbrecht 45:40745c2036cf 10 * the class's internal read and write buffers and the physical communications
jengbrecht 36:bb6b293c7495 11 * link or its HW buffers.
jengbrecht 36:bb6b293c7495 12 */
jengbrecht 0:563b70517320 13 class MTSBufferedIO
jengbrecht 0:563b70517320 14 {
jengbrecht 0:563b70517320 15 public:
jengbrecht 36:bb6b293c7495 16 /** Creates a new BufferedIO object with the passed in static buffer sizes.
jengbrecht 36:bb6b293c7495 17 * Note that because this class is abstract you cannot construct it directly.
jengbrecht 45:40745c2036cf 18 * Instead, please construct one of its derived classes like MTSSerial or
jengbrecht 36:bb6b293c7495 19 * MTSSerialFlowControl.
jengbrecht 45:40745c2036cf 20 *
jengbrecht 45:40745c2036cf 21 * @param txBufferSize the size of the Tx or write buffer in bytes. The default is
jengbrecht 45:40745c2036cf 22 * 128 bytes.
jengbrecht 45:40745c2036cf 23 * @param rxBufferSize the size of the Rx or read buffer in bytes. The default is
jengbrecht 45:40745c2036cf 24 * 128 bytes.
jengbrecht 36:bb6b293c7495 25 */
jengbrecht 0:563b70517320 26 MTSBufferedIO(int txBufferSize = 128, int rxBufferSize = 128);
jengbrecht 36:bb6b293c7495 27
jengbrecht 36:bb6b293c7495 28 /** Destructs an MTSBufferedIO object and frees all related resources, including
jengbrecht 36:bb6b293c7495 29 * internal buffers.
jengbrecht 36:bb6b293c7495 30 */
jengbrecht 0:563b70517320 31 ~MTSBufferedIO();
jengbrecht 0:563b70517320 32
jengbrecht 45:40745c2036cf 33 /** This method enables bulk writes to the Tx or wriet buffer. If more data
jengbrecht 45:40745c2036cf 34 * is requested to be written then space available the method writes
jengbrecht 45:40745c2036cf 35 * as much data as possible and returns the actual amount written.
jengbrecht 45:40745c2036cf 36 *
jengbrecht 45:40745c2036cf 37 * @param data the byte array to be written.
jengbrecht 45:40745c2036cf 38 * @param length the length of data to be written from the data paramter.
jengbrecht 45:40745c2036cf 39 * @returns the number of bytes written to the buffer, which is 0 if
jengbrecht 45:40745c2036cf 40 * the buffer is full.
jengbrecht 45:40745c2036cf 41 */
jengbrecht 0:563b70517320 42 int write(char* data, int length);
jengbrecht 45:40745c2036cf 43
jengbrecht 45:40745c2036cf 44 /** This method writes a signle byte as a char to the Tx or write buffer.
jengbrecht 45:40745c2036cf 45 *
jengbrecht 45:40745c2036cf 46 * @param data the byte to be written as a char.
jengbrecht 45:40745c2036cf 47 * @returns 1 if the byte was written or 0 if the buffer was full.
jengbrecht 45:40745c2036cf 48 */
jengbrecht 0:563b70517320 49 int write(char data);
jengbrecht 45:40745c2036cf 50
jengbrecht 45:40745c2036cf 51 /** This method is used to get the space available to write bytes to the Tx buffer.
jengbrecht 45:40745c2036cf 52 *
jengbrecht 45:40745c2036cf 53 * @returns the number of bytes that can be written, 0 if the buffer is full.
jengbrecht 45:40745c2036cf 54 */
sgodinez 17:2d7c4ea7491b 55 int writeable();
jengbrecht 45:40745c2036cf 56
jengbrecht 45:40745c2036cf 57 /** This method enables bulk reads from the Rx or read buffer. If more data is
jengbrecht 45:40745c2036cf 58 * requested then available it simply returns all remaining data within the
jengbrecht 45:40745c2036cf 59 * buffer.
jengbrecht 45:40745c2036cf 60 *
jengbrecht 45:40745c2036cf 61 * @param data the buffer where data read will be added to.
jengbrecht 45:40745c2036cf 62 * @param length the amount of data in bytes to be read into the buffer.
jengbrecht 45:40745c2036cf 63 * @returns the total number of bytes that were read.
jengbrecht 45:40745c2036cf 64 */
jengbrecht 0:563b70517320 65 int read(char* data, int length);
jengbrecht 45:40745c2036cf 66
jengbrecht 45:40745c2036cf 67 /** This method reads a single byte from the Rx or read buffer.
jengbrecht 45:40745c2036cf 68 *
jengbrecht 45:40745c2036cf 69 * @param data char where the read byte will be stored.
jengbrecht 45:40745c2036cf 70 * @returns 1 if byte is read or 0 if no byte is available.
jengbrecht 45:40745c2036cf 71 */
sgodinez 17:2d7c4ea7491b 72 int read(char& data);
jengbrecht 45:40745c2036cf 73
jengbrecht 45:40745c2036cf 74 /** This method is used to get the number of bytes available to read from
jengbrecht 45:40745c2036cf 75 * the Rx or read buffer.
jengbrecht 45:40745c2036cf 76 *
jengbrecht 45:40745c2036cf 77 * @returns the number of bytes available, 0 if there are no bytes to read.
jengbrecht 45:40745c2036cf 78 */
sgodinez 17:2d7c4ea7491b 79 int readable();
jengbrecht 0:563b70517320 80
jengbrecht 36:bb6b293c7495 81 /** This method determines if the Tx or write buffer is empty.
jengbrecht 36:bb6b293c7495 82 *
jengbrecht 36:bb6b293c7495 83 * @returns true if empty, otherwise false.
jengbrecht 36:bb6b293c7495 84 */
jengbrecht 0:563b70517320 85 bool txEmpty();
jengbrecht 36:bb6b293c7495 86
jengbrecht 36:bb6b293c7495 87 /** This method determines if the Rx or read buffer is empty.
jengbrecht 36:bb6b293c7495 88 *
jengbrecht 36:bb6b293c7495 89 * @returns true if empty, otherwise false.
jengbrecht 36:bb6b293c7495 90 */
jengbrecht 0:563b70517320 91 bool rxEmpty();
jengbrecht 36:bb6b293c7495 92
jengbrecht 36:bb6b293c7495 93 /** This method determines if the Tx or write buffer is full.
jengbrecht 36:bb6b293c7495 94 *
jengbrecht 36:bb6b293c7495 95 * @returns true if full, otherwise false.
jengbrecht 36:bb6b293c7495 96 */
jengbrecht 0:563b70517320 97 bool txFull();
jengbrecht 36:bb6b293c7495 98
jengbrecht 36:bb6b293c7495 99 /** This method determines if the Rx or read buffer is full.
jengbrecht 36:bb6b293c7495 100 *
jengbrecht 36:bb6b293c7495 101 * @returns true if full, otherwise false.
jengbrecht 36:bb6b293c7495 102 */
jengbrecht 0:563b70517320 103 bool rxFull();
jengbrecht 36:bb6b293c7495 104
jengbrecht 36:bb6b293c7495 105 /** This method clears all the data from the internal Tx or write buffer.
jengbrecht 36:bb6b293c7495 106 */
jengbrecht 0:563b70517320 107 void txClear();
jengbrecht 36:bb6b293c7495 108
jengbrecht 36:bb6b293c7495 109 /** This method clears all the data from the internal Rx or read buffer.
jengbrecht 36:bb6b293c7495 110 */
jengbrecht 0:563b70517320 111 void rxClear();
jengbrecht 0:563b70517320 112
jengbrecht 36:bb6b293c7495 113 /** This abstract method should be used by the deriving class to transfer
jengbrecht 36:bb6b293c7495 114 * data from the internal write buffer (txBuffer) to the physical interface.
jengbrecht 36:bb6b293c7495 115 * Note that this function is called everytime new data is written to the
jengbrecht 36:bb6b293c7495 116 * txBuffer though one of the write calls.
jengbrecht 36:bb6b293c7495 117 */
jengbrecht 0:563b70517320 118 virtual void handleWrite() = 0;
jengbrecht 36:bb6b293c7495 119
jengbrecht 36:bb6b293c7495 120 /** This abstract method should be used by the deriving class to transfer
jengbrecht 36:bb6b293c7495 121 * data from the physical interface ot the internal read buffer (rxBuffer).
jengbrecht 36:bb6b293c7495 122 * Note that this function is never called in this class and typically should
jengbrecht 36:bb6b293c7495 123 * be called as part of a receive data interrupt routine.
jengbrecht 36:bb6b293c7495 124 */
jengbrecht 0:563b70517320 125 virtual void handleRead() = 0;
jengbrecht 0:563b70517320 126
jengbrecht 0:563b70517320 127 protected:
jengbrecht 36:bb6b293c7495 128 MTSCircularBuffer* txBuffer; // Internal write or transmit circular buffer
jengbrecht 36:bb6b293c7495 129 MTSCircularBuffer* rxBuffer; // Internal read or receieve circular buffer
jengbrecht 0:563b70517320 130 };
jengbrecht 0:563b70517320 131
jengbrecht 0:563b70517320 132 #endif /* MTSBUFFEREDIO_H */