/ 
Net-FSP-0.16
River stage zero No dependents
/ Net::FSP

NAME

Net::FSP - A client implementation of the File Service Protocol

VERSION

This documentation refers to Net::FSP version 0.16

SYNOPSIS

use Net::FSP;
my $fsp = Net::FSP->new("hostname", { remote_port => 21 });

$fsp->current_dir->download('./');  
#do something
$fsp->upload_file('foo', 'foo');

DESCRIPTION

FSP is a very lightweight UDP based protocol for transferring files. FSP has many benefits over FTP, mainly for running anonymous archives. FSP protocol is valuable in all kinds of environments because it is one of the few protocols that is not aggressive about bandwidth while at the same time being sufficiently fault tolerant. Net::FSP is a class implementing the client side of FSP.

METHODS

new($remote_host, {...})

Creates a new Net::FSP object. As its optional second argument it takes a hashref of the following members:

remote_port

The remote port to connect to. It defaults to 21.

local_address

The local address to bind to. This parameter is usually only needed on multihomed connections. By default a socket isn't bound to a particular interface.

local_port

The local port to bind the connection to. It defaults to 0 (random).

min_delay

The minimal delay in seconds before a request is resent. It defaults to 1.34.

delay_factor

The factor with which the delay increases each time a request goes unresponded. It defaults to 1.5.

max_delay

The maximal delay for resending a request. If the delay would have been larger than this an exception is thrown. It defaults to 60 seconds.

password

Your password for this server. It defaults to undef (none).

max_payload_size

The maximal size of the payload. It defaults to 1024. Some servers may not support values higher than 1024. Setting this higher than the MTU - 12 is not recommended.

network_layer

This sets the protocol used as network layer. Currently the only supported values are ipv4 (the default) and ipv6 (this requires having the Socket6 module installed). As of writing no FSP server supports ipv6 yet though.

read_size

The size with which data is requested from the server. It defaults to max_payload_size.

write_size

The size with which data is written to the server. It defaults to max_payload_size.

listing_size

The size with which directories are read from the server. It defaults to max_payload_size.

current_dir()

This method returns the current working directory on the server.

change_dir($new_directory)

This method changes the current working directory on the server. It returns the previous working directory.

say_bye()

This method releases the connection to the FSP server. Note that this doesn't mean the connection is closed, it only means other clients from the same host can now contact the server.

server_version()

This method returns the full version of the server.

server_config()

This method returns some information about the configuration of the server. It returns a hashref with the following elements: logging, read-only, reverse-lookup, private-mode throughput-control extra-data.

download_file($file_name, $sink)

This method downloads file $file_name to $sink. $sink must either be an untainted filename, a filehandle or a callback function.

cat_file($file_name)

This method downloads file $file_name and returns it as a string. Using this on large files is not recommended.

grab_file($file_name, $sink)

This method downloads file $file_name, and deletes it at when this is done. These actions are considered atomic by the server. Its arguments work as in download_file.

list_dir($directory_name)

This method returns a list of files and subdirectories of directory $directory_name. The entries in the lists are either a Net::FSP::File or a Net::FSP::Dir for files and directories respectively.

stat_file($file_name)

In list context this returns a list of: the modification time (in unix format), the size (in bytes), and the type (either 'file' or 'dir') of file $file_name. In scalar context it returns either a Net::FSP::File or a Net::FSP::Dir object for files and directories respectively.

upload_file($file_name, $source)

This method uploads file $file_name to the server. $source must either be a filename, a filehandle or a callback function.

open_file($file_name, $mode)

Open a file and return a filehandle.

remove_file($file_name)

This method deletes file $file_name.

remove_dir($directory_name)

This method deletes directory $directory_name.

get_readme($dirname)

This method returns the readme for a directory, if there is any.

get_protection($directory_name)

This method returns the directory's protection. It returns a hash reference with the elements owner, delete, create, mkdir, private, readme, list and rename.

set_protection($directory_name, $mode)

This method changes the permission of directory $directory_name for public users. It's mode argument is consists of two characters. The first byte is + or -, to indicate whether the permission is granted or revoked. The second byte contains a c, d, g, m, l or r for the permission to create files, delete files, get files, create directories, list the directory or rename files. Its return value is the same as get_protection.

make_dir($directory_name)

This method creates a directory named $directory_name.

move_file($old_name, $new_name)

This method moves $old_name to $new_name.

DIAGNOSTICS

If the server encounters an error, it will be thrown as an exception string, prepended by 'Received error from server: '. Unfortunately the content of these errors are not well documented. Since the protocol is mostly stateless one can usually assume these errors have no effect on later requests. If the server doesn't respond at all, a 'Remote server not responding.' exception will eventually be thrown.

DEPENDENCIES

This module depends on perl version 5.6 or higher.

BUGS AND LIMITATIONS

FSP connections can not be shared between threads. Other than that, there are no known problems in this module. Please report problems to Leon Timmermans (fawaka@gmail.com). Patches are welcome.

CONFIGURATION AND ENVIRONMENT

This module has no configuration file. All configuration is done through the constructor. Some utility functions to make used of the environment are defined in Net::FSP::Util.

INCOMPATIBILITIES

This module has no known incompatibilities.

AUTHOR

Leon Timmermans, fawaka@gmail.com

SEE ALSO

The protocol is described at http://fsp.sourceforge.net/doc/PROTOCOL.txt.

LICENSE AND COPYRIGHT

Copyright (c) 2005, 2008 Leon Timmermans. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.