/ 
Convert-yEnc-1.03
River stage zero No dependents
/ Convert::yEnc::RC

NAME

Convert::yEnc::RC - yEnc file-part database

SYNOPSIS

use Convert::yEnc::RC;

	      $rc = new Convert::yEnc::RC;
	      $rc = new Convert::yEnc::RC $file;

$ok       = $rc->load;
$ok 	    = $rc->load($file);

$ok       = $rc->update  ($line);
@files    = $rc->files;
@complete = $rc->complete;
$complete = $rc->complete($fileName);
$entry    = $rc->entry   ($fileName);
$ok       = $rc->drop    ($fileName);

	      $rc->save;
	      $rc->save($file);

ABSTRACT

yEnc file-part database

DESCRIPTION

A Convert::yEnc::RC object manages a database of yEnc file parts.

Applications pass the =ybegin, =ypart, and =yend lines from yEncoded files to the object, and it keeps track of the files, parts and bytes as they are received. The object reports errors if the sequence of =y lines is inconsistent.

Applications can query the object to find out what files, parts, and bytes have been received, and whether a given file is complete.

The database can be be saved to and restored from disk.

Database format

The database is stored on disk as a flat ASCII file. There is one line in the database for each yEncoded file.

A line for a single-part file has 3 fields

  • the file name

  • the file size

  • the number of bytes received

A line for a multi-part file has 4 fields

  • the file name

  • the file size

  • a Set::IntSpan run list showing which bytes of the file have been recieved

  • a Set::IntSpan run list showing which parts of the file have been recieved

Fields are tab-delimited, so that file names may contain whitespace.

Example

a.jpg	20000	20000
b.jpg	10000	1-5000	1

Exports

Nothing.

Methods

$rc = new Convert::yEnc::RC
$rc = new Convert::yEnc::RC $file

Creates and returns a new Convert::yEnc::RC object.

If $file is supplied, initializes the database from $file.

If $file is not supplied, or doesn't exist, initializes the database to empty.

$ok = $rc->load($file)

Loads the database in $file into $rc. Any existing data in $rc is discarded. Returns true on success.

If $file can't be opened, load does nothing and returns false.

If $file contains invalid lines, load dies. When this happens, the state of $rc is undefined.

$ok = $rc->update($line)

Updates $rc according to the contents of $line. $line should be a header (=begin), trailer (=end), or part (=part) line from a yEncoded file.

Returns true iff $line is well-formed and consistent with the current state of the database.

@files = $rc->files

Returns a list of all the files in the database.

@complete = $rc->complete

Returns a list of all the files in the database that are complete.

$complete = $rc->complete($fileName)

Returns true iff all parts of ($fileName) have been received.

$entry = $rc->entry($fileName)

Returns the database entry for $fileName. $entry is a Convert::yEnc::Entry object.

If $fileName is not in the database, return undef.

$ok = $rc->drop($fileName)

Deletes the entry for $fileName from the database.

If $fileName is not in the database, return false.

$rc->save

Writes the contents of $newsrc back to the file from which it was loaded.

save dies if there is an error writing the file.

$newsrc->save($file)

Writes the contents of $newsrc to $file. Subsequent calls to save() will write to $file.

save dies if there is an error writing the file.

BUGS

    item *

    The database doesn't persist the yEnc 1.2 "total" field to disk.

SEE ALSO

AUTHOR

Steven W McDougall, <swmcd@world.std.com>

COPYRIGHT AND LICENSE

Copyright (c) 2002-2004 by Steven McDougall. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.