class SFML::Network::Ftp

CSFML’s FTP client. Useful for the rare game that needs to fetch extra content from a plain-FTP server. For anything modern, Ruby’s stdlib Net::FTP (and the Net::FTP gem) is a much nicer tool — this binding exists for parity with CSFML.

ftp = SFML::Network::Ftp.new ftp.connect(“ftp.example.com”).ok? #=> true ftp.login_anonymous.ok? #=> true ftp.directory_listing(“/”).names #=> [“pub”, “incoming”, …] ftp.download(“/pub/file.bin”, “/tmp/”) ftp.disconnect

Each call returns a Response (or DirectoryResponse / ListingResponse for commands that return a path or a list). All responses expose ok?, status (Integer), status_symbol, message.

Constants

DEFAULT_PORT: Standard port for the protocol.
DEFAULT_TIMEOUT: Default per-call timeout.
STATUS_NAMES: FTP status codes mapped to symbols. The transport-error ones at ≥ 1000 are SFML’s, not RFC 959.

Public Class Methods

new ()

Source

# File lib/sfml/network/ftp.rb, line 52
def initialize
  ptr = C::Network.sfFtp_create
  raise NetworkError, "sfFtp_create returned NULL" if ptr.null?

  @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfFtp_destroy))
end

Create a new FTP client. Call connect next to open a session.

Public Instance Methods

change_directory (directory)

Source

# File lib/sfml/network/ftp.rb, line 94
def change_directory(directory)
  Response._take_ownership(C::Network.sfFtp_changeDirectory(@handle, directory.to_s))
end

cd to a directory.

connect (host, port: DEFAULT_PORT, timeout: DEFAULT_TIMEOUT)

Source

# File lib/sfml/network/ftp.rb, line 62
def connect(host, port: DEFAULT_PORT, timeout: DEFAULT_TIMEOUT)
  addr = IpAddress.from_string(host).struct
  t    = timeout.is_a?(Time) ? timeout : Time.seconds(timeout.to_f)
  Response._take_ownership(C::Network.sfFtp_connect(@handle, addr, Integer(port), t.to_native))
end

Connect to an FTP server. host may be an IP string (“1.2.3.4”) or hostname (“ftp.example.com”); pass timeout as a SFML::Time or numeric seconds (default 0 = no timeout).

create_directory (name)

Source

# File lib/sfml/network/ftp.rb, line 104
def create_directory(name)
  DirectoryResponse._take_ownership(C::Network.sfFtp_createDirectory(@handle, name.to_s))
end

mkdir — returns a DirectoryResponse with the new path.

delete_directory (name)

Source

# File lib/sfml/network/ftp.rb, line 109
def delete_directory(name)
  Response._take_ownership(C::Network.sfFtp_deleteDirectory(@handle, name.to_s))
end

rmdir.

delete_file (name)

Source

# File lib/sfml/network/ftp.rb, line 119
def delete_file(name)
  Response._take_ownership(C::Network.sfFtp_deleteFile(@handle, name.to_s))
end

Delete a single file.

directory_listing (directory = "")

Source

# File lib/sfml/network/ftp.rb, line 89
def directory_listing(directory = "")
  ListingResponse._take_ownership(C::Network.sfFtp_getDirectoryListing(@handle, directory.to_s))
end

List directory (default = current). Returns a ListingResponse.

disconnect (= Response._take_ownership(C::Network.sfFtp_disconnect(@handle)))

Source

# File lib/sfml/network/ftp.rb, line 79
def disconnect = Response._take_ownership(C::Network.sfFtp_disconnect(@handle))
# Send a no-op to keep the connection alive against server timeouts.
def keep_alive = Response._take_ownership(C::Network.sfFtp_keepAlive(@handle))

# Current working directory as a `DirectoryResponse`.
def working_directory
  DirectoryResponse._take_ownership(C::Network.sfFtp_getWorkingDirectory(@handle))
end

# List `directory` (default = current). Returns a `ListingResponse`.
def directory_listing(directory = "")
  ListingResponse._take_ownership(C::Network.sfFtp_getDirectoryListing(@handle, directory.to_s))
end

# `cd` to a directory.
def change_directory(directory)
  Response._take_ownership(C::Network.sfFtp_changeDirectory(@handle, directory.to_s))
end

# `cd ..`.
def parent_directory
  Response._take_ownership(C::Network.sfFtp_parentDirectory(@handle))
end

# `mkdir` — returns a `DirectoryResponse` with the new path.
def create_directory(name)
  DirectoryResponse._take_ownership(C::Network.sfFtp_createDirectory(@handle, name.to_s))
end

# `rmdir`.
def delete_directory(name)
  Response._take_ownership(C::Network.sfFtp_deleteDirectory(@handle, name.to_s))
end

# Rename / move a file on the server.
def rename_file(file, new_name)
  Response._take_ownership(C::Network.sfFtp_renameFile(@handle, file.to_s, new_name.to_s))
end

# Delete a single file.
def delete_file(name)
  Response._take_ownership(C::Network.sfFtp_deleteFile(@handle, name.to_s))
end

# Pull `remote` from the server to local path. `mode` is
# `:binary` (default), `:ascii`, or `:ebcdic`.
def download(remote, local, mode: :binary)
  idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
    raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
  Response._take_ownership(C::Network.sfFtp_download(@handle, remote.to_s, local.to_s, idx))
end

# Push `local` to `remote`. `append: true` extends an existing
# remote file rather than replacing it.
def upload(local, remote, mode: :binary, append: false)
  idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
    raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
  Response._take_ownership(C::Network.sfFtp_upload(@handle, local.to_s, remote.to_s, idx, !!append))
end

# Send a raw FTP command (e.g. "STAT") and an optional parameter.
def send_command(command, parameter = "")
  Response._take_ownership(C::Network.sfFtp_sendCommand(@handle, command.to_s, parameter.to_s))
end

attr_reader :handle # :nodoc:

# Generic response: most FTP operations return this.
class Response
  # `true` if ok.
  def ok?           = C::Network.sfFtpResponse_isOk(@handle)
  # Returns the status.
  def status        = C::Network.sfFtpResponse_getStatus(@handle)
  # Returns the status symbol.
  def status_symbol = STATUS_NAMES[status] || status
  # Returns the message.
  def message       = C::Network.sfFtpResponse_getMessage(@handle).to_s
  attr_reader :handle # :nodoc:

  # @!visibility private
  def self._take_ownership(ptr)
    obj = allocate
    obj.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C::Network.method(:sfFtpResponse_destroy)))
    obj
  end
end

# Returned by working_directory and create_directory — adds the
# `#directory` accessor on top of Response.
class DirectoryResponse
  # `true` if ok.
  def ok?           = C::Network.sfFtpDirectoryResponse_isOk(@handle)
  # Returns the status.
  def status        = C::Network.sfFtpDirectoryResponse_getStatus(@handle)
  # Returns the status symbol.
  def status_symbol = STATUS_NAMES[status] || status
  # Returns the message.
  def message       = C::Network.sfFtpDirectoryResponse_getMessage(@handle).to_s
  # Returns the directory.
  def directory     = C::Network.sfFtpDirectoryResponse_getDirectory(@handle).to_s
  attr_reader :handle # :nodoc:

  # @!visibility private
  def self._take_ownership(ptr)
    obj = allocate
    obj.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C::Network.method(:sfFtpDirectoryResponse_destroy)))
    obj
  end
end

