.TH "FBB::EoiBuf" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.03\&.02" "End\-Of\-Information Base class"

.PP 
.SH "NAME"
FBB::EoiBuf \- std::streambuf class offering an eoi manipulator
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/eoibuf>\fP
.br 
Linking option: \fI\-lbobcat\fP
.PP 
.SH "DESCRIPTION"
The class \fIEoiBuf\fP inherits from \fIEoi\fP and may therefore be
used as a base class of classes specializing \fIstd::streambuf\fP\&. It also
provides a configurable character buffer for storing characters received from
their devices\&. Often, when deriving classes from \fIstd::streambuf\fP the
derived classes must implement storage to and retrieval from a character
buffer\&. By deriving from \fIEoiBuf\fP buffer\-handling is automatically
provided: it contains a (resizable) character buffer, and offers a \fIsetp\fP
member as well as a \fIsetg\fP member that can be used to specify the index rage
of the buffer from which extractions receive characters\&. Also, when overriding
its base class\(cq\&s \fIeoi_\fP member it can be used to signal the end of input
inserted into \fIstd::ostream\fP classes using \fIEoiBuf\fP objects as
\fIstd::streambuf\fP objects\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\fIFBB::Eoi\fP (and thus from: \fIstd::streambuf\fP)
.PP 
.SH "PROTECTED CONSTRUCTOR"

.PP 
Analogously to \fIstd::streambuf\fP only protected constructors are
available\&.
.PP 
.IP o 
\fBEoiBuf()\fP:
.br 
The default constructor initializes an empty buffer\&.
.IP 
.IP o 
\fBEoiBuf(size_t size)\fP:
.br 
This initializes an empty buffer of a predefined size of \fIsize\fP
characters \&.

.PP 
Note that there\(cq\&s no inherent limit to the size of the internal buffer: its
size can always be enlarged or reduced\&.
.PP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "PROTECTED MEMBER FUNCTIONS"

.PP 
All members of \fIstd:streambuf\fP and \fIEoi\fP are available, as
\fBFBB::EoiBuf\fP inherits from these classes\&.
.PP 
.IP o 
\fBstd::string &buffer()\fP:
.br 
A reference to the internal buffer is returned;
.IP 
.IP o 
\fBsize_t bufSize() const\fP:
.br 
The length (size) of the internal buffer is returned;
.IP 
.IP o 
\fBvoid resize(size_t size)\fP:
.br 
The size of the internal buffer is changed to \fIsize\fP characters;
.IP 
.IP o 
\fBvoid setg(unsigned next, unsigned beyond)\fP:
.br 
The \fIstreambuf::eback\fP member returns the address of the internal
buffer\(cq\&s first character, \fIstreambuf::gptr\fP returns the address of
the internal buffer\(cq\&s \fInext\fP character, \fIstreambuf::egptr\fP returns
the the address of the internal buffer\(cq\&s \fIbeyond\fP character;
.IP 
.IP o 
\fBvoid setp()\fP:
.br 
The \fIstreambuf::pbase\fP and \fIpptr\fP members return the address of
the internal buffer\(cq\&s first character, \fIstreambuf::epptr\fP returns
the address immediately beyond the internal buffer\(cq\&s last character;
.IP 
.IP o 
\fBunsigned char *ucharPtr()\fP:
.br 
The address of the first character of the internal buffer is returned
as a pointer to an unsigned character;
.IP 
.IP o 
\fBunsigned char const *ucharPtr() const\fP:
.br 
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\&.

.PP 
.SH "PROTECTED STATIC MEMBER FUNCTIONS"

.PP 
The following two static members are provided as convenient functions for
derived classes to convert the address of the first character of
\fIstd::string\fP objects to pointers to unsigned characters:
.PP 
.IP o 
\fBunsigned char *ucharPtr(std::string &str)\fP:
.br 
The address of the first character of \fIstr\fP is returned as a pointer
to an unsigned character;
.PP 
.IP o 
\fBunsigned char const *ucharPtr(std::string const &str) const\fP:
.br 
Same as the previous member, but this time the address of the first
character of \fIstr\fP is returned as a pointer to an immutable unsigned
character\&.
.PP 
.SH "EXAMPLE"
The following two functions are defined in the (internally used only)
class \fIFBB::OSymCryptBase\fP, which is the base class of
\fBosymcryptstreambuf\fP(3bobcat)\&.
.IP o 
\fIevpUpdate\fP updates the ongoing encryption or decryption, e\&.g\&., using
the openssl function \fIEVP_EncryptUpdate\fP, using \fIucharPtr\fP to
access characters currently in \fIEoiBuf\(cq\&s\fP buffer:
.IP 
.nf 
#include \(dq\&osymcryptbase\&.ih\(dq\&

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{} << \(dq\&EVP_{En,De}cryptUpdate failed\(dq\&;

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

    setp();
}

.fi 

.IP 
.IP o 
\fIeoi_\fP overrides \fIFBB::Eoi::eoi_()\fP function, preventing new
information from being inserted into the \fIFBB::OSymCryptBase\fP object
(and thus from being inserted into its \fIFBB::OSymCryptStreambuf\fP
derived class):
.IP 
.nf 
#include \(dq\&osymcryptbase\&.ih\(dq\&

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

}

.fi 


.PP 
.SH "FILES"
\fIbobcat/eoibuf\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBeoi\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_6\&.03\&.02\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.03\&.02\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.03\&.02\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.03\&.02\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.03\&.02\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP