Decoding

The decoding functions take a stream of bytes from the remote rsync and convert them into an internal data structure. Rather than store the file list as a native perl list of hashes (which occupies too much memory for large file lists), the same internal data structure as rsync is used. Individual file list entries can be returned with the get() function.

File list data read from the remote rsync should be passed to the decode() function. The data may be read and processed in arbitrary sized chunks. The decode() function returns how many bytes were actually processed. It is the caller's responsbility to remove that number of bytes from the input argument, preserving the remaining bytes for the next call to decode(). The decodeDone() function returns true when the file list is complete. The fatalError() function returns true if there was a non-recoverable error while decoding.

The clean() function needs to be called after the file list decode is complete. The clean() function sorts the file list and removes repeated entries. Skipping this step will produce unexpected results: since files are referred to using integers, each side will refer to different files is the file lists are not sorted and purged in exactly the same manner.

A typical decode loop looks like:

while ( !$fileList->decodeDone && !$fileList->fatalError ) {
    $data .= readMoreDataFromRemoteRsync();
    $bytesDone = $fileList->decode($data);
    $data = substr($data, $bytesDone) if ( $bytesDone > 0 );
}
$fileList->clean;

After clean() is called, the number of files in the file list can be found by calling count(). Files can be fetched by calling the get() function, with an index from 0 to count()-1:

$fileInfo = $fileList->get(5);

The get() function returns a hashref with various entries:

name      path name of the file (relative to rsync dir):
          equal to dirname/basename
basename  file name, without directory
dirname   directory where file resides
sum       file MD4 checksum (only present if --checksum specified)
uid       file user id
gid       file group id
mode      file mode
mtime     file modification time
size      file length
dev       device number on which file resides
inode     file inode
link      link contents if the file is a sym link
rdev      major/minor device number if file is char/block special

Various fields will only have valid values if the corresponding options are set (eg: uid if preserve_uid is set, dev and inode if preserve_hard_links is set etc).

For example, to dump out each of hash you could do this:

use Data::Dumper;
my $count = $fileList->count;
for ( my $i = 0 ; $i < $count ; $i++ ) {
    print("File $i is:\n");
    print Dumper($fileList->get($i));
}

Encoding

The encode() function is used to build a file list in preparation for encoding and sending a file list to a remote rsync. The encode() function takes a hashref argument with the parameters for one file. It should be called once for each file. The parameter names are the same as those returned by get().

In this example the matching stat() values are shown:

$fileList->encode({
        name  => $filePath,
        dev   => $stat[0],
        inode => $stat[1],
        mode  => $stat[2],
        uid   => $stat[4],
        gid   => $stat[5],
        rdev  => $stat[6],
        size  => $stat[7],
        mtime => $stat[9],
    });

It is not necessary to specify basename and dirname; these are extracted from name. You only need to specify the parameters that match the options given to new(). You can also specify sum and link as necessary.

To compute the encoded file list data the encodeData() function should be called. It can be called every time encode() is called, or once at the end of all the encode() calls. It returns the encoded data that should be sent to the remote rsync:

$data = $fileList->encodeData;

It is recommended that encodeData() be called frequently to avoid the need to allocate large internal buffers to hold the entire encoded file list. Since encodeData() does not know when the last file has been encoded, it is the caller's responsbility to add the final null byte (eg: pack("C", 0)) to the data to indicate the end of the file list data.

After all the file list entries are processed you should call clean():

$fileList->clean;

This ensures that each side (sender/receiver) has identical sorted file lists.

Utility functions

The count() function returns the total number of files in the internal file list (either decoded or encoded).

The fatalError() function returns true if a fatal error has occured during file decoding. It should be called in the decode loop to make sure no error has occured.