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 #ifdef HAVE_CONFIG_H
00059 #include <config.h>
00060 #endif
00061 
00062 #include <stdint.h>
00063 
00064 /** Return value indicating that no error has occurred. */
00065 #define DS_STATUS_OK 0
00066 /** Return value indicating that the connection has been closed by this
00067  * or the foreign host. */
00068 #define DS_STATUS_CLOSED 1
00069 /** Return value indicating a transmission timeout. */
00070 #define DS_STATUS_TIMEOUT 2
00071 /** Return value indicating a state error. */
00072 #define DS_STATUS_ERROR 3
00073 
00074 /*
00075  * The AbstractDataSource class provides a way to read data from a
00076  * connection.
00077  */
00078 class AbstractDataSource
00079 {
00080 public:
00081     virtual ~AbstractDataSource() { };
00082 
00083     /**
00084      * Reads one character. When successful, the returned value
00085      * represents the character. Otherwise, status() will return a
00086      * non-zero value. This function is blocking.
00087      * @return the caracter read or zero. If the return value is
00088      * non-zero, status() is zero. Otherwise, check status() for a
00089      * non-zero value.
00090      */
00091     virtual char read() = 0;
00092 
00093     /**
00094      * Returns the current read state. If a non-zero value is returned,
00095      * there is an error. Otherwise, everything is ok.
00096      * DS_STATUS_TIMEOUT means that there has been a read timeout.
00097      * DS_STATUS_CLOSED means that the connection has been closed
00098      * by either this or the foreign host.
00099      * @return the status value
00100      */
00101     virtual uint8_t status() = 0;
00102 };
00103 
00104 #endif