/*
 * Copyright (c) 2009-2012 Zmanda, Inc.  All Rights Reserved.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
 *
 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
 */

%perlcode %{

=head1 NAME

Amanda::Header - Amanda-specific headers prepended to dump files

=head1 SYNOPSIS

  # create a header
  my $hdr = Amanda::Header->new();
  $hdr->{type} = $Amanda::Header::F_DUMPFILE;
  $hdr->{name} = "localhost";
  $hdr->{disk} = "/home";

  # make a string suitable for use in a dumpfile (NUL-padded)
  my $block = $hdr->to_string(32768, 32768);

  # parse a string into a header
  $hdr = Amanda::Header->from_string($block);

  print "Working on: ", $hdr->summary(), "\n";

=head1 Header Objects

Note that, due to the vagaries of SWIG wrapping, headers actually have
class C<Amanda::Header::Header>.

The constructor creates a new, blank header, which will need at least
some of its attributes set before being used.  These are set just like
any hashref-based object:

 $hdr->{'dumplevel'} = 13;

To construct a new object from a bytestring (as read from the
beginning of a dumpfile), use

 Amanda::Header->from_string($data);

To convert a header object into a bytestring, use the C<to_string(min,
max)> method.  This method takes a minimum and maximum size.  If the
header is smaller than the minimum size, it is padded with NUL bytes;
if it would be larger than the maximum size, the method returns
C<undef>.

The C<summary> method returns a single-line summary of the header, with
no trailing newline.

As a debugging utility, the C<debug_dump> method dumps the contents of
the object to the debug log.

To compare a header to a list of dumpspecs (see L<Amanda::Cmdline>), use

  if ($hdr->matches_dumpspecs([@dumpspecs])) { ... }

which is really a call to C<Amanda::Cmdline::header_matches_dumpspecs>.

A header object has the following keys:

 type
 datestamp
 dumplevel
 compressed
 encrypted
 comp_suffix
 encrypt_suffix
 name               hostname (F_DUMPFILE) or label (F_TAPESTART)
 disk
 program
 application
 srvcompprog
 clntcompprog
 srv_encrypt
 clnt_encrypt
 recover_cmd
 uncompress_cmd
 decrypt_cmd
 srv_decrypt_opt
 clnt_decrypt_opt
 cont_filename
 dle_str
 is_partial
 partnum
 totalparts         (-1 == UNKNOWN)
 blocksize
 orig_size

C<type> is one of the following constants, which are availble for
import in the tag C<:constants>:

 F_UNKNOWN
 F_WEIRD
 F_TAPESTART
 F_TAPEEND
 F_DUMPFILE
 F_CONT_DUMPFILE
 F_SPLIT_DUMPFILE
 F_EMPTY
 F_NOOP

Some of the header fields are interrelated.  The following restrictions apply.

=over 4

=item *

C<comp_suffix> is set if and only if C<compressed> is true; the suffix "N" is
reserved and cannot be used.

=item *

C<encrypt_suffix> is set if and only if C<encrypted> is true; the suffix "N" is
reserved and cannot be used.

=item *

If C<totalparts> is not -1, then C<partnum> must be less than or equal to
C<totalparts>.  Neither parameter can be zero.  These parameters are only
recorded in a C<F_SPLIT_DUMPFILE> header.

=item *

The C<blocksize> is intended for the user's convenience only.  It is written to
the header string, but not parsed on return.  C<from_string> will always return
a header with blocksize=0.

=item *

Like C<blocksize>, C<recover_cmd>, C<uncompress_cmd> and C<decrypt_cmd> are
intended for the user's convenience noly.  The C<uncompress_cmd> and
C<decrypt_cmd>, if specified, must end with C<|> (the shell pipe character).
Neither can be nonempty unless C<recover_cmd> is also nonempty.  When parsing a
header with only two commands from a string, it is ambiguous whether the first
string is for decryption or uncompression, and this package assumes
uncompression.

=back

=cut


%}