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