Namespace and Class LrFtp

Summary

Functions

LrFtp.appendFtpPaths( root, child )

Appends two paths together for use in FTP. Often an FTP preset contains a parent directory in which the user wants to put multiple subdirectories. Use this function to generate the final destination directory for upload by combining the parent directory with the child directory. The function ensures that a single directory separator is inserted between the two path parts. If the child path starts with a '/' then the root path is not used. It ensures the result ends in a trailing '/', unless the result is the empty string. It does not resolve relative paths using '..' or '.'.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. root

(string) The root path.

2. child

(string) The subdirectory path.

Return value

(string) The path that results from combining the root and child.

LrFtp.create( params, autoNegotiate )

Creates and return an FTP connection object (ftpConnection). This method must be called from within within an asynchronous task started by LrTasks.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. params

(table) A table with these fields:

• passive: (string) The type of passive connection to make: "none", "normal" or "enhanced".
• password: (string) The password to accompany the username in authentication.
• path: (string) The remote path to use when sending or receiving files from the server.
• port: (integer) The network port the server is using to host the FTP service.
• protocol: (string) The type of FTP connection to use, "ftp" or "sftp".
• server: (string) The server name or IP address for this FTP connection.
• username: (string) The username to authenticate the connection.

2. autoNegotiate

(Boolean) True to prompt the user for retry if the connection cannot be completed due to an invalid password or an SSH host-key issue.

Return value

(ftpConnection) The new FTP connection object, or nil and an error message if the connection failed.

LrFtp.ftpPathValidator( view, inValue )

A validator function for use in LrView UI control definitions. Backslashes are converted to forward slashes, and a notice is presented to the user. If the value contains a new-line character, everything after and including the new-line is removed.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. view

(LrView) The view object.

2. inValue

(any) The proposed new value for the view.

Return values

1. (Boolean) True if the value is valid
2. (any) The new value for the view. If valid, this is the same as inValue.
3. (string) An error message to be displayed if the value was invalid.

See also

LrView

LrFtp.makeFtpPresetPopup( params )

Creates and returns a pop-up menu view object for accessing FTP presets.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. params

(table) a table with these fields

• factory: (LrViewFactory) The view factory.
• properties: (table) The property table.
• valueBinding: (table) The key in the property table for the preset.
• itemsBinding: (table) The key in the property table for the preset items list.

Return value

(LrView) A view object of type popup_menu, created by the provided factory, with bindings set to display and change the FTP preset value.

LrFtp.queryForPasswordIfNeeded( ftpSettings )

Prompts the user for a password, but only if the preset was created with 'store password' unchecked.

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. ftpSettings

Return value

(boolean) True if the password was successfully entered. False if the user cancelled the prompt.

ftpConnection:disconnect()

Disconnects this connection from the server. Once disconnected, this connection cannot be reused. This method must be called from within an asynchronous task started by LrTasks. Throws an exception in the event of an error.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection:exists( filename )

Tests for the existance of a file or directory on the remote system. at the current ftpConnection.path. This method must be called from within an asynchronous task started by LrTasks.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. filename

(string) The name of the resource to test.

Return value

(Boolean, string)

• On success: False if the resource does not exist, 'file' if it exists as a file, and 'directory' if it exist as a directory
• On failure: Nil and an error message.

ftpConnection:getContents( remoteFileName )

Retrieves the contents of a file or directory on the remote server and returns it as a string. If the remote name is a path separator character ('/'), a file listing for the current ftpConnection.path will be returned.

This method must be called from within an asynchronous task started by LrTasks. Throws an exception in the event of an error.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. remoteFileName

(string) The remote file name, or a path separator character ('/'). To specify the containing directory, set the ftpConnection.path property to the name of an existing directory.

Return value

(string) The contents of the remote file, or the file listing for the FTP connection's path.

ftpConnection:makeDirectory( directoryName )

Creates a directory on the remote server. The current ftpConnection.path must exist on the server as a directory. There must not exist any file or directory of this name at the destination location. This method must be called from within an asynchronous task started by LrTasks. Throws an exception in the event of an error.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. directoryName

(string) The name of the directory to create.

Return value

(Boolean) True if the operation succeeds and a subsequent check shows the directory to exist. False if the operation succeeds but the check shows it to be missing.

ftpConnection:pRemoveDirectory( directoryName )

Removes a directory on the remote server. The same as removeDirectory(), except that it returns success or failure rather than throwing an exception.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. directoryName

(string) The name of the directory to remove.

Return values

1. (Boolean) True if the function completed correctly
2. (string or Boolean) On failure, the error message. On success, true if a check for the directory after the operation completed shows it to be deleted.

ftpConnection:pRemoveFile( filename )

Removes a file on the remote server. The same as removeFile(), except that it returns success or failure rather than throwing an exception.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. filename

(string) The name of the file to remove.

Return values

1. (Boolean) True if the function completed correctly
2. (string/Boolean) On failure, the error message. On success, true if a check for the file after the operation completed shows it to be deleted.

ftpConnection:putFile( theLocalFilePath, destFileName )

Sends a file from the local filesystem to the remote server. To specify an upload destination, set the connection to a given directory by setting the path property. The upload destination must already exist as a directory. This method must be called from within an asynchronous task started by LrTasks. Throws an exception in the event of an error.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. theLocalFilePath

(string) The local file path, using the local system path separator.

2. destFileName

(string) The destination file name

ftpConnection:removeDirectory( directoryName )

Removes a directory on the remote server. The current ftpConnection.path must exist on the server as a directory. There must exist an empty directory with this name at the destination location. This method must be called from within an asynchronous task started by LrTasks. Throws an exception on error.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. directoryName

(string) The name of the directory to remove.

Return value

(Boolean) True if a check for the directory after the operation completes shows it to be deleted.

ftpConnection:removeFile( filename )

Removes a file on the remote server. The current ftpConnection.path must exist on the server as a directory. There must exist a file with this name at the destination location. This method must be called from within an asynchronous task started by LrTasks. Throws an exception in the event of an error.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. filename

(string) The name of the file to remove.

Return value

(Boolean) True if a check for the file after the remove completed shows it to be deleted.

ftpConnection:toTable()

Converts the properties of this FTP connection back into a Lua table, the same as the one passed to LrFtp.create() to create the object.

First supported in version 1.3 of the Lightroom SDK.

Return value

(table) A table of entries for all the properties on this connection.

See also

LrFtp.create

Properties

ftpConnection.connected : (Read-Only)

(Boolean) True if a connection exists. Even if the connection exists, it could time out or experience network problems at any time, so the fact of connection does not guarantee the success of subsequent operations.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.passive : (Read-Only)

(string) When protocol is "ftp", the kind of passive connection to attempt. One of "none", "normal", or "enhanced". When protocol is "sftp", this is not used.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.password : (Read-Only)

(string) The password to accompany the username in authentication.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.path : (Read/Write)

(string) The remote path to use when sending or receiving files from the server.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.port : (Read-Only)

(integer) The network port the server is using to host the FTP service.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.protocol : (Read-Only)

(string) The type of FTP connection to use, one of "ftp" or "sftp".

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.server : (Read-Only)

(string) The server name or IP address for this FTP connection.

First supported in version 1.3 of the Lightroom SDK.

ftpConnection.username : (Read-Only)

(string) The username to authenticate the connection.

First supported in version 1.3 of the Lightroom SDK.