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.

       o      EoiBuf():
              The default constructor initializes an empty buffer.

       o      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.

       o      std::string &buffer():
              A reference to the internal buffer is returned;

       o      size_t bufSize() const:
              The length (size) of the internal buffer is returned;

       o      void resize(size_t size):
              The size of the internal buffer is changed to size characters;

       o      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;

       o      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;

       o      unsigned char *ucharPtr():
              The  address of the first character of the internal buffer is returned as a pointer to an unsigned
              character;

       o      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:

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

       o      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).

       o      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();
              }

       o      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

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       Debian Bobcat project files:

       o      libbobcat6: debian package containing the shared library, changelog and copyright note;

       o      libbobcat-dev:  debian package containing the static library, headers, manual pages, and developer
              info;

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).

libbobcat-dev_6.07.01                               2005-2025                               FBB::EoiBuf(3bobcat)