AbstractDataSource.h

00001 /*
00002  * AbstractDataSource.h
00003  *
00004  * Created on: Nov 1, 2013
00005  * * Authors: Vincent Wochnik <v.wochnik@gmail.com>
00006  *
00007  * Copyright (c) 2013 Cumulocity GmbH
00008  *
00009  * Permission is hereby granted, free of charge, to any person obtaining
00010  * a copy of this software and associated documentation files (the
00011  * "Software"), to deal in the Software without restriction, including
00012  * without limitation the rights to use, copy, modify, merge, publish,
00013  * distribute, sublicense, and/or sell copies of the Software, and to
00014  * permit persons to whom the Software is furnished to do so, subject to
00015  * the following conditions:
00016  *
00017  * The above copyright notice and this permission notice shall be
00018  * included in all copies or substantial portions of the Software.
00019  *
00020  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00021  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00022  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00023  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
00024  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
00025  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00026  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00027  */
00028 
00029 /**
00030  * @file AbstractDataSource.h
00031  * An abstraction layer which provides means to read data from a
00032  * connection.
00033  * 
00034  * Example:
00035  * @code
00036  * AbstractDataSource source;
00037  * char c;
00038  * while (((c = source.read()) > 0) || (source.status() == DS_STATUS_OK)) {
00039  *     // read action
00040  * }
00041  * switch (source.status()) {
00042  * case DS_STATUS_OK:
00043  *     // ok
00044  * case DS_STATUS_CLOSED:
00045  *     // connection closed
00046  * case DS_STATUS_TIMEOUT:
00047  *     // timeout
00048  * default:
00049  *     // other error
00050  * }
00051  * @encode
00052  * 
00053  */
00054 
00055 #ifndef ABSTRACTDATASOURCE_H
00056 #define ABSTRACTDATASOURCE_H
00057 
00058 #include "config.h"
00059 #include <stdint.h>
00060 
00061 /** Return value indicating that no error has occurred. */
00062 #define DS_STATUS_OK 0
00063 /** Return value indicating that the connection has been closed by this
00064  * or the foreign host. */
00065 #define DS_STATUS_CLOSED 1
00066 /** Return value indicating a transmission timeout. */
00067 #define DS_STATUS_TIMEOUT 2
00068 /** Return value indicating a state error. */
00069 #define DS_STATUS_ERROR 3
00070 
00071 /*
00072  * The AbstractDataSource class provides a way to read data from a
00073  * connection.
00074  */
00075 class AbstractDataSource
00076 {
00077     public:
00078         virtual ~AbstractDataSource() { };
00079 
00080         /**
00081          * Reads one character. When successful, the returned value
00082          * represents the character. Otherwise, status() will return a
00083          * non-zero value. This function is blocking.
00084          * @return the caracter read or zero. If the return value is
00085          * non-zero, status() is zero. Otherwise, check status() for a
00086          * non-zero value.
00087          */
00088         virtual char read() = 0;
00089 
00090         /**
00091          * Returns the current read state. If a non-zero value is returned,
00092          * there is an error. Otherwise, everything is ok.
00093          * DS_STATUS_TIMEOUT means that there has been a read timeout.
00094          * DS_STATUS_CLOSED means that the connection has been closed
00095          * by either this or the foreign host.
00096          * @return the status value
00097          */
00098         virtual uint8_t status() = 0;
00099 };
00100 
00101 #endif