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@141:571e0ef6c8dc, 2014-01-04 (annotated)

Committer:
kranjan
Date:
Sat Jan 04 05:28:45 2014 +0000
Revision:
141:571e0ef6c8dc
Parent:
101:27bb34e23304 
Added licensing header to all files in the library

Who changed what in which revision?

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