File Ftp.lua

Functions

Ftp.assurePassword (ftpSettings, ftpPropertyMap) Static equivalent of query-for-password-if-needed method.
Ftp.formatPath (p) Static function to format a server path.assures ftp slash convention (forward).
Ftp.formatSubPath (p, trailingSlashOk) Static function to format a sub-path - assures ftp slash convention (forward) and removes leading and trailing slashes.
Ftp.uncalibrateClock (server) Allows get-dir-contents to be had, with the caveat that file-time will be uncalibrated.
Ftp:_makeDirPath (rsp) Synopsis: Create a full path to a remote directory from parent and child sub-paths.
Ftp:_makeFilePath (rsp) Synopsis: Creates a full path to a remote file from parent and child components.
Ftp:assureAllRemoteDirectories (rsp) Synopsis: Create directories if not already, up to and including the leaf of specified path.
Ftp:calibrateClock (localDirForTempFile, rsp, leaveRemFile) Synopsis: Computes offset of remote clock from 2001-01-01, GMT.
Ftp:connect () Connect to the remote server.
Ftp:disconnect () Disconnect from the remote server.
Ftp:existsAsDir (rsp, expected) Synopsis: Determines if dir exists, and will double-check if no expectation, waits for it to disappear if its supposed to be gone (like when it was just deleted), or waits for it to be present if expected to be there (like if it was just put out there, or detected via get-dir-contents...).
Ftp:existsAsFile (rsp, expected) Synopsis: Determines if file exists, and will double-check if no expectation, waits for it to disappear if its supposed to be gone (like when it was just deleted), or waits for it to be present if expected to be there (like if it was just put out there, or detected via get-dir-contents...).
Ftp:getDirContents (rsp, remoteClockOffset) Synopsis: Get lists of directories and files in the specified remote directory.
Ftp:getFileContents (rsp) Get remote file contents.
Ftp:init (ftpSettings, autoNegotiate) Initialize ftp settings and other particulars.
Ftp:isEmpty (dir) Determine if specified directory (remote sub-path) is empty.
Ftp:isFileSame (localFile, rsp, options) Determine if local file is same as remote file.
Ftp:makeDir (rsp) Synopsis: Create a remote directory, if not already existing.
Ftp:new (t) Constructor for new instance.
Ftp:newClass (t) Constructor for extending class.
Ftp:putFile (localPath, rsp, overwriteOK) Synopsis: Put (upload) a file from local disk to remote.
Ftp:queryForPasswordIfNeeded (ftpSettings, ftpPropertyMap) Serves same purpose as Lr-FTP version - prompt user for password if not provided in the settings.
Ftp:removeDirTree (rsp) Synopsis: Remove a directory tree, which typically (although not necessarily) pre-exists, including sub-dir & files.
Ftp:removeEmptyDir (rsp) Synopsis: Removes a directory known to exist and be empty.
Ftp:removeFile (rsp) Synopsis: Removes a file which is presumably (although not necessarily) existing before calling.
Ftp:uploadFile (localPath, rsp, validate) Upload file (re-writing remote file if necessary), and optionally: validate.


Functions

Ftp.assurePassword (ftpSettings, ftpPropertyMap)
Static equivalent of query-for-password-if-needed method.

Parameters:

  • ftpSettings:
  • ftpPropertyMap:
Ftp.formatPath (p)
Static function to format a server path.assures ftp slash convention (forward). optional leading slash will determine whether remote path is absolute or relative to server default.

Parameters:

  • p:

Usage:

    Assures ftp slash convention (forward). optional leading slash will determine whether remote path is absolute or relative to server default.
    Trailing slash is preserved, but should not have any effect.
Ftp.formatSubPath (p, trailingSlashOk)
Static function to format a sub-path - assures ftp slash convention (forward) and removes leading and trailing slashes.

Parameters:

  • p:
  • trailingSlashOk:
Ftp.uncalibrateClock (server)
Allows get-dir-contents to be had, with the caveat that file-time will be uncalibrated.

Parameters:

  • server:

Usage:

    Warning: this will affect all instances. 
Ftp:_makeDirPath (rsp)
Synopsis: Create a full path to a remote directory from parent and child sub-paths. Notes: This function takes a root-dir-path and sub-dir-path and returns a full-path to a dir for ftp purposes. Preferred over lightroom's version when you dont want to run the risk of a slash prefixed child-path being interpreted as an absolute path, instead of a relative path. Also, makes sure input paths are interpreted correctly regardless of source path origins (e.g. local windows dir that contains backslashes), and makes sure result path is properly formatted for FTP, meaning only forward slashes, no backslashes. Reminder: the Lr-Ftp function only checks if child-path begins with a forward slash, and if so root-path is ignored. It interprets backslash prepended child-paths as true children. Also, although Lr-Ftp is surprisingly tolerant of appending windows backslashed paths to traditionaly ftp forward slashed paths, I prefer the asthetic of properly formatted ftp paths, and in so doing, this function may even prevent a bug in the future. Returns: Full path, no excuses, trailing slash. - No guarantee its to a real directory: garbage in = garbage out.

