1 # This file was automatically generated by SWIG (http://www.swig.org).
4 # Don't modify this file, modify the SWIG interface instead.
9 @ISA = qw(Exporter DynaLoader);
10 require Amanda::MainLoop;
11 require Amanda::Device;
12 require Amanda::Types;
13 package Amanda::Xferc;
14 bootstrap Amanda::Xfer;
18 # ---------- BASE METHODS -------------
23 my ($classname,$obj) = @_;
24 return bless $obj, $classname;
34 my ($self,$field) = @_;
35 my $member_func = "swig_${field}_get";
36 $self->$member_func();
40 my ($self,$field,$newval) = @_;
41 my $member_func = "swig_${field}_set";
42 $self->$member_func($newval);
51 # ------- FUNCTION WRAPPERS --------
55 *xfer_new = *Amanda::Xferc::xfer_new;
56 *xfer_unref = *Amanda::Xferc::xfer_unref;
57 *xfer_get_status = *Amanda::Xferc::xfer_get_status;
58 *xfer_repr = *Amanda::Xferc::xfer_repr;
59 *xfer_start = *Amanda::Xferc::xfer_start;
60 *xfer_cancel = *Amanda::Xferc::xfer_cancel;
61 *xfer_element_unref = *Amanda::Xferc::xfer_element_unref;
62 *xfer_element_repr = *Amanda::Xferc::xfer_element_repr;
63 *xfer_source_device = *Amanda::Xferc::xfer_source_device;
64 *xfer_source_random = *Amanda::Xferc::xfer_source_random;
65 *xfer_source_pattern = *Amanda::Xferc::xfer_source_pattern;
66 *xfer_source_fd = *Amanda::Xferc::xfer_source_fd;
67 *xfer_filter_xor = *Amanda::Xferc::xfer_filter_xor;
68 *xfer_dest_device = *Amanda::Xferc::xfer_dest_device;
69 *xfer_dest_null = *Amanda::Xferc::xfer_dest_null;
70 *xfer_dest_fd = *Amanda::Xferc::xfer_dest_fd;
71 *xfer_get_amglue_source = *Amanda::Xferc::xfer_get_amglue_source;
73 # ------- VARIABLE STUBS --------
77 *XFER_INIT = *Amanda::Xferc::XFER_INIT;
78 *XFER_START = *Amanda::Xferc::XFER_START;
79 *XFER_RUNNING = *Amanda::Xferc::XFER_RUNNING;
80 *XFER_DONE = *Amanda::Xferc::XFER_DONE;
81 *XMSG_INFO = *Amanda::Xferc::XMSG_INFO;
82 *XMSG_ERROR = *Amanda::Xferc::XMSG_ERROR;
83 *XMSG_DONE = *Amanda::Xferc::XMSG_DONE;
84 *XMSG_CANCEL = *Amanda::Xferc::XMSG_CANCEL;
91 Amanda::Xfer - the transfer architecture
96 use Amanda::Xfer qw( :constants );
99 my $infd = POSIX::open("input", POSIX::O_RDONLY, 0);
100 my $outfd = POSIX::open("output", POSIX::O_CREAT|POSIX::O_WRONLY, 0640);
101 my $xfer = Amanda::Xfer->new([
102 Amanda::Xfer::Source::Fd->new($infd),
103 Amanda::Xfer::Dest::Fd->new($outfd)
105 $xfer->get_source()->set_callback(sub {
106 my ($src, $xmsg, $xfer) = @_;
107 print "Message from $xfer: $xmsg\n"; # use stringify operations
108 if ($xfer->get_status() == $XFER_DONE) {
110 Amanda::MainLoop::quit();
114 Amanda::MainLoop::run();
116 See L<http://wiki.zmanda.com/index.php/XFA> for background on the transfer
123 =head1 Amanda::Xfer Objects
125 A new transfer is created with C<< Amanda::Xfer->new() >>, which takes an arrayref
126 giving the transfer elements which should compose the transfer.
128 The resulting object has the following methods:
134 Get the L<Amanda::MainLoop> event source through which messages will be
135 delivered for this transfer. Use its C<set_callback> method to connect a perl
136 sub for processing events. You I<must> C<release> the source when the
137 transfer is complete!
139 The callback from this event source receives three arguments: the event source,
140 the message, and a reference to the controlling transfer. See the description of
141 C<Amanda::Xfer::Msg>, below, for details.
145 Start this transfer. Processing takes place asynchronously, and messages will
146 begin queueing up immediately.
150 Stop transferring data. The transfer will send an C<XMSG_CANCEL>, "drain" any
151 buffered data as best it can, and then complete normally with an C<XMSG_DONE>.
155 Get the transfer's status. The result will be one of C<$XFER_INIT>,
156 C<$XFER_START>, C<$XFER_RUNNING>, or C<$XFER_DONE>. These symbols are
157 available for import with the tag C<:constants>.
161 Return a string representation of this transfer, suitable for use in debugging
162 messages. This method is automatically invoked when a transfer is interpolated
164 print "Starting $xfer\n";
168 =head1 Amanda::Xfer::Element objects
170 The individual transfer elements that compose a transfer are instances of
171 subclasses of Amanda::Xfer::Element. All such objects have a C<repr()> method,
172 similar to that for transfers, and support a similar kind of string
175 Note that the names of these classes contain the words "Source", "Filter", and
176 "Dest". This is merely suggestive of their intended purpose -- there are no
177 such abstract classes.
179 =head2 Transfer Sources
181 =head3 Amanda::Xfer::Source::Device
183 Amanda::Xfer::Source::Device->new($device);
185 This source reads data from a device. The device should already be queued up
186 for reading (C<$device->seek_file(..)>). The element will read until the end
189 =head3 Amanda::Xfer::Source::Fd
191 Amanda::Xfer::Source::Fd->new(fileno($fh));
193 This source reads data from a file descriptor. It reads until EOF, but does
194 not close the descriptor. Be careful not to let Perl close the file for you!
196 =head3 Amanda::Xfer::Source::Random
198 Amanda::Xfer::Source::Random->new($length, $seed);
200 This source provides I<length> bytes of random data (or an unlimited amount
201 of data if I<length> is zero). C<$seed> is the seed used
202 to generate the random numbers; this seed can be used in a destination to
203 check for correct output.
205 =head3 Amanda::Xfer::Source::Pattern
207 Amanda::Xfer::Source::Pattern->new($length, $pattern);
209 This source provides I<length> bytes containing copies of
210 I<pattern>. If I<length> is zero, the source provides an unlimited
213 =head2 Transfer Filters
215 =head3 Amanda::Xfer::Filter:Xor
217 Amanda::Xfer::Filter::Xor->new($key);
219 This filter applies a bytewise XOR operation to the data flowing through it.
221 =head2 Transfer Destinations
223 =head3 Amanda::Xfer::Dest::Device
225 Amanda::Xfer::Dest::Device->new($device, $max_memory);
227 This source writes data to a device. The device should already be queued up
228 for writing (C<$device->start_file(..)>). No more than C<$max_memory> will be
229 used for buffers. Use zero for the default buffer size. On completion of the
230 transfer, the file will be finished.
232 =head3 Amanda::Xfer::Dest::Fd
234 Amanda::Xfer::Dest::Fd->new(fileno($fh));
236 This destination writes data to a file descriptor. The file is not closed
237 after the transfer is completed. Be careful not to let Perl close the file
240 =head3 Amanda::Xfer::Dest::Null
242 Amanda::Xfer::Dest::Null->new($seed);
244 This destination discards the data it receives. If C<$seed> is nonzero, then
245 the element will validate that it receives the data that
246 C<Amanda::Xfer::Source::Random> produced with the same seed. No validation is
247 performed if C<$seed> is zero.
249 =head1 Amanda::Xfer::Msg objects
251 Messages are simple hashrefs, with a few convenience methods. Like transfers,
252 they have a C<repr()> method that formats the message nicely, and is available
253 through string interpolation:
254 print "Received message $msg\n";
256 Every message has the following keys:
262 The message type -- one of the C<xmsg_type> constants available from the import
267 The transfer element that sent the message.
271 The version of the message. This is used to support extensibility of the protocol.
275 The canonical description of the message types and keys is in C<xfer-src/xmsg.h>, and is
280 push @EXPORT_OK, qw(xfer_status_to_string);
281 push @{$EXPORT_TAGS{"xfer_status"}}, qw(xfer_status_to_string);
283 my %_xfer_status_VALUES;
284 #Convert an enum value to a single string
285 sub xfer_status_to_string {
288 for my $k (keys %_xfer_status_VALUES) {
289 my $v = $_xfer_status_VALUES{$k};
291 #is this a matching flag?
292 if ($enumval == $v) {
297 #default, just return the number
301 push @EXPORT_OK, qw($XFER_INIT);
302 push @{$EXPORT_TAGS{"xfer_status"}}, qw($XFER_INIT);
304 $_xfer_status_VALUES{"XFER_INIT"} = $XFER_INIT;
306 push @EXPORT_OK, qw($XFER_START);
307 push @{$EXPORT_TAGS{"xfer_status"}}, qw($XFER_START);
309 $_xfer_status_VALUES{"XFER_START"} = $XFER_START;
311 push @EXPORT_OK, qw($XFER_RUNNING);
312 push @{$EXPORT_TAGS{"xfer_status"}}, qw($XFER_RUNNING);
314 $_xfer_status_VALUES{"XFER_RUNNING"} = $XFER_RUNNING;
316 push @EXPORT_OK, qw($XFER_DONE);
317 push @{$EXPORT_TAGS{"xfer_status"}}, qw($XFER_DONE);
319 $_xfer_status_VALUES{"XFER_DONE"} = $XFER_DONE;
321 #copy symbols in xfer_status to constants
322 push @{$EXPORT_TAGS{"constants"}}, @{$EXPORT_TAGS{"xfer_status"}};
324 push @EXPORT_OK, qw(xmsg_type_to_string);
325 push @{$EXPORT_TAGS{"xmsg_type"}}, qw(xmsg_type_to_string);
327 my %_xmsg_type_VALUES;
328 #Convert an enum value to a single string
329 sub xmsg_type_to_string {
332 for my $k (keys %_xmsg_type_VALUES) {
333 my $v = $_xmsg_type_VALUES{$k};
335 #is this a matching flag?
336 if ($enumval == $v) {
341 #default, just return the number
345 push @EXPORT_OK, qw($XMSG_INFO);
346 push @{$EXPORT_TAGS{"xmsg_type"}}, qw($XMSG_INFO);
348 $_xmsg_type_VALUES{"XMSG_INFO"} = $XMSG_INFO;
350 push @EXPORT_OK, qw($XMSG_ERROR);
351 push @{$EXPORT_TAGS{"xmsg_type"}}, qw($XMSG_ERROR);
353 $_xmsg_type_VALUES{"XMSG_ERROR"} = $XMSG_ERROR;
355 push @EXPORT_OK, qw($XMSG_DONE);
356 push @{$EXPORT_TAGS{"xmsg_type"}}, qw($XMSG_DONE);
358 $_xmsg_type_VALUES{"XMSG_DONE"} = $XMSG_DONE;
360 push @EXPORT_OK, qw($XMSG_CANCEL);
361 push @{$EXPORT_TAGS{"xmsg_type"}}, qw($XMSG_CANCEL);
363 $_xmsg_type_VALUES{"XMSG_CANCEL"} = $XMSG_CANCEL;
365 #copy symbols in xmsg_type to constants
366 push @{$EXPORT_TAGS{"constants"}}, @{$EXPORT_TAGS{"xmsg_type"}};
368 package Amanda::Xfer::Xfer;
374 Amanda::Xfer::xfer_new(@_);
376 *DESTROY = *Amanda::Xfer::xfer_unref;
377 use overload '""' => sub { $_[0]->repr(); };
378 *repr = *Amanda::Xfer::xfer_repr;
379 *get_status = *Amanda::Xfer::xfer_get_status;
380 *get_source = *Amanda::Xfer::xfer_get_amglue_source;
381 *start = *Amanda::Xfer::xfer_start;
382 *cancel = *Amanda::Xfer::xfer_cancel;
384 package Amanda::Xfer::Element;
385 *DESTROY = *Amanda::Xfer::xfer_element_unref;
386 use overload '""' => sub { $_[0]->repr(); };
387 *repr = *Amanda::Xfer::xfer_element_repr;
389 package Amanda::Xfer::Element::Glue;
392 @ISA = qw( Amanda::Xfer::Element );
394 package Amanda::Xfer::Source::Device;
397 @ISA = qw( Amanda::Xfer::Element );
403 Amanda::Xfer::xfer_source_device(@_);
406 package Amanda::Xfer::Source::Fd;
409 @ISA = qw( Amanda::Xfer::Element );
415 Amanda::Xfer::xfer_source_fd(@_);
418 package Amanda::Xfer::Source::Random;
421 @ISA = qw( Amanda::Xfer::Element );
427 Amanda::Xfer::xfer_source_random(@_);
430 package Amanda::Xfer::Source::Pattern;
433 @ISA = qw( Amanda::Xfer::Element );
439 Amanda::Xfer::xfer_source_pattern(@_);
442 package Amanda::Xfer::Filter::Xor;
445 @ISA = qw( Amanda::Xfer::Element );
451 Amanda::Xfer::xfer_filter_xor(@_);
454 package Amanda::Xfer::Dest::Device;
457 @ISA = qw( Amanda::Xfer::Element );
463 Amanda::Xfer::xfer_dest_device(@_);
466 package Amanda::Xfer::Dest::Fd;
469 @ISA = qw( Amanda::Xfer::Element );
475 Amanda::Xfer::xfer_dest_fd(@_);
478 package Amanda::Xfer::Dest::Null;
481 @ISA = qw( Amanda::Xfer::Element );
487 Amanda::Xfer::xfer_dest_null(@_);
490 package Amanda::Xfer::Msg;
493 use overload '""' => sub { $_[0]->repr(); };
497 local $Data::Dumper::Indent = 0;
498 local $Data::Dumper::Terse = 1;
499 local $Data::Dumper::Useqq = 1;
501 my $typestr = Amanda::Xfer::xmsg_type_to_string($self->{'type'});
502 my $str = "{ type => \$$typestr, elt => $self->{'elt'}, version => $self->{'version'},";
504 my %skip = ( "type" => 1, "elt" => 1, "version" => 1 );
505 for my $k (keys %$self) {
507 $str .= " $k => " . Dumper($self->{$k}) . ",";
510 # strip the trailing comma and add a closing brace
516 package Amanda::Xfer;
518 # make Amanda::Xfer->new equivalent to Amanda::Xfer::Xfer->new (don't
519 # worry, the blessings work out just fine)
520 *new = *Amanda::Xfer::Xfer::new;