git.gag.com Git - debian/amanda/blob - perl/Amanda/Archive.pm

   1 # This file was automatically generated by SWIG (http://www.swig.org).
   2 # Version 1.3.39
   3 #
   4 # Do not make changes to this file unless you know what you are doing--modify
   5 # the SWIG interface file instead.
   6
   7 package Amanda::Archive;
   8 use base qw(Exporter);
   9 use base qw(DynaLoader);
  10 package Amanda::Archivec;
  11 bootstrap Amanda::Archive;
  12 package Amanda::Archive;
  13 @EXPORT = qw();
  14
  15 # ---------- BASE METHODS -------------
  16
  17 package Amanda::Archive;
  18
  19 sub TIEHASH {
  20     my ($classname,$obj) = @_;
  21     return bless $obj, $classname;
  22 }
  23
  24 sub CLEAR { }
  25
  26 sub FIRSTKEY { }
  27
  28 sub NEXTKEY { }
  29
  30 sub FETCH {
  31     my ($self,$field) = @_;
  32     my $member_func = "swig_${field}_get";
  33     $self->$member_func();
  34 }
  35
  36 sub STORE {
  37     my ($self,$field,$newval) = @_;
  38     my $member_func = "swig_${field}_set";
  39     $self->$member_func($newval);
  40 }
  41
  42 sub this {
  43     my $ptr = shift;
  44     return tied(%$ptr);
  45 }
  46
  47
  48 # ------- FUNCTION WRAPPERS --------
  49
  50 package Amanda::Archive;
  51
  52 *amar_new = *Amanda::Archivec::amar_new;
  53 *amar_close = *Amanda::Archivec::amar_close;
  54 *amar_new_file = *Amanda::Archivec::amar_new_file;
  55 *amar_file_close = *Amanda::Archivec::amar_file_close;
  56 *amar_new_attr = *Amanda::Archivec::amar_new_attr;
  57 *amar_attr_close = *Amanda::Archivec::amar_attr_close;
  58 *amar_attr_add_data_buffer = *Amanda::Archivec::amar_attr_add_data_buffer;
  59 *amar_attr_add_data_fd = *Amanda::Archivec::amar_attr_add_data_fd;
  60 *amar_read = *Amanda::Archivec::amar_read;
  61
  62 # ------- VARIABLE STUBS --------
  63
  64 package Amanda::Archive;
  65
  66
  67 @EXPORT_OK = ();
  68 %EXPORT_TAGS = ();
  69
  70 =head1 NAME
  71
  72 Amanda::Archive - Perl access to the  amanda archive library
  73
  74 =head1 SYNOPSIS
  75
  76   use Amanda::Archive
  77
  78   # Write to the file descriptor $fd, and add /etc/hosts to it
  79   my $archive = Amanda::Archive->new($fd, ">");
  80   my $file = $archive->new_file("/etc/hosts");
  81   my $attr = $file->new_attr(16);
  82   open(my $fh, "<", "/etc/hosts");
  83   $attr->add_data_fd(fileno($fh), 1);
  84   $file->close();
  85   $archive->close();
  86
  87   # Read from an archive
  88   my $archive = Amanda::Archive->new($fd, "<");
  89   $ar->read(
  90       file_start => sub {
  91           my ($user_data, $filenum, $filename) = @_;
  92           # ...
  93           return "foo"; # this becomes $file_data
  94       },
  95       file_finish => sub {
  96           my ($user_data, $file_data, $filenum, $truncated) = @_;
  97           # ...
  98       },
  99       21 => [ 32768,    # buffer into 32k chunks
 100               sub {
 101                   my ($user_data, $filenum, $file_data, $attrid,
 102                       $attr_data, $data, $eoa, $truncated) = @_;
 103                   return "pants"; # becomes the new $attr_data for
 104                                   # any subsequent fragments
 105               } ],
 106       0 => sub {        # note no buffering here; attrid 0 is "default"
 107           my ($user_data, $filenum, $file_data, $attrid,
 108               $attr_data, $data, $eoa, $truncated) = @_;
 109           return "shorts"; # becomes the new $attr_data for
 110                            # any subsequent fragments
 111       },
 112       user_data => [ "mydata" ], # sent to all callbacks
 113   );
 114
 115 =head1 WRITING
 116
 117 =head2 Amanda::Archive::Archive Objects
 118
 119 Note that C<Amanda::Archive->new> and C<Amanda::Archive::Archive->new> are
 120 equivalent.
 121
 122 =over
 123
 124 =item C<new($fd, $mode)>
 125
 126 Create a new archive for reading ("<") or writing (">") from or to file
 127 descriptor C<$fd>.
 128
 129 =item C<new_file($filename, $want_posn)>
 130
 131 Create a new C<Amanda::Archive::File> object with the given filename (writing
 132 only).  Equivalent to
 133
 134   Amanda::Archive::File->new($archive, $filename, $want_posn);
 135
 136 if C<$want_posn> is false, then this method returns a new
 137 C<Amanda::Archive::File> object.  If C<$want_posn> is true, then it returns
 138 C<($file, $posn)> where C<$file> is the object and C<$posn> is the offset into
 139 the datastream at which this file begins.  This offset can be stored in an
 140 index and used later to seek into the file.
 141
 142 =item C<read(..)>
 143
 144 See I<READING>, below.
 145
 146 =item C<close()>
 147
 148 Flush all buffers and close this archive. This does not close the file descriptor.
 149
 150 =back
 151
 152 =head2 Amanda::Archive::File Objects
 153
 154 =over
 155
 156 =item C<new($archive, $filename, $want_posn)>
 157
 158 Create a new file in the given archive.  See C<Amanda::Archive::Archive::new_file>, above.
 159
 160 =item C<new_attr($attrid)>
 161
 162 Create a new C<Amanda::Archive::Attribute> object.  Equivalent to
 163
 164   Amanda::Archive::Attr->new($file, $attrid);
 165
 166 =item C<close()>
 167
 168 Close this file, writing an EOF record.
 169
 170 =back
 171
 172 =head2 Amanda::Archive::Attribute Objects
 173
 174 =over
 175
 176 =item C<add_data($data, $eoa)>
 177
 178 Add C<$data> to this attribute, adding an EOA (end-of-attribute) bit if C<$eoa> is true.
 179
 180 =item C<add_data_fd($fd, $eoa)>
 181
 182 Copy data from C<$fd> to this attribute, adding an EOA (end-of-attribute) bit if C<$eoa> is true.
 183
 184 =item C<close()>
 185
 186 Close this attribute, adding an EOA bit if none has been written already.
 187
 188 =back
 189
 190 =head1 READING
 191
 192 The C<Amanda::Archive::Archive> method C<read()> handles reading archives via a callback mechanism.  It takes its arguments in hash form, with the following keys:
 193
 194     file_start => sub {
 195         my ($user_data, $filenum, $filename) = @_;
 196         # ..
 197     },
 198
 199 C<file_start> gives a sub which is called for every file in the archive.  It
 200 can return an arbitrary value which will become the C<$file_data> for
 201 subsequent callbacks in this file, or the string "IGNORE" which will cause the
 202 reader to ignore all data for this file.  In this case, no other callbacks will
 203 be made for the file (not even C<file_finish>).
 204
 205     file_finish => sub {
 206         my ($user_data, $file_data, $filenum, $truncated) = @_;
 207         # ..
 208     },
 209
 210 C<file_finish> gives a sub which is called when an EOF record appears.
 211 C<$file_data> comes from the return value of the C<file_start> callback.
 212 C<$truncated> is true if the file may be missing data (e.g., when an early EOF
 213 is detected).
 214
 215     user_data => $my_object,
 216
 217 C<user_data> gives an arbitrary value which is passed to each callback as C<$user_data>.
 218
 219     13 => sub {
 220         my ($user_data, $filenum, $file_data, $attrid,
 221             $attr_data, $data, $eoa, $truncated) = @_;
 222         # ...
 223     },
 224     19 => [ 10240, sub { ... } ],
 225
 226 Any numeric key is treated as an attribute ID, and specifies the handling for
 227 that attribute.  Attribute ID zero is treated as a wildcard, and will match any
 228 attribute without an explicit handler.  The handler can be specified as a sub
 229 (as for attribute ID 13 in the example above) or as an arrayref C<[$minsize,
 230 $sub]>.  In the latter case, the sub is only called when at least C<$minsize>
 231 bytes of data are available for the attribute, or at the end of the attribute
 232 data.
 233
 234 The parameters to the callback include C<$file_data>, the value returned from
 235 C<file_start>, and C<$attr_data>, which is the return value of the last
 236 invocation of this sub for this attribute.  If this is the last fragment of
 237 data for this attribute, then C<$eoa> is true.  The meaning of C<$truncated>
 238 is similar to that in C<file_finish>.
 239
 240 =head2 EXAMPLE
 241
 242     sub read_to_files {
 243         my ($arch_fh, $basedir) = @_;
 244
 245         my $arch = Amanda::Archive->new(fileno($arch_fh), "<");
 246         $arch->read(
 247             file_start => sub {
 248                 my ($user_data, $filenum, $filename) = @_;
 249                 return "$basedir/$filenum"; # becomes $file_data
 250             },
 251             0 => [ 32768, sub {
 252                 my ($user_data, $filenum, $file_data, $attrid,
 253                     $attr_data, $data, $eoa, $truncated) = @_;
 254                 warn("file $filename attribute $attrid is truncated")
 255                     if ($truncated);
 256                 # store the open filehandle in $attr_data
 257                 if (!$attr_data) {
 258                     open($attr_data, "$file_data.$attrid", ">")
 259                         or die("open: $!");
 260                 }
 261                 print $attr_data $data;
 262                 if ($eoa) {
 263                     close($attr_data);
 264                 }
 265                 return $attr_data;
 266             },
 267         );
 268     }
 269
 270 =cut
 271
 272 package Amanda::Archive;
 273
 274 # Expose the Archive constructor at Amanda::Archive->new
 275 sub new {
 276     my $pkg = shift;
 277     Amanda::Archive::Archive->new(@_);
 278 }
 279
 280 package Amanda::Archive::Archive;
 281
 282 sub new {
 283     my ($class, $fd, $mode) = @_;
 284     my $arch = Amanda::Archive::amar_new($fd, $mode);
 285     return bless (\$arch, $class);
 286 }
 287
 288 sub close {
 289     my $self = shift;
 290     if ($$self) {
 291         Amanda::Archive::amar_close($$self);
 292         $$self = undef;
 293     }
 294 }
 295
 296 sub DESTROY {
 297     my $self = shift;
 298     $self->close();
 299 }
 300
 301 sub new_file {
 302     my ($self, $filename, $want_offset) = @_;
 303     return Amanda::Archive::File->new($self, $filename, $want_offset);
 304 }
 305
 306 sub Amanda::Archive::Archive::read {
 307     my $self = shift;
 308     die "Archive is not open" unless ($$self);
 309     # pass a hashref to the C code
 310     my %h = @_;
 311     Amanda::Archive::amar_read($$self, \%h);
 312 }
 313
 314 package Amanda::Archive::File;
 315
 316 sub new {
 317     my ($class, $arch, $filename, $want_offset) = @_;
 318     die "Archive is not open" unless ($$arch);
 319     if ($want_offset) {
 320         # note that posn is returned first by the SWIG wrapper
 321         my ($file, $posn) = Amanda::Archive::amar_new_file($$arch, $filename, $want_offset);
 322         return (bless([ $file, $arch ], $class), $posn);
 323     } else {
 324         my $file = Amanda::Archive::amar_new_file($$arch, $filename, $want_offset);
 325         return bless([ $file, $arch ], $class);
 326     }
 327 }
 328
 329 sub close {
 330     my $self = shift;
 331     if ($self->[0]) {
 332         Amanda::Archive::amar_file_close($self->[0]);
 333         $self->[0] = undef;
 334     }
 335 }
 336
 337 sub DESTROY {
 338     my $self = shift;
 339     $self->close();
 340 }
 341
 342 sub new_attr {
 343     my ($self, $attrid) = @_;
 344     return Amanda::Archive::Attr->new($self, $attrid);
 345 }
 346
 347 package Amanda::Archive::Attr;
 348
 349 sub new {
 350     my ($class, $file, $attrid) = @_;
 351     die "File is not open" unless ($file->[0]);
 352     my $attr = Amanda::Archive::amar_new_attr($file->[0], $attrid);
 353     return bless ([$attr, $file], $class);
 354 }
 355
 356 sub close {
 357     my $self = shift;
 358     if ($self->[0]) {
 359         Amanda::Archive::amar_attr_close($self->[0]);
 360         $self->[0] = undef;
 361     }
 362 }
 363
 364 sub DESTROY {
 365     my $self = shift;
 366     $self->close();
 367 }
 368
 369 sub add_data {
 370     my ($self, $data, $eoa) = @_;
 371     die "Attr is not open" unless ($self->[0]);
 372     Amanda::Archive::amar_attr_add_data_buffer($self->[0], $data, $eoa);
 373 }
 374
 375 sub add_data_fd {
 376     my ($self, $fd, $eoa) = @_;
 377     die "Attr is not open" unless ($self->[0]);
 378     return Amanda::Archive::amar_attr_add_data_fd($self->[0], $fd, $eoa);
 379 }
 380 1;