Latest revision as of 03:51, 7 June 2017

[edit] 360Works FTPeek User Guide

The 360Works FTPeek plugin enables SFTP (encrypted with SSH) / FTP / FTPS (encrypted with SSL) functionality in FileMaker, including:

• Establish an FTP connection to a server
• View a list of files in a specified directory
• Download files from the server to a specified directory
• Optionally rename the local file upon download

You can select what type of FTP protocol you want to use by using one of the FTPeek_Connect methods. For regular unencrypted FTP, use FTPeek_ConnectFTP. You can also do SFTP with FTPeek_ConnectSFTP or FTPS with FTPeek_ConnectFTPS.</p>

Once you're connected, the plugin functions to upload, download, etc. are the same for all three protocols.</p>

More information about the FTP protocol, as well as the secure variations (SFTP and FTPS) can be found at this <a href="http://en.wikipedia.org/wiki/File_Transfer_Protocol" target="_new">Wikipedia article</a>.

Example Usage

This shows an example of connecting to a secure SFTP server, getting a list of files, and downloading one of them.</p>

Step #1: Get public key of the server. This returns text that can be stored in FileMaker.</p>

Set Field[ example::publicKey; FTPeek_GetPublicKey( "host.address.com" ) ]
If[ example::publicKey = "ERROR" ] ...show error using FTPeek_LastError...

Step #2: Connect to the server. Requires public key and client authentication.</p>

if[ FTPeek_ConnectSFTP( "host.address.com" ; example::publicKey ; "username" ; 
     "password" ) = "ERROR" ] ...Handle error...

Step #3: Get a list of files in a directory on the server</p>

Set Field[ example::filesList; FTPeek_GetFileList( "/Users/username/" ) ]
if[ example::filesList = "ERROR" ] ...show error using FTPeek_LastError...

Step #4: Download the first file in the list to a temp directory and name it newFileName.</p>

If[ FTPeek_DownloadFile( "/tmp/" ; GetValue( example::filesList; 1 ); 
     "newFileName" ) = "ERROR" ] ...Handle error...

Step #5: Disconnect</p>

If[ FTPeek_Disconnect = "ERROR" ]
     ...Display error message to user, but we don't need to do anything else...

<a name="rel_path">Relative vs. Absolute Paths</a>

All functions support referencing remote files and directories as relative or absolute paths.</p>A relative path references files and directories starting from the current working directory. For example, if we are in the /uploaded/FTPeek/ directory on the remote server, changing into backup would navigate into the /uploaded/FTPeek/backup/ directory.
On the other hand, an absolute path references files and directories starting from the root directory of the server. If we're in the same /uploaded/FTPeek/ directory and try to change into /temp, we would actually end up in /temp/ instead of /uploaded/FTPeek/temp/, since we start at the root directory instead of the current working directory.</p> As seen in the examples, an absolute path starts with a slash /, while a relative one does not. Either can be passed in to FTPeek_ChangeDir, FTPeek_Rename, FTPeek_UploadFile, and other functions to reference relative or absolute paths.</p>

[edit] 360Works Plugin Setup Guides

See Plugins_101 for Error reporting, installation, registration, and more.

[edit] Function Summary

[edit] Function Detail

[edit] FTPeek_ChooseFile ( { initialPath ; fileType ; title } )

Pops up a file chooser dialog.

*Note that although all parameters in this function are optional, they are also positional.  This means that if you want to specify a fileType without specifying initialPath you'll need
pass in an empty string "" for the initialPath parameter.

[edit] FTPeek_DownloadFileToContainer ( remoteSourcePath )

Downloads a file and returns file's data into a container field, sets transfer type for this action to Binary unless specified otherwise in FTPeek_SetTransferType( type ). For example, this will download a Word document from the FTP server and store it into a container field:

Set Field[ example::ContainerField; 
     FTPeek_DownloadFileToContainer("My report.doc") ]

[edit] FTPeek_DownloadFileToField ( remoteSourcePath { ; encoding } )

Downloads a file and returns file's data as text. For example, this will download a text file from the FTP server and store it into a text field:

Set Field[ example::TextField; 
     FTPeek_DownloadFileToField("My File.txt") ]

[edit] FTPeek_ExecuteCommand ( command )

Requests that the remote server execute the literal command supplied. In FTP and SFTP, this might be a SITE command, while in SFTP it might be a shell command. It is up to the user to send a sensible command.

[edit] FTPeek_GetCurrentDir ( )

Returns path of current working directory on the server.
For example, if the plugin has connected and navigated into a directory called temp, calling the FTPeek_GetCurrentDir function will return /temp/.

[edit] FTPeek_GetFileInfo ( remotePath; infoType )

Gets information about the selected file.

[edit] FTPeek_GetFileList ( { remoteDir } )

Returns a list of files in a directory as a return-separated list. If the directory is not specified, the contents of the current working directory are returned. The passed-in directory can be relative or absolute.

[edit] FTPeek_GetPublicKey ( host )

Gets an SFTP server's public key, which must be provided as a parameter to FTPeek_ConnectSFTP. The public key is used to check to make sure that the server you are connecting to is the same one that you originally retrieved the key from. This prevents a malicious attacker from using DNS spoofing to pose as the real FTP server. For this reason, you should get the public key the first time you connect to an FTP server, and then store that in your FileMaker database and use the same key each time you connect to the server. You could retrieve the public key every time you connect to the server, but that would defeat the purpose of this security layer.

[edit] FTPeek_IsConnected ( )

Returns connection status.

[edit] FTPeek_LastError ( )

Returns detailed information about the last error generated by this plugin. If another plugin function returns the text "ERROR", call this function to get a user-presentable description of what went wrong. For example,

If[ FTPeek_ConnectFTP( "ftp.domain.com"; "username"; "password" ) = "ERROR" ]
	Show Custom Dialog[ "Could not connect to FTP Server: " & FTPeek_LastError ]
	Exit Script
End If

[edit] FTPeek_LastErrorCode ( )

Returns the FTP reply code from the most recent FTP command that resulted in error.

[edit] FTPeek_LicenseInfo ( )

Returns license information about the plugin. This shows whether it is registered, and what type of license is being used.

[edit] FTPeek_ScanLocalDir ( localPath ; recursive )

Do not use this function - it is only included for backwards compatibility and will be removed from a future version of FTPeek. Use FTPeek_ScanLocalDirectory instead.

[edit] FTPeek_ScanLocalDirectory ( localPath ; isPathFromFileMaker )

Scans a local directory and returns a return-separated list of files in the directory. This is useful for examining the contents of a local directory to select files for upload. For example, the following call:

Set Field[ example::localFilesList; 
     FTPeek_ScanLocalDirectory( "/Library/User Pictures/Animals", 0 ) ]
on Mac OS X will set

the field example::localFilesList to a return separated list of files, such as

Butterfly.tif
Cat.tif
Dog.tif
Dragonfly.tif
Jaguar.tif
Parrot.tif
...etc

Calling this function on Windows:

Set Field[ example::localFilesList; 
     FTPeek_ScanLocalDir( "C:\WINDOWS\Media"; 0 ) ]

will set example::localFilesList to

chimes.wav
chord.wav
ding.wav
flourish.mid
notify.wav
onestop.mid
recycle.wav
ringin.wav
ringout.wav
start.wav
tada.wav
town.mid
...etc

Directories will end in a '/' on Mac OS X or '\' on Windows.

[edit] FTPeek_Version ( )

Returns the version number of the plugin. This is always a numeric value, with no letter characters.