Streams

The framework StreamI interface offers a portable stream definition. The BufferedStreamI complements the StreamI interface by offering an interface to buffered operations (e.g. Printf and GetToken).

Warning

Some operations (e.g. Read, Printf, …) might change the stream cursor position. Always remember to Seek to the appropriate position (e.g. Seek(0)).

StreamString

The StreamString is the framework string implementation and allows to read and write to an underlying unbounded string that can grow dynamically.

StreamString s1 = "Hello";
//The cursor of s1 will be pointing at the end. As a consequence an empty string will be printed.
REPORT_ERROR_STATIC(ErrorManagement::Information, "s1 = %s", s1);
s1.Seek(0);
REPORT_ERROR_STATIC(ErrorManagement::Information, "{After seek} s1 = %s", s1);
//The buffer will return the pointer to the start of the string.
REPORT_ERROR_STATIC(ErrorManagement::Information, "{Buffer()} s1 = %s", s1.Buffer());

StreamString s3 = s1;
s3.Seek(0);
s3.Printf("%s", "Hi");
//This will print Hillo....
REPORT_ERROR_STATIC(ErrorManagement::Information, "{After Printf} s3 = %s", s3.Buffer());
//Reset the string
s3 = "";
s3.Printf("%s", "Hi");
REPORT_ERROR_STATIC(ErrorManagement::Information, "{After =\"\"} s3 = %s", s3.Buffer());

Basic streams

The Basic streams implementation allow to access the underlying media (e.g. file, socket, …) using the StreamI interface, but do not allow more advanced operations (e.g. Printf, GetToken, …) which require buffered support.

The following basic streams are available: BasicConsole, BasicFile, BasicTCPSocket and BasicUDPSocket.

BasicUDPSocket sock;
bool ok = sock.Open();
...
ok = sock.Listen(port);
...
BasicConsole bc;
...
bc.Open(BasicConsoleMode::EnablePaging);
bc.SetSceneSize(ncols, nrows);
...
BasicFile f;
ok = f.Open(TEST_FILENAME, BasicFile::FLAG_CREAT | BasicFile::ACCESS_MODE_W);
...
MARTe::uint32 writeSize = str.Size();
stream.Write(str.Buffer(), writeSize);

Buffered streams

The buffered streams complement the basic streams with buffered operations.

The following buffered streams are available: StreamString, File, TCPSocket and UDPSocket.

UDPSocket sock;
bool ok = sock.Open();
...
ok = sock.Listen(port);
...
File f;
ok = f.Open(TEST_FILENAME, BasicFile::FLAG_CREAT | BasicFile::ACCESS_MODE_W);
...
stream.GetLine(line);
while (line.GetToken(token, ":", term)) {
   ...
   token = "";
}
line = "";

Warning

When using the GetLine and GetToken methods, always remember to reset the output parameters (e.g. line = ""; token = "";).

Examples

StreamString

The following example shows some typical use-cases of the strings.

