# Class: Ftp

## helma.Ftp(server)

This class represents a FTP client, providing access to an FTP server.

## Constructor

#### new Ftp(server)

Constructor for FTP client objects, to send and receive files from an FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`server` | String | as String, the address of the FTP Server to connect to

Source:
  - helma/Ftp.js, line 45

##### Example

    var ftp = new helma.Ftp("ftp.mydomain.com");

### Methods

#### active()

Switches the connection to use active mode.

Source:
  - helma/Ftp.js, line 203

##### Example

    ftp.active();

#### ascii()

Sets transfer mode to ascii for transmitting text-based data.

Source:
  - helma/Ftp.js, line 186

##### Example

    ftp.ascii();

#### binary()

Sets transfer mode to binary for transmitting images and other non-text files.

Source:
  - helma/Ftp.js, line 169

##### Example

    ftp.binary();

#### cd(dir)

Changes the working directory on the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`dir` | String | as String, the path that the remote working directory should be changed to

Source:
  - helma/Ftp.js, line 324

##### Examples

    ftp.cd("/home/users/fred/www"); // use absolute pathname

    ftp.cd(".."); // change to parent directory

    ftp.cd("images"); // use relative pathname

#### deleteFile(remoteFile)

Deletes a file on the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`remoteFile` | String | as String, the name of the file to be deleted

Source:
  - helma/Ftp.js, line 500

##### Returns:

Boolean true if the deletion was successful, false otherwise

##### Example

    var str = ftp.deleteFile("messages.txt");

#### dir(path)

Returns a listing of the files contained in a directory on the FTP server.
Lists the files contained in the current working directory or, if an alternative path is specified, the files contained in the specified directory.

##### Parameters:

Name | Type | Description
--- | --- | ---
`path` | String | as String, optional alternative directory

Source:
  - helma/Ftp.js, line 262

##### Returns:

Array containing the list of files in that directory

##### Example

    var filelist = ftp.dir();

#### getFile(remoteFile, localFile)

Transfers a file from the FTP server to the local file system.

##### Parameters:

Name | Type | Description
--- | --- | ---
`remoteFile` | String | as String, the name of the file that should be downloaded
`localFile` | String | as String, the name which the file should be stored under

Source:
  - helma/Ftp.js, line 450
See:
  - #cd
  - #lcd

##### Example

    ftp.getFile(".htaccess", "htaccess.txt");

#### getString(remoteFile)

Retrieves a file from the FTP server and returns it as string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`remoteFile` | String | as String, the name of the file that should be downloaded

Source:
  - helma/Ftp.js, line 479
See:
  - #cd

##### Returns:

String containing the data of the downloaded file

##### Example

    var str = ftp.getString("messages.txt");

#### lcd(dir)

Changes the working directory of the local machine when being connected to an FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`dir` | String | as String, the path that the local working directory should be changed to

Source:
  - helma/Ftp.js, line 344

##### Examples

    ftp.lcd("/home/users/fred/www"); // use absolute pathname

    ftp.lcd(".."); // change to parent directory

    ftp.lcd("images"); // use relative pathname

#### login(username, password)

Logs in to the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`username` | String | as String
`password` | String | as String

Source:
  - helma/Ftp.js, line 151

##### Returns:

Boolean true if the login was successful, otherwise false

#### logout()

Terminates the current FTP session.

Source:
  - helma/Ftp.js, line 536

#### mkdir(dir)

Creates a new directory on the server.
The name of the directory is determined as the function's string parameter. Returns false when an error occured (e.g. due to access restrictions, directory already exists etc.), otherwise true.

##### Parameters:

Name | Type | Description
--- | --- | ---
`dir` | String | as String, the name of the directory to be created

Source:
  - helma/Ftp.js, line 285

##### Returns:

Boolean true if the directory was successfully created, false if there was an error

#### passive()

Switches the connection to use passive mode.

Source:
  - helma/Ftp.js, line 220

##### Example

    ftp.passive();

#### putBytes(bytes, remoteFile)

Transfers a byte array to a file on the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`bytes` | Array | The byte array that should be uploaded
`remoteFile` | String | The name of the remote destination file

Source:
  - helma/Ftp.js, line 428

##### Returns:

Boolean True if the file was successfully uploaded, false if there was an error

#### putFile(localFile, remoteFile)

Transfers a file from the local file system to the remote server.
Returns true if the transmission was successful, otherwise false.

##### Parameters:

Name | Type | Description
--- | --- | ---
`localFile` | String | as String, the name of the file to be uploaded
`remoteFile` | String | as String, the name of the remote destination file

Source:
  - helma/Ftp.js, line 369

##### Returns:

Boolean true if the file was successfully uploaded, false if there was an error

#### putString(str, remoteFile, charset)

Transfers text from a string to a file on the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`str` | String | as String, the text content that should be uploaded
`remoteFile` | String | as String, the name of the remote destination file
`charset` | String | as String, optional

Source:
  - helma/Ftp.js, line 406

##### Returns:

Boolean true if the file was successfully uploaded, false if there was an error

##### Example

    ftp.putString("Hello, World!", "message.txt");

#### pwd()

Returns the path of the current working directory.

Source:
  - helma/Ftp.js, line 239

##### Returns:

String containing the current working directory path

##### Example

    var remotepath = ftp.pwd();

#### renameFile(from, to)

Renames a file on the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`from` | String | the name of the original file
`to` | String | the new name the original file should get

Source:
  - helma/Ftp.js, line 521

##### Returns:

Boolean true if renaming the remote file was successful, false otherwise

##### Example

    var success = ftp.renameFile("messages.tmp", "messages.txt");

#### rmdir(dir)

Deletes a directory on the FTP server.

##### Parameters:

Name | Type | Description
--- | --- | ---
`dir` | String | as String, the name of the directory to be deleted

Source:
  - helma/Ftp.js, line 304

##### Returns:

Boolean true if the deletion was successful, false otherwise

#### setReadTimeout()

Set the default timeout in milliseconds to use when opening a socket.

Source:
  - helma/Ftp.js, line 116

#### setTimeout()

Sets the timeout in milliseconds to use when reading from the data connection.

Source:
  - helma/Ftp.js, line 131