Parameters:

  • rsp:
Ftp:_makeFilePath (rsp)
Synopsis: Creates a full path to a remote file from parent and child components. Notes: Uses dir-path function to assure leading slash, one sep, and trailing slash, then removes the trailing slash to turn it into a file reference. Returns: Full path, no excuses, no trailing slash. - No guarantee its to a real file: garbage in = garbage out.

Parameters:

  • rsp:
Ftp:assureAllRemoteDirectories (rsp)
Synopsis: Create directories if not already, up to and including the leaf of specified path. Notes: - path must be to folder, not file. - departs from the "leave logging to calling context" convention by logging all dirs created or pre-existing if verbose mode. Idea: could make a table and return to caller. Returns: - true, nil: worked, no comment. - true, comment: pretend it worked, see comment. - false, error-message: failed.

Parameters:

  • rsp:
Ftp:calibrateClock (localDirForTempFile, rsp, leaveRemFile)
Synopsis: Computes offset of remote clock from 2001-01-01, GMT. Motivation: FTP, much to my dissatisfaction, uses the remote clock to set the timestamp of uploaded files. I wish it would set it to the exact value of the local source file. This would solve a lot of problems, and cause none. But, for some reason, the FTP protocol is like never improved (go figure), thus we have to keep chugging along with same 'ol same 'ol for better and for worse... The problem is: If the clock at the remote end is slow, and you upload a file immediately after changing it, it will appear to be out of date already after being uploaded. Throw in differences in time zone, and daylight savings and the problem worsens - the file may appear out of date all day long, even after continually uploading, then appear up-to-date the next day without having done anything except wait. Likewise, and usually a worse problem - if the clock at the remote end is ahead, a recently changed local file may appear up-to-date forever and never be uploaded. The solution is: Before beginning an ftp session, create a tiny local file and upload it. Read the remote timestamp back and save the difference between it and local time. This offset can then be applied in the future to compute a normalized remote timestamp that is accurate to within a few seconds, instead of 25 hours. Note: This function may be called explicitly from outside, which allows logging of results before ftp session begins, and allows specification of writeable directory to be used for temp filem but if not - will be called automatically from within - temp file dir will be whatever. My experience has been that true ftp connections are not really made until they needs to be. And since this may be the first need, it will fail if remote server is down. If local-dir-for-temp-file is passed in, make sure it's been standardized, since this function won't do it. Returns: - true, nil: calibrated, no comment. - false, error-message: failed.

Parameters:

  • localDirForTempFile:
  • rsp:
  • leaveRemFile:
Ftp:connect ()
Connect to the remote server.

Usage:

    side-effect: validates root-server-dir exists - this forces a true connection, and is a pre-requisite to everything else. 
Ftp:disconnect ()
Disconnect from the remote server.

Usage:

    Optional method - makes for a clean break, but connection cleanup via Lightroom or OS so far has made this unnecessary. 
Ftp:existsAsDir (rsp, expected)
Synopsis: Determines if dir exists, and will double-check if no expectation, waits for it to disappear if its supposed to be gone (like when it was just deleted), or waits for it to be present if expected to be there (like if it was just put out there, or detected via get-dir-contents...). Returns: - true, nil: dir exists, for sure. - false, nil: dir does not exist, for sure. - nil, error-message: uncertain, see error message.

Parameters:

  • rsp:
  • expected:
Ftp:existsAsFile (rsp, expected)
Synopsis: Determines if file exists, and will double-check if no expectation, waits for it to disappear if its supposed to be gone (like when it was just deleted), or waits for it to be present if expected to be there (like if it was just put out there, or detected via get-dir-contents...). Returns: - true, nil: file exists, for sure. - false, nil: file does not exist, for sure. - nil, error-message: uncertain, see error message.

Parameters:

  • rsp:
  • expected:
Ftp:getDirContents (rsp, remoteClockOffset)
Synopsis: Get lists of directories and files in the specified remote directory. Returns: two arrays of directory elements (one for directories, one for files) whose entries are structs containing: - leafName: string - date: last-mod date-time, expressed as a number of seconds since midnight GMT, January 1, 2001 (same as local files ala lr-file-utils). - size (applies to both dirs & files). Returns empty tables if directory empty. Returns nil & error message if probs. Side Effects: - Will change path in ftp-conn. Notes: Usually only called when directory known to exist - not sure what happens if it doesn't. *** IMPORTANT NOTE: Relies on parsing text content of remote directory - may not be compatible with all servers. *** IMPORTANT NOTE: Must NOT be called from calibrate-clock method or there will be an infinite loop. (_get-dir-contents can be called from calib-clock - with underscore).

Parameters:

  • rsp:
  • remoteClockOffset:
Ftp:getFileContents (rsp)
Get remote file contents.

Parameters:

  • rsp:

Return values:

  1. contents or nil.
  2. errm or nil.
Ftp:init (ftpSettings, autoNegotiate)
Initialize ftp settings and other particulars.

Parameters:

  • ftpSettings:
  • autoNegotiate:

Usage:

    optional method, in case the particulars were not available at the time of new instance creation. 
Ftp:isEmpty (dir)
Determine if specified directory (remote sub-path) is empty.

Parameters:

  • dir:

Return values:

  1. status (boolean) nil => error; true => empty; false => not empty
  2. message (string) if status == nil, explanation.
Ftp:isFileSame (localFile, rsp, options)
Determine if local file is same as remote file.

Parameters:

  • localFile: (string, required) absolute path
  • rsp: (string, required) relative subpath
  • options: (struct, optional) named options, including:
    dateTol - to set a date tolerance.

Usage:

  • Uses auto-caching of dir contents, which means it's only good for one "run", and @24/Jan/2014 5:09, no way to clear caches, so a new ftp object must be created for each run.
  • @8/May/2012, size is only criteria, by default. 

Return values:

  1. status (boolean) true if same, false if different, nil if undiscernable or error.
  2. errm (string) nil if status is true or false or undiscernable, else error message.
Ftp:makeDir (rsp)
Synopsis: Create a remote directory, if not already existing. Notes: Creates parent directories as necessary. Returns: - true, nil: worked, no comment, no distinction. - true, comment: pretend like it worked, see comment. - false, comment: failed.

Parameters:

  • rsp:
Ftp:new (t)
Constructor for new instance.

Parameters:

  • t: (initialization table, optional) ftp-settings and auto-negotiate may come now or in init method.
Ftp:newClass (t)
Constructor for extending class.

Parameters:

  • t:
Ftp:putFile (localPath, rsp, overwriteOK)
Synopsis: Put (upload) a file from local disk to remote. Notes: - If file pre-exists and overwrite OK, existing target will be removed first. - Directory tree created if necessary to support file. - This function takes the liberty to do a little verbose logging, plus warnings... Returns: - true, nil: worked, no comment. - false, comment: failed.

Parameters:

  • localPath:
  • rsp:
  • overwriteOK:
Ftp:queryForPasswordIfNeeded (ftpSettings, ftpPropertyMap)
Serves same purpose as Lr-FTP version - prompt user for password if not provided in the settings.

Motivation: Lightroom's version just says "gimme a password" without stating what the password is for. This is one of my all time pet peeves in modern software - I suppose if you are the kind of person that uses the same password for everything and dont care what its for when you are asked for one, it doesn't much matter - I am not that kind of person. Its completely unacceptable for Photooey since passwords may be needed for two different servers.

Parameters:

  • ftpSettings: (table, required) can be user-created lua table (as long as required members are present),
    or that created by binding to make-ftp-preset-popup.
  • ftpPropertyMap:

Usage:

  • This function indicates the password request is for ftp user on specified server.
  • Use in conjunction with view--observe-Ftp-Property-Changes, since it will set up the encrypted password store.
  • This function can be called as object method or dot-function (static). 

Return value:

    ok (boolean) true iff valid password entered.
Ftp:removeDirTree (rsp)
Synopsis: Remove a directory tree, which typically (although not necessarily) pre-exists, including sub-dir & files. Note: - You can not remove the root dir. - first return value is never nil. Returns: - true, nil: removed, or wasnt there to begin with, no comment, no distinction. - false, error-message: cant, and here's why...

Parameters:

  • rsp:
Ftp:removeEmptyDir (rsp)
Synopsis: Removes a directory known to exist and be empty. Notes: - dir-path - presumably already in the proper format (hint: use make-dir-path). - first return value will never be nil. - Tries 3 times with 1 second between. My experience is that if you've just deleted the last file, then the first attempt at removing the directory may fail. Returns: - true, nil -- worked, no issues. - false, msg -- maybe didnt work, warning or error message.

Parameters:

  • rsp:
Ftp:removeFile (rsp)
Synopsis: Removes a file which is presumably (although not necessarily) existing before calling. Notes: file-path - presumably already in the proper format (hint: use make-file-path). Returns: - true: file removed, or was never there. - false, error message: file not removed, reason.

Parameters:

  • rsp:
Ftp:uploadFile (localPath, rsp, validate)
Upload file (re-writing remote file if necessary), and optionally: validate.

Parameters:

  • localPath: local path
  • rsp: remote path
  • validate:

Valid XHTML 1.0!