360Works FTPeek 1.67 User Guide

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

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.

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

Relative vs. Absolute Paths

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.

Error Handling/Reporting

When something unexpected happens, the plug-in will pop up a dialog showing what the error message is. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call FTPeek_SetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

When you call this function, it is set for that plug-in for as long as FileMaker is running, so if you want to do all of your own error handling, you can just set it to true once in your startup script. However, we recommend only turning it on when your script is prepared to check for errors, and then turning it off after finishing that section.

Whether or not you suppress the error dialogs, a plugin function will return the word ERROR if something goes wrong. It's a good idea to put your plugin functions in an 'If' statement so that you don't execute a bunch of script steps after something has gone wrong. If you'd like for your script to get the error message, you can get that by calling the FTPeek_LastError function.

Here is an example of basic error reporting:

Set Variable [ $result = MyPluginFunction("x" ; "y" ; "z") ]
If [ $result = "ERROR" ]
    Exit Script[ "Error occurred: " & FTPeek_LastError ]
Else
    ... do more stuff here ...
End If

Chaining Multiple Functions Together

Since the string "ERROR" evaluates to false when evaluated by FileMaker, and most plugin functions return a 1 when successful, you can chain multiple dependent plugin operations together using the "and" operator. However, in this case the result will be a 1 or a 0, not "ERROR". For example:

// chain multiple calls together
// if any of the functions fail, the calculation will
// short-circuit with a result of false,
// and none of the subsequent function calls will be evaluated.
Set Variable [ $success =
    FirstPluginFunction("x") and
    SecondPluginFunction("y") and
    ThirdPluginFunction("z")
]
If [not $success]
    Show Custom Dialog [ "An error occurred: " & FTPeek_LastError ]
End If

Note: the above only works for plugin functions which return 1 on success! Check the documentation for each function used in this manner.

Additional Error Checking - Plugin not installed

If a plugin is not installed correctly, calls to a plugin function will return "?". As part of your startup script, you should check for this occurrence and display a warning accordingly that the plugin needs to be installed. Note: when treated as a boolean true/false value, FileMaker will treat ? as true.

Installation

Requirements

FileMaker version 11 or higher.

Java Virtual Machine (JVM) version 1.6 or later (32-bit). If you are running a JVM earlier than 1.6, you should upgrade. Download a JVM from http://www.java.com/en/download/. Apple has a 32-bit version of Java 1.6 here http://support.apple.com/kb/DL1572. If you are not sure what version of Java you have installed, you can do java -version on the command line in Windows or OS X.

Windows, or Mac OS X version 10.6 or higher.

Note to intel Mac users: running this plugin under Rosetta is not supported. Upgrade to FileMaker 8.5 to run our plugin in native Intel mode.

Install Steps for FileMaker Pro

Drag the plugin from the MAC or WIN folder into your FileMaker extensions, and restart FileMaker.

If the plugin does not load correctly, double-check that you meet the system requirements.

Install steps for Instant Web Publishing

You do not need to do this step unless you plan on using the plugin with Instant Web Publishing with FileMaker Server Advanced. You will need an Enterprise license to use this feature.

For installing into the Web Publishing Engine with FileMaker Server or FileMaker Server Advanced, drag the plugin from the MAC (.fmplugin file) or WIN (.fmx file) folder into the FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins folder. If there is no Plugins folder inside the wpc folder, then create it manually. Restart FileMaker Web Publishing, and now the plugins should be ready to go.

The easiest way to test whether the plugin is working is to have a calculation which calls the version function of the plugin, and display that on an IWP layout. If it shows "?", then the plugin is not working. If it shows a number, then the plugin has been installed successfully.

Install steps for Custom Web Publishing

If you are using FileMaker Server 12.0v1 or earlier, you can follow the same procedure as detailed above for custom web publishing. However, in FileMaker Server 12.0v2 and later, the custom web publishing now runs as a 64-bit application, and requires a slightly different location. You will need an Enterprise license to use this feature.

For Mac, the single plug-in file in the MAC directory contains both 32-bit and 64-bit versions. For Windows, look for the plug-in that has the extension .fmx64 and use it in exclusively in custom web publishing.

To install 64-bit plug-ins, install either the .fmx64 or the .fmplugin to the following directory:

FileMaker Server / Web Publishing / publishing-engine / cwpc / Plugins

If it does not exist, create the Plugin folder manually. Restart FileMaker Web Publishing, and then you can then test a script that contains a plug-in and see if it returns the correct values.

Please note that plug-ins do not work with the web publishing engine of the Mac version of FileMaker Server 8.0v4.