StreamString example (StreamStringExample1)
 1/**
 2 * @file StreamStringExample1.cpp
 3 * @brief Source file for class StreamStringExample1
 4 * @date 30/04/2018
 5 * @author Andre Neto
 6 *
 7 * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
 8 * the Development of Fusion Energy ('Fusion for Energy').
 9 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved
10 * by the European Commission - subsequent versions of the EUPL (the "Licence")
11 * You may not use this work except in compliance with the Licence.
12 * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
13 *
14 * @warning Unless required by applicable law or agreed to in writing, 
15 * software distributed under the Licence is distributed on an "AS IS"
16 * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
17 * or implied. See the Licence permissions and limitations under the Licence.
18
19 * @details This source file contains the definition of all the methods for
20 * the class StreamStringExample1 (public, protected, and private). Be aware that some
21 * methods, such as those inline could be defined on the header file, instead.
22 */
23
24/*---------------------------------------------------------------------------*/
25/*                         Standard header includes                          */
26/*---------------------------------------------------------------------------*/
27
28/*---------------------------------------------------------------------------*/
29/*                         Project header includes                           */
30/*---------------------------------------------------------------------------*/
31#include "AdvancedErrorManagement.h"
32#include "ErrorLoggerExample.h"
33#include "StreamString.h"
34
35/*---------------------------------------------------------------------------*/
36/*                           Static definitions                              */
37/*---------------------------------------------------------------------------*/
38
39/*---------------------------------------------------------------------------*/
40/*                           Method definitions                              */
41/*---------------------------------------------------------------------------*/
42
43int main(int argc, char *argv[]) {
44    using namespace MARTe;
45    SetErrorProcessFunction(&ErrorProcessExampleFunction);
46
47    StreamString s1 = "Hello";
48    //The cursor of s1 will be pointing at the end. As a consequence an empty string will be printed.
49    REPORT_ERROR_STATIC(ErrorManagement::Information, "s1 = %s", s1);
50    s1.Seek(0);
51    REPORT_ERROR_STATIC(ErrorManagement::Information, "{After seek} s1 = %s", s1);
52    //The buffer will return the pointer to the start of the string.
53    REPORT_ERROR_STATIC(ErrorManagement::Information, "{Buffer()} s1 = %s", s1.Buffer());
54
55    StreamString s2 = s1;
56    //The cursor of s2 will also be pointing at the end. As a consequence an empty string will be printed.
57    REPORT_ERROR_STATIC(ErrorManagement::Information, "s2 = %s", s2);
58    s2.Seek(1);
59    REPORT_ERROR_STATIC(ErrorManagement::Information, "{After seek:1} s2 = %s", s2);
60
61    StreamString s3 = s1;
62    s3.Seek(0);
63    s3.Printf("%s", "Hi");
64    REPORT_ERROR_STATIC(ErrorManagement::Information, "{After Printf} s3 = %s", s3.Buffer());
65
66    //Reset the string
67    s3 = "";
68    s3.Printf("%s", "Hi");
69    REPORT_ERROR_STATIC(ErrorManagement::Information, "{After =\"\"} s3 = %s", s3.Buffer());
70
71    return 0;
72}

Basic streams

The following is an example which highlights the usage of the basic streams.

Basic streams example (BasicStreamsExample1)
  1/**
  2 * @file BasicStreamsExample1.cpp
  3 * @brief Source file for class BasicStreamsExample1
  4 * @date 30/04/2018
  5 * @author Andre Neto
  6 *
  7 * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
  8 * the Development of Fusion Energy ('Fusion for Energy').
  9 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved
 10 * by the European Commission - subsequent versions of the EUPL (the "Licence")
 11 * You may not use this work except in compliance with the Licence.
 12 * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
 13 *
 14 * @warning Unless required by applicable law or agreed to in writing, 
 15 * software distributed under the Licence is distributed on an "AS IS"
 16 * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 17 * or implied. See the Licence permissions and limitations under the Licence.
 18
 19 * @details This source file contains the definition of all the methods for
 20 * the class BasicStreamsExample1 (public, protected, and private). Be aware that some
 21 * methods, such as those inline could be defined on the header file, instead.
 22 */
 23
 24/*---------------------------------------------------------------------------*/
 25/*                         Standard header includes                          */
 26/*---------------------------------------------------------------------------*/
 27
 28/*---------------------------------------------------------------------------*/
 29/*                         Project header includes                           */
 30/*---------------------------------------------------------------------------*/
 31#include "AdvancedErrorManagement.h"
 32#include "Directory.h"
 33#include "ErrorLoggerExample.h"
 34#include "BasicConsole.h"
 35#include "BasicFile.h"
 36#include "BasicUDPSocket.h"
 37
 38/*---------------------------------------------------------------------------*/
 39/*                           Static definitions                              */
 40/*---------------------------------------------------------------------------*/
 41
 42/**
 43 * @brief Writes to the specified stream
 44 */
 45static void WriteToBasicStream(MARTe::StreamI &stream, MARTe::StreamString &str) {
 46    MARTe::uint32 writeSize = str.Size();
 47    stream.Write(str.Buffer(), writeSize);
 48}
 49
 50/*---------------------------------------------------------------------------*/
 51/*                           Method definitions                              */
 52/*---------------------------------------------------------------------------*/
 53
 54int main(int argc, char *argv[]) {
 55    using namespace MARTe;
 56    SetErrorProcessFunction(&ErrorProcessExampleFunction);
 57
 58    BasicUDPSocket sock;
 59    bool ok = sock.Open();
 60    uint16 port = 24680;
 61    if (ok) {
 62        REPORT_ERROR_STATIC(ErrorManagement::Information, "Going to listen in port = %d", port);
 63        ok = sock.Listen(port);
 64    }
 65    if (!ok) {
 66        REPORT_ERROR_STATIC(ErrorManagement::FatalError, "Failed to listen in port = %d", port);
 67    }
 68
 69    StreamString recStream;
 70    if (ok) {
 71        const uint32 MAX_BUFFER_SIZE = 512;
 72        char8 buffer[MAX_BUFFER_SIZE];
 73        uint32 bufferSize = MAX_BUFFER_SIZE;
 74        ok = sock.Read(buffer, bufferSize);
 75        if (bufferSize == MAX_BUFFER_SIZE) {
 76            bufferSize = (MAX_BUFFER_SIZE - 1);
 77        }
 78        buffer[bufferSize] = '\0';
 79        if (ok) {
 80            recStream = buffer;
 81            REPORT_ERROR_STATIC(ErrorManagement::Information, "Read from UDP: %s", recStream.Buffer());
 82        }
 83        ok = sock.Close();
 84    }
 85    if (ok) {
 86        BasicConsole bc;
 87        uint32 ncols = 24;
 88        uint32 nrows = 8;
 89        bc.Open(BasicConsoleMode::EnablePaging);
 90        bc.SetSceneSize(ncols, nrows);
 91        StreamString str;
 92        str.Printf("BasicConsole: %s", recStream.Buffer());
 93        REPORT_ERROR_STATIC(ErrorManagement::Information, "Writing into console: %s", str.Buffer());
 94        WriteToBasicStream(bc, str);
 95        bc.Close();
 96    }
 97
 98    const char8 * const TEST_FILENAME = "BasicStreamTestExample1.out";
 99    if (ok) {
100        BasicFile f;
101        ok = f.Open(TEST_FILENAME, BasicFile::FLAG_CREAT | BasicFile::ACCESS_MODE_W);
102        if (ok) {
103            StreamString str;
104            str.Printf("BasicFile: %s", recStream.Buffer());
105            REPORT_ERROR_STATIC(ErrorManagement::Information, "Writing into file: %s", str.Buffer());
106            WriteToBasicStream(f, str);
107            f.Close();
108        }
109    }
110    if (ok) {
111        const uint32 MAX_BUFFER_SIZE = 512;
112        char8 buffer[MAX_BUFFER_SIZE];
113        uint32 bufferSize = MAX_BUFFER_SIZE;
114        BasicFile f;
115        ok = f.Open(TEST_FILENAME, BasicFile::ACCESS_MODE_R);
116        if (ok) {
117            ok = f.Read(&buffer[0], bufferSize);
118            f.Close();
119        }
120        if (ok) {
121            StreamString readStr = buffer;
122            REPORT_ERROR_STATIC(ErrorManagement::Information, "Read from File: %s", readStr.Buffer());
123            Directory d(TEST_FILENAME);
124            d.Delete();
125        }
126    }
127    return 0;
128}

Start the application and, in another console, type echo -e "HELLO" | nc 127.0.0.1 24680 -w0.

Basic streams

The following is an example that shows the usage of the buffered streams (including the GetLine, GetToken and Printf methods).

