NAME

MP3::Napster::Transfer - Manage Napster file transfer sessions

SYNOPSIS

$transfer = $nap->download($song);
print $transfer->asString,"\n";

print $transfer->title,"\n";
print $transfer->song,"\n";
print $transfer->remote_path,"\n";
print $transfer->local_path,"\n";
$fh = $transfer->fh;

print $transfer->sender,"\n";
print $transfer->recipient,"\n";
print $transfer->remote_user,"\n";
print $transfer->local_user,"\n";

print $transfer->direction,"\n";
print $transfer->status,"\n";
print $transfer->bytes,"\n";
print $transfer->expected_size,"\n";

print $transfer->done;

$transfer->interval(100_000);  # set reporting interval to 100K
$transfer->done(1);            # abort transfer

DESCRIPTION

MP3::Napster::Transfer allows you to monitor and control upload and download sessions initiated by the MP3::Napster module.

OBJECT CONSTRUCTION

Transfer objects are not constructed from scratch, but are created during the operation of MP3::Napster clients. Transfers from remote clients to the local machine are created by the download() method. Uploads to remote clients are created in response to requests by the Napster server.

OBJECT METHODS

Object methods provide access to transfer status information and allow you terminate the transfer prematurely.

Accessors

The accessors provide read-only access to the following attributes:

Accessor                   Description
--------                   -----------
$transfer->title           Title of the transfer, currently derived from the song name
$transfer->direction       Direction of the transfer, either "upload" or "download"
$transfer->asString        String of form "(downloading from foo) ChaChaCha.mp3"
$transfer->remote_path     Path to the song on the remote host
$transfer->local_path      Path to the song on the local host
$transfer->fh              Filehandle connected to the local song file
$transfer->socket          Socket connected to the remote host

NOTES: In the case of a song that is being downloaded to a file, local_path() will return the path on the local machine. In the case of a download that is being piped to a program, local_path() will return undef. In either case, fh() will return the local filehandle and socket() will return the handle connected to the remote host.

$transfer->sender          Nickname of sender
$transfer->recipient       Nickname of recipient
$transfer->remote_user     Nickname of remote user
$transfer->local_user      Nickname of local user

NOTES: These four methods return MP3::Napster::User objects corresponding to the two users involved in the transfer. Local_user() will always return the MP3::Napster::User that you are logged in as and remote_user() will always return the nickname of the peer, but send() and receipient() will vary depending on the direction of the transfer.

$transfer->status          Status of the transfer (see NOTES)
$transfer->statusString    Status plus transfer progress
$transfer->bytes           Number of bytes transferred
$transfer->expected_size   Expected size of the transfer
$transfer->connection      Connection type: "active" or "passive"

NOTES: The expected_size() method returns the total size of the song, in bytes, even when resuming from an interrupted transfer. However, in the latter case, bytes() will be set to the size previously transferred.

A transfer can either be initiated by the local host, in which case an outgoing connection is made to the peer, or it can be initiated by the peer, in which case the peer makes an incoming connection to the local host. The connection() method returns "active" in the former case, and "passive" in the latter. In the case of two non-firewalled peers, downloads are active and uploads are passive. If one of the peers is behind a firewall, then the firewalled peer makes active connections exclusively.

The status() method returns a human readable string indicating the current status of the transfer. The status states vary depending on whether the transfer is active or passive. The following status strings are possible in either case:

"waiting for transfer"           Object created, waiting for something to happen
"transferring"                   Data transfer is in progress
"transfer complete"              Transfer done, file transferred completely
"transfer incomplete"            Transfer done, file transferred incompletely
"ERROR: <error message>"         An error of some sort

The difference between "transfer incomplete" and "ERROR" is that in the former situation the transfer was cancelled prematurely by the local host or the peer, while in the latter the transfer was terminated by a software error of some sort.

These additional status strings are possible for active connections:

"initiating active connect"      Beginning an outgoing connection
"connecting to aa.bb.cc.dd:port" Trying to connect to remote peer
"reading welcome byte"           Reading a 1 byte acknowledgement from peer 
"request sent"                   Sent request and waiting for transfer

This additional status string is possible for passive connections:

"setting position"               Setting file position for interrupted transfers

The "transferring", "transfer complete", "transfer incomplete", and "ERROR" status messages are guaranteed never to change. The other status strings may be modified in later versions of this module.

$done = $transfer->done( [$flag] )

The done() method will return a true value if the transfer is finished. You may check its status() method to determine whether the transfer finished normally or abnormally.

To prematurely abort a file transfer, you may pass a true value to done():

$transfer->done(1);  # abort!

$interval= $transfer->interval( [$interval] )

The MP3::Napster::Transfer object issues up to three Napster events during its lifetime, any one of which can be intercepted by callbacks:

TRANSFER_STARTED      When the transfer is first initiated
TRANSFER_DONE	       When the transfer is finished
TRANSFER_IN_PROGRESS  At periodic intervals during the transfer

The interval() method allows you to get or set the interval at which TRANSFER_IN_PROGRESS messages are issued. The interval is measured bytes, so you can set interval() to 100,000 in order to be notified each time approximately 100K of data is transferred (the exact number varies by up to 1K depending on how much is sent in any given read() or write() call). If you do not wish to receive such messages, set interval() to 0.

Example:

$transfer->interval(250_000);  # notify every 250K

As explained in MP3::Napster, the callback for these events will receive two arguments consisting of the MP3::Napster object and the MP3::Napster::Transfer object. Here are practical examples of intercepting and using the three events to produce informational messages:

  $nap->callback(TRANSFER_STARTED,
             sub { 
	        my ($nap,$transfer) = @_;
                return unless $transfer->direction eq 'upload';
                my $song = $transfer->song;
                my $nick = $transfer->remote_user;
                print "\t[ $nick has begun to download $song ]\n";
              });

  $nap->callback(TRANSFER_IN_PROGRESS,
             sub { 
                my ($nap,$transfer) = @_;
                my ($bytes,$expected) = ($transfer->bytes,$transfer->expected_size);
                print "\t[ $transfer: $bytes / $expected bytes ]\n";
             });

  $nap->callback(TRANSFER_DONE,
             sub { 
                my ($nap,$transfer) = @_;
                my $song = $transfer->song;
                print "\t[ $song done: ",$transfer->status," ]\n";

                if ($transfer->direction eq 'download' &&
	               $transfer->status ne 'transfer complete' && 
	                   $transfer->local_path) {
                    print "\t[ $song incomplete: unlinking file ]\n";
                    unlink $transfer->local_path;
                }
             });

String Overloading

If used in a string context, MPEG::Napster::Transfer objects will invoke the asString() method. This allows the objects to be directly interpolated into strings, printed, and pattern matched.

AUTHOR

Lincoln Stein <lstein@cshl.org>.

COPYRIGHT

Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

MP3::Napster, MP3::Napster::User, MP3::Napster::Channel, and MPEG::Napster::Song