Install steps for server scheduled scripts

You do not need to do this step unless you plan on using the plugin with scheduled script triggering. You will need an Enterprise license to use this feature.

  1. Drag the plugin from the MAC (.fmplugin file) or WIN (.fmx file) folder into the FileMaker Server extensions folder. On Mac OS X, this is located at /Library/FileMaker Server/Database Server/Extensions folder. On Windows, this is at C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions.
  2. In the Server Admin application, restart FileMaker Server by stopping and starting it.
  3. Go to Configuration -> Database Server->Server Plug-ins and check the box that says 'Enable FileMaker Server to use plug-ins', and then check the 'enabled' box for this plugin. Click the 'save' button and wait a few seconds to make sure that the 'enabled' check box stays checked. If it does not, then there was an error loading the plugin and you should contact us for help troubleshooting. You should now be able to write schedules that trigger scripts which use the plugin.

Auto Update

360Works has created an AutoUpdate helper database which makes setting up Auto Update much easier. This file includes pre-configured plugin files which you can place on your server, and an auto-update script for each of our plugins which you can paste into your own solution.

You can get the AutoUpdate360Works file at fmp7://autoupdate.360works.com/AutoUpdate360Works or fmp://autoupdate12.360works.com/AutoUpdate360Works. Follow the instructions included in the file to either host your own Auto Update server or pull the files from ours.

Uninstalling the plugin

Uninstall the plugin by quitting FileMaker Pro or stopping FileMaker Server and removing the plugin file from your Extensions directory.

Demo mode and Registering the plugin

Plugins will run in demo mode until they are registered. While running in Demo mode, the product will run for 2 hours every time you launch FileMaker / FileMaker Server / FileMaker Web Publishing Engine. The 2 hour time limit will reset every time you relaunch FileMaker. There is no expiration date when Demo mode stops working. There are no feature differences between the Demo version and the licensed version.

Once you have purchased the plugin, you can register it with the license key. Once a valid license key is entered, the product will run for as long as FileMaker is running. After FileMaker starts up with the plugin installed, open FileMaker preferences, click on the Plug-ins tab, select the plugin from the list, and click the Configure button. Enter your license key and company name in this dialog. You will only need to do this once on a given machine. Alternately, you can use the registration function to register the plugin during a startup script.

Note that if you are running the plugin with FileMaker Server / FileMaker Web Publishing Engine, you must use the registration function to register the plugin, since there is no preferences dialog on FileMaker Server to enter the license key and company name.

Feedback

We love to hear your suggestions for improving our products! If you are experiencing problems with this plugin, or have a feature request, or are happy with it, we'd appreciate hearing about it. Send us a message on our website, or email us!

Function Summary

Function Detail

FTPeek_ChangeDir ( remoteDir )

Changes the working directory to a specified directory. The remoteDir path can be relative or absolute.

Parameters:
remoteDir - the directory to navigate into
Returns: 1 on success, ERROR on failure

FTPeek_ChangeDirRoot ( )

Changes the working directory to the root directory of the server.

Returns: 1 on success, ERROR on failure

FTPeek_ChangeDirUp ( )

Changes the working directory to the parent of the current directory.

Returns: 1 on success, ERROR on failure

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:

*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_ConnectFTP ( host ; username ; password { ; flag1 ; flag2 ; ... } )

Connects to an FTP (File Transfer Protocol) server with the specified address, username, and password. You must call one of the connect methods (FTPeek_ConnectFTP, FTPeek_ConnectSFTP, or FTPeek_ConnectFTPS) before you can call any other FTP functions.

If multiple connect functions are called, the last connection remains as the active working connection. While previous connections will time-out and eventually disconnect, a server may allow a limited number of concurrent connections per account, limiting new connections until the old ones are closed. It is therefore highly recommended to close any active connection before opening a new one.

All connections are made in passive mode, unless the optional flag is used to explicitly change the mode to active.

Active mode

Use the optional arguments to connect to an FTP server using Active instead of the default Passive mode "ActiveMode=true".

Control channel encoding

Use the optional arguments to connect use a specific encoding for the control channel, "encoding=UTF8>/code>.
 Set Variable[$result =
     FTPeek_ConnectFTPS(
         "ftp.mysite.com" ;
         "username" ;
         "password" ;
         "ActiveMode=true" ;
         "encoding=UTF8"
     )
 ]
 

Logging level

  • DEBUG - use this logging level to produce detail log of ftp operations
          Set Variable[$result =
              FTPeek_ConnectFTPS(
                  "ftp.mysite.com" ;
                  "username" ;
                  "password" ;
                  "LoggingLevel=DEBUG"
              )
          ]
     

Timeout

Set a request timeout in milliseconds (e.g., 30000 = 30 seconds)
          Set Variable[$result =
              FTPeek_ConnectFTPS(
                  "ftp.mysite.com" ;
                  "username" ;
                  "password" ;
                  "timeout=30000"
              )
          ]
     

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like "ftp.mysite.com"; if need to connect to a non-standard port number, concatenate the port number to the host name like "ftp.mysite.com:21".
username - the client username.
password - the client authentication password.
args - Additional optional arguments ActiveMode, encoding, timeout.
Returns: 1 on success, ERROR on failure

FTPeek_ConnectFTPS ( host ; username ; password { ; flag1 ; flag2 ; ... } )

Connect to a FTPS (File Transfer Protocol over SSL) server. You must call one of the connect methods (FTPeek_ConnectFTP, FTPeek_ConnectSFTP, or FTPeek_ConnectFTPS) before you can call any other FTP functions.
If multiple connect functions are called, the last connection remains as the active working connection. While previous connections will time-out and eventually disconnect, a server may allow a limited number of concurrent connections per account, limiting new connections until the old ones are closed. It is therefore highly recommended to call FTPeek_Disconnect to close any active connection before opening a new one.

Here is an example of connecting to FTPS server:

 Set Variable[$result =
     FTPeek_ConnectFTPS(
         "ftp.mysite.com" ;
         "username" ;
         "password"
     )
 ]
 

No server certificate validation

Use the optional arguments to disable server certificate validation by passing "ValidateServerCertificate=false".
 Set Variable[$result =
     FTPeek_ConnectFTPS(
         "ftp.mysite.com" ;
         "username" ;
         "password" ;
         "ValidateServerCertificate=false"
     )
 ]
 

FTPS implicit

Use the optional arguments to use implicit FTPS mode "ImplicitFTPS=true".
 Set Variable[$result =
     FTPeek_ConnectFTPS(
         "ftp.mysite.com" ;
         "username" ;
         "password" ;
         "ImplicitFTPS=true"
     )
 ]
 

Start With Clear Data Channels

Use the optional arguments to start with clear data channels. Use this if the connect function returns a "USER and PASS required first" error. "StartWithClearDataChannels=true".
 Set Variable[$result =
     FTPeek_ConnectFTPS(
         "ftp.mysite.com" ;
         "username" ;
         "password" ;
         "StartWithClearDataChannels=true"
     )
 ]
 

Active mode

Use the optional arguments to connect to an FTP server using Active instead of the default Passive mode "ActiveMode=true".

Control channel encoding

Use the optional arguments to connect use a specific encoding for the control channel, "encoding=UTF8>/code>.
 Set Variable[$result =
     FTPeek_ConnectFTPS(
         "ftp.mysite.com" ;
         "username" ;
         "password" ;
         "ActiveMode=true" ;
         "encoding=UTF8"
     )
 ]
 

SSL flags

  • DisableDataSslClosure - use if plugin hangs after a file transfer completes, this happens when FTPS server does not send the data chanel ssl closure response
  • DisableControlWaitOnClose - use if plugin hangs after a file transfer completes, this happens when FTPS server does not send the control chanel ssl closure response
  • DisableSslClosure - use if plugin returns a premature SSL closure error
          Set Variable[$result =
              FTPeek_ConnectFTPS(
                  "ftp.mysite.com" ;
                  "username" ;
                  "password" ;
                  "DisableDataSslClosure=true" ;
                  "DisableSslClosure=true"
              )
          ]
 

Logging level

  • DEBUG - use this logging level to produce detail log of ftp operations
          Set Variable[$result =
              FTPeek_ConnectFTPS(
                  "ftp.mysite.com" ;
                  "username" ;
                  "password" ;
                  "LoggingLevel=DEBUG"
              )
          ]
     

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like "ftp.mysite.com"; if need to connect to a non-standard port number, concatenate the port number to the host name like "ftp.mysite.com:990"
username - the client username
password - the client authentication password
args - Additional optional arguments (ValidateServerCertificate, ImplicitFTPS, ActiveMode, encoding, ssl flags, logging level (see examples)).
Returns: 1 on successful connection, or "ERROR" if an error occurred (use FTPeek_LastError in this case)

FTPeek_ConnectSFTP ( host ; hostPublicKey ; username ; password { ; flag1 ; flag2 ; ... } )

