class SF::Ftp

Overview

A FTP client

SF::Ftp is a very simple FTP client that allows you to communicate with a FTP server. The FTP protocol allows you to manipulate a remote file system (list files, upload, download, create, remove, ...).

Using the FTP client consists of 4 parts:

Every command returns a FTP response, which contains the status code as well as a message from the server. Some commands such as #working_directory() and directory_listing() return additional data, and use a class derived from SF::Ftp::Response to provide this data. The most often used commands are directly provided as member functions, but it is also possible to use specific commands with the #send_command() function.

Note that response statuses >= 1000 are not part of the FTP standard, they are generated by SFML when an internal error occurs.

All commands, especially upload and download, may take some time to complete. This is important to know if you don't want to block your application while the server is completing the task.

Usage example:

# Create a new FTP client
ftp = SF::Ftp.new

# Connect to the server
response = ftp.connect("ftp://ftp.myserver.com")
if response.ok?
  puts "Connected"
end

# Log in
response = ftp.login("laurent", "dF6Zm89D")
if response.ok?
  puts "Logged in"
end

# Print the working directory
directory = ftp.working_directory
if directory.ok?
  puts "Working directory: #{directory.directory}"
end

# Create a new directory
response = ftp.create_directory "files"
if response.ok?
  puts "Created new directory"
end

# Upload a file to this new directory
response = ftp.upload("local-path/file.txt", "files", SF::Ftp::Ascii)
if response.ok?
  puts "File uploaded"
end

# Send specific commands (here: FEAT to list supported FTP features)
response = ftp.send_command "FEAT"
if response.ok?
  puts "Feature list:\n#{response.message}"
end

# Disconnect from the server
ftp.disconnect

Included Modules

Defined in:

network/obj.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new #

[View source]

Instance Method Detail

def change_directory(directory : String) : Ftp::Response #

Change the current working directory

The new directory must be relative to the current one.

  • directory - New working directory

Returns: Server response to the request

See also: #working_directory, directory_listing, #parent_directory


[View source]
def connect(server : IpAddress, port : Int = 21, timeout : Time = Time::Zero) : Ftp::Response #

Connect to the specified FTP server

The port has a default value of 21, which is the standard port used by the FTP protocol. You shouldn't use a different value, unless you really know what you do. This function tries to connect to the server so it may take a while to complete, especially if the server is not reachable. To avoid blocking your application for too long, you can use a timeout. The default value, Time::Zero, means that the system timeout will be used (which is usually pretty long).

  • server - Name or address of the FTP server to connect to
  • port - Port used for the connection
  • timeout - Maximum time to wait

Returns: Server response to the request

See also: #disconnect


[View source]
def create_directory(name : String) : Ftp::Response #

Create a new directory

The new directory is created as a child of the current working directory.

  • name - Name of the directory to create

Returns: Server response to the request

See also: #delete_directory


[View source]
def delete_directory(name : String) : Ftp::Response #

Remove an existing directory

The directory to remove must be relative to the current working directory. Use this function with caution, the directory will be removed permanently!

  • name - Name of the directory to remove

Returns: Server response to the request

See also: #create_directory


[View source]
def delete_file(name : String) : Ftp::Response #

Remove an existing file

The file name must be relative to the current working directory. Use this function with caution, the file will be removed permanently!

  • name - File to remove

Returns: Server response to the request

See also: #rename_file


[View source]
def disconnect : Ftp::Response #

Close the connection with the server

Returns: Server response to the request

See also: #connect


[View source]
def download(remote_file : String, local_path : String, mode : Ftp::TransferMode = Binary) : Ftp::Response #

Download a file from the server

The filename of the distant file is relative to the current working directory of the server, and the local destination path is relative to the current directory of your application. If a file with the same filename as the distant file already exists in the local destination path, it will be overwritten.

  • remote_file - Filename of the distant file to download
  • local_path - The directory in which to put the file on the local computer
  • mode - Transfer mode

Returns: Server response to the request

See also: #upload


[View source]
def finalize #

Destructor

Automatically closes the connection with the server if it is still opened.


[View source]
def get_directory_listing(directory : String = "") : Ftp::ListingResponse #

Get the contents of the given directory

This function retrieves the sub-directories and files contained in the given directory. It is not recursive. The directory parameter is relative to the current working directory.

  • directory - Directory to list

Returns: Server response to the request

See also: #working_directory, #change_directory, #parent_directory


[View source]
def keep_alive : Ftp::Response #

Send a null command to keep the connection alive

This command is useful because the server may close the connection automatically if no command is sent.

Returns: Server response to the request


[View source]
def login(name : String, password : String) : Ftp::Response #

Log in using a username and a password

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

  • name - User name
  • password - Password

Returns: Server response to the request


[View source]
def login : Ftp::Response #

Log in using an anonymous account

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

Returns: Server response to the request


[View source]
def parent_directory : Ftp::Response #

Go to the parent directory of the current one

Returns: Server response to the request

See also: #working_directory, directory_listing, #change_directory


[View source]
def rename_file(file : String, new_name : String) : Ftp::Response #

Rename an existing file

The filenames must be relative to the current working directory.

  • file - File to rename
  • new_name - New name of the file

Returns: Server response to the request

See also: #delete_file


[View source]
def send_command(command : String, parameter : String = "") : Ftp::Response #

Send a command to the FTP server

While the most often used commands are provided as member functions in the SF::Ftp class, this method can be used to send any FTP command to the server. If the command requires one or more parameters, they can be specified in parameter. If the server returns information, you can extract it from the response using Response.message().

  • command - Command to send
  • parameter - Command parameter

Returns: Server response to the request


[View source]
def upload(local_file : String, remote_path : String, mode : Ftp::TransferMode = Binary, append : Bool = false) : Ftp::Response #

Upload a file to the server

The name of the local file is relative to the current working directory of your application, and the remote path is relative to the current directory of the FTP server.

The append parameter controls whether the remote file is appended to or overwritten if it already exists.

  • local_file - Path of the local file to upload
  • remote_path - The directory in which to put the file on the server
  • mode - Transfer mode
  • append - Pass true to append to or false to overwrite the remote file if it already exists

Returns: Server response to the request

See also: #download


[View source]
def working_directory : Ftp::DirectoryResponse #

Get the current working directory

The working directory is the root path for subsequent operations involving directories and/or filenames.

Returns: Server response to the request

See also: directory_listing, #change_directory, #parent_directory


[View source]