NAME

       Paranoid::IO::FileMultiplexer::Block::StreamHeader - Stream Header Block

VERSION

       $Id: lib/Paranoid/IO/FileMultiplexer/Block/StreamHeader.pm, 2.10 2022/03/08 00:01:04
       acorliss Exp $

SYNOPSIS

           $obj = Paranoid::IO::FileMultiplexer::Block::StreamHeader->new($file,
                   $blockNo, $blockSize, $strmName);

           $name   = $obj->streamName;
           $max    = $obj->maxBATs;
           $eos    = $obj->eos;
           @bats   = $obj->bats;
           $rv     = $obj->full;

           $rv     = $obj->writeSig;
           $rv     = $obj->readSig;
           $rv     = $obj->writeEOS($pos);
           $pos    = $obj->readEOS;
           $rv     = $obj->validateBlocks;
           $rv     = $obj->writeBATs;
           $rv     = $obj->readBATs;
           $rv     = $obj->addBAT($bn);

DESCRIPTION

       This class is not meant to be used directly, but as part of the
       Paranoid::IO::FileMultiplexer functionality.  This provides functionality necessary for
       manipulation of the stream header block.

       This module does presume that whatever file it is being used on has already been opened in
       the appropriate mode, and that the Paranoid::IO flock stack has been enabled.  For the
       purposes of Paranoid::IO::FileMultiplexer, this is done in that class.

SUBROUTINES/METHODS

   new
           $obj = Paranoid::IO::FileMultiplexer::Block::StreamHeader->new($file,
                   $blockNo, $blockSize, $strmName);

       This creates a new instance of a stream header block object.  It requires the filename in
       order to retrieve the cached file handle from Paranoid::IO, the block number of the block,
       the size of the block, and the name of the stream.

       NOTE: creating an object does not automatically create the file and/or write a signature.
       That must be done using the methods below.

   streamName
           $name = $obj->streamName;

       This method returns the stream name.

   maxBATs
           $max = $obj->maxBATs;

       This method returns the maximum number of BATs supported by the stream.

   eos
           $eos = $obj->eos;

       This method returns the current EOS of the stream.  Note that this is just the last cached
       value, which may be out of sync with the contents of the file.

   bats
           %bats = $obj->bats;

       This method returns an array of BAT block numbers allocated to the stream.

   full
           $rv     = $obj->full;

       This method returns a boolean value denoting whether this streams's array of BAT blocks is
       at maximum capacity or not.

   writeSig
           $rv = $obj->writeSig;

       This method writes the stream header signature to disk, returning a boolean value denoting
       its success.  Note that the signature contains the file format, stream name, and current
       EOS position.  This does not include the allocated BAT block numbers.

   readSig
           $rv = $obj->readSig;

       This method reads the stream header signature from disk and performs basic validation that
       the information in it is acceptable.  It validates that the stream name matches what is
       expected and the block format is correct.

       If the method call was successful it will update the cached values in the object.  Note
       that this is only the signature values, not the BAT block numbers.

   writeEOS
           $rv = $obj->writeEOS($pos);

       This method writes the passed stream EOS position to disk, and returns a boolean value
       denoting success.

   readEOS
           $pos = $obj->readEOS;

       This method reads the stream EOS postiong from disk and returns it.  If there are any
       errors reading or extracting the value, it will return undef.

   validateEOS
           $rv = $obj->validateEOS;

       This method compares the cached EOS position to what's actually written in the file.  This
       is useful for determining whether an external process has potentially modified the file.

   writeBATs
           $rv = $obj->writeBATs;

       This method writes the BAT block numbers to the header block, and returns a boolean
       denoting success.

   readBATs
           $rv = $obj->readBATs;

       This method reads the BAT block numbers from the file, and returns a boolean value
       denoting success.  If the read is successful, this will update the cached BATs in the
       object.

   addBAT
           $rv = $obj->addBAT($bn);

       This method does some basic validation of the requested BAT, and if it passes, updates the
       BAT block number list on the disk.

DEPENDENCIES

       o   Fcntl

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::Data

       o   Paranoid::IO

       o   Paranoid::IO::FileMultiplexer::Block

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is free software.  Similar to Perl, you can redistribute it and/or modify it
       under the terms of either:

         a)     the GNU General Public License
                <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
                Free Software Foundation <http://www.fsf.org/>; either version 1
                <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
                <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
         b)     the Artistic License 2.0
                <https://opensource.org/licenses/Artistic-2.0>,

       subject to the following additional term:  No trademark rights to "Paranoid" have been or
       are conveyed under any of the above licenses.  However, "Paranoid" may be used fairly to
       describe this unmodified software, in good faith, but not as a trademark.

       (c) 2005 - 2021, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2021, Paranoid Inc.
       (www.paranoid.com)

perl v5.34.0                              Paranoid::IO::FileMultiplexer::Block::StreamHeader(3pm)