Connects to an SFTP (SSH File Transfer Protocol) server with the specified address, public key, username, and password. You must call one of the connect methods (FTPeek_ConnectFTP, FTPeek_ConnectSFTP, or FTPeek_ConnectFTPS) before you can call any other FTP functions.
If multiple connect functions are called, the last connection remains as the active working connection. While previous connections will time-out and eventually disconnect, a server may allow a limited number of concurrent connections per account, limiting new connections until the old ones are closed. It is therefore highly recommended to close any active connection before opening a new one.

Logging level

  • DEBUG - use this logging level to produce detail log of ftp operations
          Set Variable[$result =
              FTPeek_ConnectSFTP(
                  "ftp.mysite.com" ;
                  "####Public Key####" ;
                  "username" ;
                  "password" ;
                  "LoggingLevel=DEBUG" ;
                  "PublicKeyAuth=1" ;
                  "PrivateKeyPath=/Users/username/.ssh/id_rsa"
              )
          ]
     

Parameters:
host - address of the server; can be numeric IP address like "127.0.0.1" or a named one like "ftp.mysite.com"; if need to connect to a non-standard port number, concatenate the port number to the host name like "ftp.mysite.com:21"
publicKey - the unique key of the server, obtained by calling {@link #FTPeek_GetPublicKey}. If a wrong key is entered, the connection will be refused and this error thrown: "The host signature is invalid or the host key was not accepted!"
username - the client username
password - the client authentication password
args - Additional optional arguments: LoggingLevel, PublicKeyAuth, PrivateKeyPath.
Returns: 1 on success, ERROR on failure

FTPeek_DeleteDir ( remoteDir { ; recursiveFlag } )

Deletes the specified empty remote directory. Trying to delete a non-empty remote directory will produce an error, unless recursive delete flag is specified. The remoteDir path can be relative or absolute.

Here is an example:

 Set Variable [ $deleteDir ; FTPeek_DeleteDir( "Empty/Directory" ) //relative path example ]
 Set Variable [ $deleteDir ; FTPeek_DeleteDir( "/home/files/Non empty directory" ; "recursive=true" ) //absolute path example]
 

Parameters:
remoteDir - remote directory to delete
recursiveFlag - optional parameter, specify recursive=true to enable recursive delete
Returns: 1 on success, ERROR on failure

FTPeek_DeleteFile ( remoteFile { ; wildcardFlag } )

Deletes the specified remote file. The remoteFile path can be relative or absolute.

Here is an example:

 Set Variable [ $deleteFile ; FTPeek_DeleteFile( "remoteFiles.txt" ) ]
 Set Variable [ $deleteFiles ; FTPeek_DeleteFile( "remoteFiles.*" ; "wildcards=true" ) ]
 

Parameters:
remoteFile - remote file path to delete
useWildcards - optional parameter, specify wildcards=true to enable wildcard characters * and ? in the remote file name to delete matching files.
Returns: 1 on success, ERROR on failure

FTPeek_DeleteLocal ( localFile )

Deletes the specified local file. If deleting a folder/directory, it must first be emptied.
 Set Variable [ $deleteLocal ; FTPeek_DeleteLocal( "/Users/username/Desktop/upload.gif" ) ]
 Set Variable [ $deleteLocal ; FTPeek_DeleteLocal( "c:\\Documents and Settings\\username\\Desktop\\upload.txt" ) ]

Parameters:
localFile - file on the local file system.
Returns: 1 on success, ERROR on failure.

FTPeek_Disconnect ( )

Disconnects from the server and quits the current SFTP/FTP/FTPS session.

Returns: 1 on success, ERROR on failure

FTPeek_DownloadFile ( remoteSourcePath ; localDestPath { ; newLocalFileName } )

Downloads a file to the specified directory and optionally renames the file.

Parameters:
remoteSourcePath - the file path on the remote FTP server to download
localDestPath - the directory on the computer running FileMaker Pro where the downloaded file should be stored, for example "/Users/Shared/Downloads/" or "filemac:/Macintosh HD/Users/Shared/Downloads/"
newLocalFileName - an optional parameter that can be used to locally rename the downloaded file. If left empty, the file will be named whatever it was named on the FTP server.
Returns: 1 on success, ERROR on failure

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 Java supported encodings 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_MakeDir ( remoteDir )

Creates a remote directory or directory path. If there are multiple directories in the path hierarchy that do not exist, all of them are created as necessary. Only ASCII characters are supported for directory names. The remoteDir path can be relative or absolute.

Here is an example:

 Set Variable [ $result ; FTPeek_MakeDir( "New Folder" ) //relative path example ]
 Set Variable [ $result ; FTPeek_MakeDir( "/home/files/newDir" ) //absolute path example]
 

Parameters:
remoteDir - remote directory path to create
Returns: 1 on success, ERROR on failure

FTPeek_Register ( licenseKey ; registeredTo )

Registers the plugin. This will not be retained at the next launch of FileMaker, so if you're using this method to register the plugin, you'll want to call this in the startup script. For developer licenses, this is the only way to register the plugin.

Parameters:
licenseKey - registration key
registeredTo - register to entity
Returns: 1 on success, ERROR on failure

FTPeek_Rename ( from ; to )

Renames a file on the remote server. The from and to paths can be relative or absolute, however, the "to" file path must be in the same directory as the "from" file path.

Parameters:
from - old file name to rename from
to - new file name to rename to
Returns: 1 on success, ERROR on failure

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_SetErrorCapture ( errorCapture )

Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call FTPeek_SetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.

Parameters:
errorCapture - set to true to suppress the default popups.

FTPeek_SetShowProgress ( showProgressFlag )

Configures whether to show progress bars on upload/download. Once this is set, it remains on that setting until changed, or until FileMaker is quit and restarted. Dialogs are displayed by default.

Parameters:
showProgressFlag - 0 to suppress progress bars, 1 to show progress bars.
Returns: This always returns a 1.

FTPeek_SetTransferType ( type )

Explicitly sets the transfer mode for uploading and downloading. This overwrites assumptions that FTPeek makes about what kind of file is being uploaded, and allows manual setting of the transfer type to use for an upload or download. Once set, the setting is persistent until changed again.

Parameters:
type - Set to "ASCII" to transfer plain text data and files; set to "BINARY" for all non plain text data and files; set to "DEFAULT" to have FTPeek resume making automatic implicit decisions on the transfer type.
Returns: 1 on success, ERROR on failure

FTPeek_UploadFile ( remoteDestPath ; localSourcePath )

Uploads a file to the remote server. If the upload directory structure does not exist on the remote server, it will be created as necessary. If the remote destination path is blank the file will be saved in the current working directory. If the remote file name is not specified ( remoteDestPath ends with a '/' slash character ), the remote file will be named the same as the local file. Only ASCII characters are supported for file names. The remoteDestPath path can be relative or absolute.

Please see the note on relative and absolute paths at the top of the page for more information. localSourcePath can be a system specific file path or a URL. ( ex. http://serverAddress/sample.mov ).

Here is an example of how to upload a file into the current working directory on the FTP server, retaining the same name as the source file:

 If[ FTPeek_UploadFile( "", "/Library/Desktop Pictures/Lines Blue.jpg" ) = "ERROR" ]
 	Show Custom Dialog[ "Could not upload file"; FTPeek_LastError ]
 End If
 

Parameters:
remoteDestPath - remote file or dir path to upload to; will be created if directory structure does not exist; if empty current working directory will be used
localSourcePath - local file path to upload
Returns: 1 on success, ERROR on failure

FTPeek_UploadFileFromContainer ( remoteDestPath ; containerToUpload )

Uploads container data as a file to the remote server, sets transfer type for this action to Binary unless specified otherwise in FTPeek_SetTransferType( type ). If the directory structure to upload to does not exist on the remote server, it will be created as necessary. If the remote file name is not specified ( remoteDestPath ends with a '/' slash character ), the remote file will be named the same as the local file. Only ASCII characters are supported for file names. The remoteDestPath path can be relative or absolute.

Parameters:
remoteDestPath - remote file or dir path to upload to; will be created if directory structure does not exist
containerToUpload - container data to upload
Returns: 1 on success, ERROR on failure

FTPeek_UploadFileFromField ( remoteDestPath ; textFieldToUpload { ; encoding } )

Uploads data from a non-container field as a file to the remote server. If the destination directory structure does not exist on the remote server, it will be created as necessary. If the remote file name is not specified ( remoteDestPath ends with a '/' slash character ), the remote file will be named Untitled.txt. Only ASCII characters are supported for file names. The remoteDestPath path can be relative or absolute. *Note that the default ftp transfer type is BINARY

Parameters:
remoteDestPath - remote file or dir path to upload to; will be created if directory structure does not exist, will use current directory if empty.
textFieldToUpload - text data to upload
encoding - optional text encoding. Some of the supported encodings are "ASCII", "ISO8859_1", "UTF8", "UTF-16", for more supported encodings consult Java supported encodings use the second column of the table as the encoding name.
Returns: 1 on success, ERROR on failure

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