360Works FTPeek/Documentation

From 360Works Product Documentation Wiki
Jump to: navigation, search

Contents

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>


360Works Plugin Setup Guides

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

Function Summary

  • FTPeek_ChooseFile ( { initialPath ; fileType ; title } ) — Pops up a file chooser dialog.
  • 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 ).
  • FTPeek_DownloadFileToField ( remoteSourcePath { ; encoding } ) — Downloads a file and returns file's data as text.
  • FTPeek_ExecuteCommand ( command ) — Requests that the remote server execute the literal command supplied.
  • FTPeek_GetCurrentDir ( ) — Returns path of current working directory on the server.
  • FTPeek_GetFileInfo ( remotePath; infoType ) — Gets information about the selected file.
  • FTPeek_GetFileList ( { remoteDir } ) — Returns a list of files in a directory as a return-separated list.
  • FTPeek_GetPublicKey ( host ) — Gets an SFTP server's public key, which must be provided as a parameter to {@link #FTPeek_ConnectSFTP}.
  • FTPeek_IsConnected ( ) — Returns connection status.
  • FTPeek_LastError ( ) — Returns detailed information about the last error generated by this plugin.
  • FTPeek_LastErrorCode ( ) — Returns the FTP reply code from the most recent FTP command that resulted in error.
  • FTPeek_LicenseInfo ( ) — Returns license information about the plugin.
  • 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.
  • FTPeek_ScanLocalDirectory ( localPath ; isPathFromFileMaker ) — Scans a local directory and returns a return-separated list of files in the directory.
  • FTPeek_Version ( ) — Returns the version number of the plugin.

Function Detail

FTPeek_ChooseFile ( { initialPath ; fileType ; title } )

Pops up a file chooser dialog.

Parameters:

initialPath
optional path to set the initial dialog selection to. If empty, will default to the user's home directory.
fileType
option parameter to specify whether to allow "files", "directories", or both "files + directories".
title
optional title string to display as the title of the FileChooser dialog.

Returns: </p>
*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.

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") ]


Parameters:

remoteSourcePath
the file path on the remote server to download

Returns: container data with the downloaded file

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") ]


Parameters:

remoteSourcePath
the file path on the remote server to download
encoding
optional text encoding. Some of the supported encodings are "ASCII", "ISO8859_1", "UTF8", "UTF-16", for more supported encodings consult <a href="http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html">Java supported encodings</a> use the second column of the table as the encoding name.

Returns: Text data

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.

Parameters:
Returns: result of the arbitrary command if one is appropriate on success, ERROR on failure

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/.

Returns: path of current working directory

FTPeek_GetFileInfo ( remotePath; infoType )

Gets information about the selected file.

Parameters:

remotePath
remote file path to get info for.
infoType
Can be either size, which returns the file size in bytes, or moddate, which returns a Date field with the modification date of the file.


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.

Parameters:

remoteDir
the path of the directory to look in, or empty for the current working directory

Returns: return-separated list of files in the directory

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.

Parameters:

host
address of the server; can be numeric IP address like "127.0.0.1" or a named one like "ftp.mysite.com"

Returns: a text representation of the server's public key

FTPeek_IsConnected ( )

Returns connection status.

Returns: 1 if connected to server, 0 if not connected

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


Returns: Error text, or null if there was no error.

FTPeek_LastErrorCode ( )

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

Returns: An integer if an error occurred.

FTPeek_LicenseInfo ( )

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

Returns: plugin license information

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.

Parameters:


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.

Parameters:

localPath
path of the local folder to scan
isPathFromFileMaker
Set to 1 if localPath is a FileMaker-style path, returned from a FileMaker path function such as Get( DesktopPath ) or Get( TemporaryPath ). Set it to 0 if localPath is a native operating system path. For example, the file-style path to the user's desktop returned by Get( DesktopPath ) is '/Macintosh HD/Users/jesse/Desktop/', where the normal OS X path would be '/Users/jesse/Desktop'.

Returns: return-separated list of files in the specified directory

FTPeek_Version ( )

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

Returns: the version number of the plugin
Personal tools
Namespaces

Variants
Actions
Plug-in Products
Other Products
Navigation
Toolbox