# Returned by directory_listing — adds the `#names` array.
class ListingResponse
  # `true` if ok.
  def ok?           = C::Network.sfFtpListingResponse_isOk(@handle)
  # Returns the status.
  def status        = C::Network.sfFtpListingResponse_getStatus(@handle)
  # Returns the status symbol.
  def status_symbol = STATUS_NAMES[status] || status
  # Returns the message.
  def message       = C::Network.sfFtpListingResponse_getMessage(@handle).to_s
  # Returns the count.
  def count         = C::Network.sfFtpListingResponse_getCount(@handle)
  attr_reader :handle # :nodoc:

  # Filenames returned by the listing, as an Array of Strings.
  def names
    Array.new(count) { |i| C::Network.sfFtpListingResponse_getName(@handle, i).to_s }
  end

  # @!visibility private
  def self._take_ownership(ptr)
    obj = allocate
    obj.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C

Close the connection.

download (remote, local, mode: :binary)

Source

# File lib/sfml/network/ftp.rb, line 125
def download(remote, local, mode: :binary)
  idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
    raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
  Response._take_ownership(C::Network.sfFtp_download(@handle, remote.to_s, local.to_s, idx))
end

Pull remote from the server to local path. mode is :binary (default), :ascii, or :ebcdic.

keep_alive (= Response._take_ownership(C::Network.sfFtp_keepAlive(@handle)))

Source

# File lib/sfml/network/ftp.rb, line 81
def keep_alive = Response._take_ownership(C::Network.sfFtp_keepAlive(@handle))

# Current working directory as a `DirectoryResponse`.
def working_directory
  DirectoryResponse._take_ownership(C::Network.sfFtp_getWorkingDirectory(@handle))
end

# List `directory` (default = current). Returns a `ListingResponse`.
def directory_listing(directory = "")
  ListingResponse._take_ownership(C::Network.sfFtp_getDirectoryListing(@handle, directory.to_s))
end

# `cd` to a directory.
def change_directory(directory)
  Response._take_ownership(C::Network.sfFtp_changeDirectory(@handle, directory.to_s))
end

# `cd ..`.
def parent_directory
  Response._take_ownership(C::Network.sfFtp_parentDirectory(@handle))
end

# `mkdir` — returns a `DirectoryResponse` with the new path.
def create_directory(name)
  DirectoryResponse._take_ownership(C::Network.sfFtp_createDirectory(@handle, name.to_s))
end

# `rmdir`.
def delete_directory(name)
  Response._take_ownership(C::Network.sfFtp_deleteDirectory(@handle, name.to_s))
end

# Rename / move a file on the server.
def rename_file(file, new_name)
  Response._take_ownership(C::Network.sfFtp_renameFile(@handle, file.to_s, new_name.to_s))
end

# Delete a single file.
def delete_file(name)
  Response._take_ownership(C::Network.sfFtp_deleteFile(@handle, name.to_s))
end

# Pull `remote` from the server to local path. `mode` is
# `:binary` (default), `:ascii`, or `:ebcdic`.
def download(remote, local, mode: :binary)
  idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
    raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
  Response._take_ownership(C::Network.sfFtp_download(@handle, remote.to_s, local.to_s, idx))
end

# Push `local` to `remote`. `append: true` extends an existing
# remote file rather than replacing it.
def upload(local, remote, mode: :binary, append: false)
  idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
    raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
  Response._take_ownership(C::Network.sfFtp_upload(@handle, local.to_s, remote.to_s, idx, !!append))
end

# Send a raw FTP command (e.g. "STAT") and an optional parameter.
def send_command(command, parameter = "")
  Response._take_ownership(C::Network.sfFtp_sendCommand(@handle, command.to_s, parameter.to_s))
end

attr_reader :handle # :nodoc:

# Generic response: most FTP operations return this.
class Response
  # `true` if ok.
  def ok?           = C::Network.sfFtpResponse_isOk(@handle)
  # Returns the status.
  def status        = C::Network.sfFtpResponse_getStatus(@handle)
  # Returns the status symbol.
  def status_symbol = STATUS_NAMES[status] || status
  # Returns the message.
  def message       = C::Network.sfFtpResponse_getMessage(@handle).to_s
  attr_reader :handle # :nodoc:

  # @!visibility private
  def self._take_ownership(ptr)
    obj = allocate
    obj.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C::Network.method(:sfFtpResponse_destroy)))
    obj
  end
end

# Returned by working_directory and create_directory — adds the
# `#directory` accessor on top of Response.
class DirectoryResponse
  # `true` if ok.
  def ok?           = C::Network.sfFtpDirectoryResponse_isOk(@handle)
  # Returns the status.
  def status        = C::Network.sfFtpDirectoryResponse_getStatus(@handle)
  # Returns the status symbol.
  def status_symbol = STATUS_NAMES[status] || status
  # Returns the message.
  def message       = C::Network.sfFtpDirectoryResponse_getMessage(@handle).to_s
  # Returns the directory.
  def directory     = C::Network.sfFtpDirectoryResponse_getDirectory(@handle).to_s
  attr_reader :handle # :nodoc:

  # @!visibility private
  def self._take_ownership(ptr)
    obj = allocate
    obj.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C::Network.method(:sfFtpDirectoryResponse_destroy)))
    obj
  end
end

# Returned by directory_listing — adds the `#names` array.
class ListingResponse
  # `true` if ok.
  def ok?           = C::Network.sfFtpListingResponse_isOk(@handle)
  # Returns the status.
  def status        = C::Network.sfFtpListingResponse_getStatus(@handle)
  # Returns the status symbol.
  def status_symbol = STATUS_NAMES[status] || status
  # Returns the message.
  def message       = C::Network.sfFtpListingResponse_getMessage(@handle).to_s
  # Returns the count.
  def count         = C::Network.sfFtpListingResponse_getCount(@handle)
  attr_reader :handle # :nodoc:

  # Filenames returned by the listing, as an Array of Strings.
  def names
    Array.new(count) { |i| C::Network.sfFtpListingResponse_getName(@handle, i).to_s }
  end

  # @!visibility private
  def self._take_ownership(ptr)
    obj = allocate
    obj.instance_variable_set(:@handle,
      FFI::AutoPointer.new(ptr, C::Network

Source

# File lib/sfml/network/ftp.rb, line 74
def login(user, password)
  Response._take_ownership(C::Network.sfFtp_login(@handle, user.to_s, password.to_s))
end

login_anonymous ()

Source

# File lib/sfml/network/ftp.rb, line 69
def login_anonymous
  Response._take_ownership(C::Network.sfFtp_loginAnonymous(@handle))
end

parent_directory ()

Source

# File lib/sfml/network/ftp.rb, line 99
def parent_directory
  Response._take_ownership(C::Network.sfFtp_parentDirectory(@handle))
end

cd ...

rename_file (file, new_name)

Source

# File lib/sfml/network/ftp.rb, line 114
def rename_file(file, new_name)
  Response._take_ownership(C::Network.sfFtp_renameFile(@handle, file.to_s, new_name.to_s))
end

Rename / move a file on the server.

send_command (command, parameter = "")

Source

# File lib/sfml/network/ftp.rb, line 140
def send_command(command, parameter = "")
  Response._take_ownership(C::Network.sfFtp_sendCommand(@handle, command.to_s, parameter.to_s))
end

Send a raw FTP command (e.g. “STAT”) and an optional parameter.

upload (local, remote, mode: :binary, append: false)

Source

# File lib/sfml/network/ftp.rb, line 133
def upload(local, remote, mode: :binary, append: false)
  idx = C::Network::FTP_TRANSFER_MODES.index(mode) ||
    raise(ArgumentError, "Unknown FTP transfer mode: #{mode.inspect}")
  Response._take_ownership(C::Network.sfFtp_upload(@handle, local.to_s, remote.to_s, idx, !!append))
end

Push local to remote. append: true extends an existing remote file rather than replacing it.

working_directory ()

Source

# File lib/sfml/network/ftp.rb, line 84
def working_directory
  DirectoryResponse._take_ownership(C::Network.sfFtp_getWorkingDirectory(@handle))
end

Current working directory as a DirectoryResponse.