FBB::EoiBuf(3bobcat)

End-Of-Information Base class
(libbobcat-dev_6.02.02)

2005-2022

NAME

FBB::EoiBuf - std::streambuf class offering an eoi manipulator

SYNOPSIS

#include <bobcat/eoibuf>
Linking option: -lbobcat

DESCRIPTION

The class EoiBuf inherits from Eoi and may therefore be used as a base class of classes specializing std::streambuf. It also provides a configurable character buffer for storing characters received from their devices. Often, when deriving classes from std::streambuf the derived classes must implement storage to and retrieval from a character buffer. By deriving from EoiBuf buffer-handling is automatically provided: it contains a (resizable) character buffer, and offers a setp member as well as a setg member that can be used to specify the index rage of the buffer from which extractions receive characters. Also, when overriding its base class's eoi_ member it can be used to signal the end of input inserted into std::ostream classes using EoiBuf objects as std::streambuf objects.

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

FBB::Eoi (and thus from: std::streambuf)

PROTECTED CONSTRUCTOR

Analogously to std::streambuf only protected constructors are available.

EoiBuf():
The default constructor initializes an empty buffer.
EoiBuf(size_t size):
This initializes an empty buffer of a predefined size of size characters .

Note that there's no inherent limit to the size of the internal buffer: its size can always be enlarged or reduced.

Copy and move constructors (and assignment operators) are not available.

PROTECTED MEMBER FUNCTIONS

All members of std:streambuf and Eoi are available, as FBB::EoiBuf inherits from these classes.

std::string &buffer():
A reference to the internal buffer is returned;
size_t bufSize() const:
The length (size) of the internal buffer is returned;
void resize(size_t size):
The size of the internal buffer is changed to size characters;
void setg(unsigned next, unsigned beyond):
The streambuf::eback member returns the address of the internal buffer's first character, streambuf::gptr returns the address of the internal buffer's next character, streambuf::egptr returns the the address of the internal buffer's beyond character;
void setp():
The streambuf::pbase and pptr members return the address of the internal buffer's first character, streambuf::epptr returns the address immediately beyond the internal buffer's last character;
unsigned char *ucharPtr():
The address of the first character of the internal buffer is returned as a pointer to an unsigned character;
unsigned char const *ucharPtr() const:
Same as the previous member, but this time the address of the first character of the internal buffer is returned as a pointer to an immutable unsigned character.

PROTECTED STATIC MEMBER FUNCTIONS

The following two static members are provided as convenient functions for derived classes to convert the address of the first character of std::string objects to pointers to unsigned characters:

unsigned char *ucharPtr(std::string &str):
The address of the first character of str is returned as a pointer to an unsigned character;

unsigned char const *ucharPtr(std::string const &str) const:
Same as the previous member, but this time the address of the first character of str is returned as a pointer to an immutable unsigned character.

EXAMPLE

The following two functions are defined in the (internally used only) class FBB::OSymCryptBase, which is the base class of osymcryptstreambuf(3bobcat).

evpUpdate updates the ongoing encryption or decryption, e.g., using the openssl function EVP_EncryptUpdate, using ucharPtr to access characters currently in EoiBuf's buffer:

#include "osymcryptbase.ih"

void OSymCryptBase::evpUpdate()
{
    size_t inBufRead = pptr() - pbase();    // # read chars

    checkOutBufSize(inBufRead);

    int nOutputChars;

    if (not ((*d_evpUpdate)(                // en/decrypt the bytes in d_inBuf
            ctx(),
            uOutBuf(), &nOutputChars,
            ucharPtr(), inBufRead
        ))
    )
        throw Exception{} << "EVP_{En,De}cryptUpdate failed";

    d_outStream.write(outBuf(), nOutputChars);      // write the processed
                                                    // chars to d_outSteam

    setp();
}

eoi_ overrides FBB::Eoi::eoi_() function, preventing new information from being inserted into the FBB::OSymCryptBase object (and thus from being inserted into its FBB::OSymCryptStreambuf derived class):

#include "osymcryptbase.ih"

void OSymCryptBase::eoi_()
{
    if (d_eoi)
        return;

    evpUpdate();                // process available chars in the input
    d_eoi = true;
    resize(0);                  // clear the input buffer
    evpUpdate();                // update an empty buffer

}

FILES

bobcat/eoibuf - defines the class interface

BUGS

None Reported.

BOBCAT PROJECT FILES

https://fbb-git.gitlab.io/bobcat/: gitlab project page;
bobcat_6.02.02-x.dsc: detached signature;
bobcat_6.02.02-x.tar.gz: source archive;
bobcat_6.02.02-x_i386.changes: change log;
libbobcat1_6.02.02-x_*.deb: debian package containing the libraries;
libbobcat1-dev_6.02.02-x_*.deb: debian package containing the libraries, headers and manual pages;

BOBCAT

Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT

This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl).