=head1 NAME

File::Rdiff

=head1 SYNOPSIS

 use File::Rdiff

=head1 DESCRIPTION

A more-or-less direct interface to librsync (L<http://rproxy.samba.org>).

For usage examples (better than this very sparse documentation), see the
two example scripts rdiff1 and rdiff2 that came with the distribution.

=over 4

=cut

package File::Rdiff;

require DynaLoader;
require Exporter;

$VERSION = 0.01;
@ISA = qw/DynaLoader Exporter/;

bootstrap File::Rdiff $VERSION;

{
   my @loglevels = qw(LOG_EMERG LOG_ALERT LOG_CRIT LOG_ERR LOG_WARNING LOG_NOTICE LOG_INFO LOG_DEBUG);
   my @result = qw(DONE BLOCKED RUNNING TEST_SKIPPED IO_ERROR SYNTAX_ERROR MEM_ERROR INPUT_ENDED BAD_MAGIC UNIMPLEMENTED CORRUPT INTERNAL_ERROR PARAM_ERROR);

   %EXPORT_TAGS = (
           loglevels   => [@loglevels],
           trace       => [@loglevels, qw(trace_level trace_to)],
           result      => [@result],
           error       => [@result, qw(strerror)],
           file        => [@result, qw(md4_file sig_file loadsig_file delta_file patch_file)],
           nonblocking => [@result],
   );

   my %export_ok;
   @export_ok{map @$_, values %EXPORT_TAGS} = ();
   @EXPORT_OK = keys %export_ok;
}

=item LIBRSYNC_VERSION

A constant describing the version of the rsync library used in this
module. My version claimed to be "0.9.5 librsync" when I wrote this
document ;)

=item $oldlevel = trace_level [$newlevel]

Return the current tracelevel and optionally set a new one.

=item $oldcb = trace_to [$newcb]

Return the current trace callback and optionally set a new one. The callback will be
called with the log level as the first argument and the log message as the second one.

Calling C<trace_to> with C<undef> will restore the default handler (which
currently prints the message to standard error).

=item supports_trace

Returns wether debugging traces are supported in this version of the library.

=item $msg = strerror $rcode

Returns a string representation of the given error code. You usually
just "exit(1)" or something when a function/method fails, as all (most?)
librsync functions log the error properly, so there is rarely a need to
call this function.

=item $md4 = md4_file $fh

=item sig_file $old_fh, $sig_fh[, $block_len[, $strong_len]]

=item $sig = loadsig_file $fh

=item delta_file $signature, $new_fh, $delta_fh

=item patch_file $base_fh, $delta_fh, $new_fh

=back

=head2 The File::Rdiff::Job class

=head2 The File::Rdiff::Buffers class

This class contains the input and output buffers for the non-blocking interface. It is slightly unusual
in that it allows direct manipulation of (some) of it's internal variables.

=over 4

=item new File::Rdiff::Buffers [$outsize]

Creates and initializes a new buffers structure. C<$outsize> specifies
the maximum number of bytes to be read into the output scalar until it is
considered full. The default is 64k.

=item $buffers->in($in)

Set the next block of input to consume. Data will be read from this scalar
(no copy will be made!) until all bytes have been consumed or a new input
scalar is set.

=item $out = $buffers->out

Return the current output data and create a new buffer. Returns C<undef> if no data has been accumulated.

=item $buffers->eof

Set the eof flag to true. This indicates that no data is following the current input scalar.

=item $buffers->avail_in

Returns the numer of bytes still available for input.

=item $buffers->avail_out

Returns the number of bytes still available in the output buffer.

=item $buffers->size

The number of bytes that have been accumulated in the current buffer so far.

=back

=head2 The File::Rdiff::Job class

=over 4

=back

=head1 SEE ALSO

L<File::Rsync>, L<rdiff1> (usage example using simple file API), L<rdiff2> (example using nonblocking API).

=head1 BUGS

- not well-tested so far.

- low memory will result in segfaults rather than croaks.

- no access to statistics yet

- documentation leaves much to be deserved.

=head1 AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://www.goof.com/pcg/marc/

=cut

1;