Buffered streams example (BufferedStreamsExample1)
  1/**
  2 * @file BufferedStreamsExample1.cpp
  3 * @brief Source file for class BufferedStreamsExample1
  4 * @date 30/04/2018
  5 * @author Andre Neto
  6 *
  7 * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
  8 * the Development of Fusion Energy ('Fusion for Energy').
  9 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved
 10 * by the European Commission - subsequent versions of the EUPL (the "Licence")
 11 * You may not use this work except in compliance with the Licence.
 12 * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
 13 *
 14 * @warning Unless required by applicable law or agreed to in writing, 
 15 * software distributed under the Licence is distributed on an "AS IS"
 16 * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 17 * or implied. See the Licence permissions and limitations under the Licence.
 18
 19 * @details This source file contains the definition of all the methods for
 20 * the class BufferedStreamsExample1 (public, protected, and private). Be aware that some
 21 * methods, such as those inline could be defined on the header file, instead.
 22 */
 23
 24/*---------------------------------------------------------------------------*/
 25/*                         Standard header includes                          */
 26/*---------------------------------------------------------------------------*/
 27
 28/*---------------------------------------------------------------------------*/
 29/*                         Project header includes                           */
 30/*---------------------------------------------------------------------------*/
 31#include "AdvancedErrorManagement.h"
 32#include "BufferedStreamI.h"
 33#include "Directory.h"
 34#include "ErrorLoggerExample.h"
 35#include "File.h"
 36#include "UDPSocket.h"
 37
 38/*---------------------------------------------------------------------------*/
 39/*                           Static definitions                              */
 40/*---------------------------------------------------------------------------*/
 41
 42/**
 43 * @brief Parses tokens from a given stream
 44 */
 45static void GetTokensFromStream(MARTe::BufferedStreamI &stream) {
 46    using namespace MARTe;
 47    StreamString line = "";
 48    bool end = false;
 49    while (!end) {
 50        stream.GetLine(line);
 51        StreamString token = "";
 52        char8 term;
 53        line.Seek(0u);
 54        REPORT_ERROR_STATIC(ErrorManagement::Information, "Line: %s", line.Buffer());
 55        while (line.GetToken(token, ":", term)) {
 56            REPORT_ERROR_STATIC(ErrorManagement::Information, "Token: %s", token.Buffer());
 57            end = (token == "END");
 58            token = "";
 59        }
 60        line = "";
 61    }
 62}
 63
 64/*---------------------------------------------------------------------------*/
 65/*                           Method definitions                              */
 66/*---------------------------------------------------------------------------*/
 67
 68int main(int argc, char *argv[]) {
 69    using namespace MARTe;
 70    SetErrorProcessFunction(&ErrorProcessExampleFunction);
 71
 72    UDPSocket sock;
 73    bool ok = sock.Open();
 74    uint16 port = 24680;
 75    if (ok) {
 76        REPORT_ERROR_STATIC(ErrorManagement::Information, "Going to listen in port = %d", port);
 77        ok = sock.Listen(port);
 78    }
 79    if (!ok) {
 80        REPORT_ERROR_STATIC(ErrorManagement::FatalError, "Failed to listen in port = %d", port);
 81    }
 82
 83    if (ok) {
 84        GetTokensFromStream(sock);
 85        sock.Close();
 86    }
 87
 88    const char8 * const TEST_FILENAME = "BufferedStreamTestExample1.out";
 89    if (ok) {
 90        File f;
 91        ok = f.Open(TEST_FILENAME, BasicFile::FLAG_CREAT | BasicFile::ACCESS_MODE_W);
 92        if (ok) {
 93            f.Printf("%s", "FILE\nA1:B1:C1\nD2:E2:F2\nEND");
 94            f.Flush();
 95            f.Close();
 96        }
 97    }
 98    if (ok) {
 99        File f;
100        ok = f.Open(TEST_FILENAME, BasicFile::ACCESS_MODE_R);
101        if (ok) {
102            GetTokensFromStream(f);
103            f.Close();
104            Directory d(TEST_FILENAME);
105            d.Delete();
106        }
107    }
108    return 0;
109}

Start the application and, in another console, type echo -e "SOCKET\nA1:B1:C1\nD2:E2:F2\nEND" | nc -u 127.0.0.1 24680 -w0.

Instructions on how to compile and execute the example can be found here.