# FBB::EoiBuf(3bobcat)

## End-Of-Information Base class
(libbobcat-dev_6.06.02)

## 2005-2024

## 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

  ## SEE ALSO

  bobcat(7), eoi(3bobcat)

  ## BUGS

  None Reported.

  ## BOBCAT PROJECT FILES

  - https://fbb-git.gitlab.io/bobcat/: gitlab project page;
  - bobcat_6.06.02-x.dsc: detached signature;
  - bobcat_6.06.02-x.tar.gz: source archive;
  - bobcat_6.06.02-x_i386.changes: change log;
  - libbobcat1_6.06.02-x_*.deb: debian package containing the libraries;
  - libbobcat1-dev_6.06.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).