Difference between revisions of "360Works FTPeek/Documentation"
WikiEditTask (talk | contribs) m (Auto-upload documentation) |
|||
Line 14: | Line 14: | ||
More information about the FTP protocol, as well as the secure variations (SFTP and FTPS) can be found | More information about the FTP protocol, as well as the secure variations (SFTP and FTPS) can be found | ||
− | at this | + | at this [Wikipedia article](http://en.wikipedia.org/wiki/File_Transfer_Protocol). |
<h3>Example Usage</h3> | <h3>Example Usage</h3> |
Revision as of 15:22, 17 September 2024
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.
Once you're connected, the plugin functions to upload, download, etc. are the same for all three protocols.
More information about the FTP protocol, as well as the secure variations (SFTP and FTPS) can be found at this [Wikipedia article](http://en.wikipedia.org/wiki/File_Transfer_Protocol).
Example Usage
This shows an example of connecting to a secure SFTP server, getting a list of files, and downloading one of them.
Step #1: Get public key of the server. This returns text that can be stored in FileMaker.
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.
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
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.
If[ FTPeek_DownloadFile( "/tmp/" ; GetValue( example::filesList; 1 );
"newFileName" ) = "ERROR" ] ...Handle error...
Step #5: Disconnect
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.
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.
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.
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.
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.
*Note that although all parameters in this function are optional, they are also positional. This means that if you want to specify afileType
without specifyinginitialPath
you'll need pass in an empty string""
for theinitialPath
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") ]
remoteSourcePath
- the file path on the remote server to download
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") ]
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.
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.
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/
.
FTPeek_GetFileInfo ( remotePath; infoType )
Gets information about the selected file.
remotePath
- remote file path to get info for.
infoType
- Can be either
size
, which returns the file size in bytes, ormoddate
, 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.
remoteDir
- the path of the directory to look in, or empty for the current working 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.
host
- address of the server; can be numeric IP address like
"127.0.0.1"
or a named one like"ftp.mysite.com"
FTPeek_IsConnected ( )
Returns connection status.
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
null
if there was no error.
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. This shows whether it is registered, and what type of license is being used.
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.
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.
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'.
FTPeek_Version ( )
Returns the version number of the plugin. This is always a numeric value, with no letter characters.