360Works FTPeek 4.04 User Guide

Installation

Requirements

FileMaker version 12 or higher.

When 360Plugins are intialized for the first time, they will automatically download all required support files

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, please send an email to support@360works.com

WebDirect Install (FMS 13+)

Install plug-ins for use with WebDirect by dragging the appropriate plugin to FileMaker Server/Web Publishing/publishing-engine/cwpc/Plugins

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 or WIN(.fmx) 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 call 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, you can follow the same procedure as detailed above for custom web publishing. However, in FileMaker Server 12.0v2 and later, custom web publishing now runs as a 64-bit application and requires the 64-bit version of the plugin 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.

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 (.fmx64 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. Restart the FileMaker Script Engine by opening Terminal (Mac) or CMD (Windows) and type the command: fmsadmin restart fmse -y . Note: On Windows you may need to change directories to where the fmsadmin utility is located in order to run this command. By default this is located at "C:\Program Files\FileMaker\FileMaker Server\Database Server" This step is not necessary if using Powershell
  3. Go to Configuration -> Database Server->Server Plug-ins and check the box that says 'Enable FileMaker Server to use plug-ins'(if it is not already checked), 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 AutoUpdate much easier. This file includes pre-configured plugin files which you can place on your server, and an AutoUpdate script for each of our plugins which you can paste into your own solution.

You can get the AutoUpdate360Works file here 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: 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. You will need to call the register function at the beginning of any script that is going to call plugin functions. This will ensure that you do not get demo mode errors.

Product Wiki

This is the main documentation for the plugin. However, we also maintain a documentation Wiki that contains additional information for a lot of our products. You can find that page here

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!

Error Handling/Reporting

When calling plugin functions as script steps, you will handle errors in the same manner you would any other FileMaker script step. Please see the FileMaker documentation for how to handle errors appropriately. Generally, if there is an error, our plugins will return an error code of 1552 when Get(LastError) is called. However, some plugin functions will return different error codes. If a function can return an error code other than a 1552, it will be documented with the description of the function below. In addition to the error code, you can also get the description of the error by calling Get(LastExternalErrorDetail). Please note that if you are using FileMaker 19.6 or later then this function has been renamed to Get(LastErrorDetail)

You can also call our functions in a calculation dialog. In this case, error handling is done differently. If you decide to call plugin functions in a calculation dialog and you want to capture errors, see this page page for instruction on how to do so

Examples

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.

Dropbox / OAuth logins

Here is an example illustrating how a login script would work for DropBox. It assumes there is a related table occurrence named 'currentUserRecord' where the login token for the current user can be read and written:

 Set Variable[ $$state; Get( UUID ) ]
 Set Variable[ $loginUrl; FTPeek_DropboxGetLoginUrl( currentUserRecord::DropBoxToken; $$state ) ]
 If[ IsEmpty( $loginUrl ) ]
   #User tokens are still valid from last login; can auto-login without being prompted
   Set Field[ currentUser::DropBoxToken; FTPeek_ConnectDropbox( currentUserRecord::DropBoxToken; $$state ) ]
   #Proceed to make normal calls to the plug-in to list, read, and write files on DropBox
 Else
   #Need to redirect user to loginUrl
   Open URL[ $loginUrl ]
   #After they login, they should click a button in FileMaker that runs the post-login script, below
   #You can also show a dialog to pause the script and wait for them to press continue, instead of running a separate script.
 End If
Post-login script. Make sure $$state is the same UUID that was passed into the FTPeek_DropboxGetLoginUrl function 
 Set Field[ currentUser::DropBoxToken; FTPeek_ConnectDropbox( currentUserRecord::DropBoxToken; $$state ) ]
 #Proceed to make normal calls to the plug-in to list, read, and write files on DropBox

Function Summary

Function Detail

FTPeekSetWindowManagement ( windowManagement )

FTPeek_ChangeDir ( remoteDir )

Changes the working directory to a specified directory. The remoteDir path can be relative or absolute.
 #Change dir using relative path. Current working directory is "/uploaded"
 FTPeekChangeDir[Remote Dir:"FTPeek"]//working dir is now "/uploaded/FTPeek"
 

 #Change dir using absolute path. Current working directory is "/uploaded"
 FTPeekChangeDir[Remote Dir:"/FTPeek"]//working dir is now "/FTPeek"

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.
 #Root directory is "/" Current working directory is /uploaded/FTPeek
 FTPeek_ChangeDirRoot // current directory is now "/"

Returns: 1 on success, ERROR on failure

FTPeek_ChangeDirUp ( )

Changes the working directory to the parent of the current directory.
 # Current directory "/uploaded/FTPeek"
 FTPeek_ChangeDirUp // current directory is now "/uploaded"

Returns: 1 on success, ERROR on failure

FTPeek_ChooseFile ( { initialPath ; fileType ; title } )

Pops up a file chooser dialog.
 # opens a File Chooser, showing only files, Window title is "Choose a file to upload"
 Set Variable[$choose; Value: FTPeek_ChooseFile("/User/SomeUser/Desktop";"files";"Choose a file to upload"]

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.

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: File path of the selected file

FTPeek_ConnectDropbox ( tokenStore { ; state } )

Call this function AFTER FTPeek_DropboxGetLoginUrl, and after sending the user to the login URL (if a URL was returned by the GetLoginUrl function), or immediately (if a blank result was returned by the GetLoginFunction). After this function completes successfully, you should store the result in a user record for future logins, and then you can proceed to make normal function calls to interact with DropBox.

There is an OAuth example login process at the top part of this documentation.

Parameters:
tokenStore - Every time this function is called, the result should be stored in the database and passed in as this parameter on the next call to this function.
state - This should match the random UUID that was passed to the ,FTPeek_DropboxGetLoginUrl, function.

FTPeek_ConnectFTP ( Host ; Username ; Password { ; ActiveMode ; Encoding ; LoggingLevel ; Timeout ; ... } )

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

 FTPeek_ConnectFTP[Host:"ftp.mysite.com" ;Username:"username" ;Password:"password" ;ActiveMode:"true";Encoding:"UTF8"]

Logging level

 FTPeek_ConnectFTP[Host:"ftp.mysite.com" ;Username:"username" ; Password:"password"; ActiveMode: ; Encoding: ; Logging Level: "DEBUG"]

Timeout

Set a request timeout in milliseconds (e.g., 30000 = 30 seconds)
 FTPeek_ConnectFTP[Host:"ftp.mysite.com" ;Username:"username" ;Password:"password" ;ActiveMode:"true";Encoding:"UTF8";Logging Level: ; 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 { ; ActiveMode=false ; Encoding=utf-8 ; LoggingLevel=OFF ; Timeout=60 ; ValidateServerCertificate=1 ; ImplicitFTPS=0 ; StartWithClearDataChannels=0 ; DisableDataSslClosure=0 ; DisableControlWaitOnClose=0 ; DisableSslClosure=0 ... } )

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: 

 FTPeek_ConnectFTPS[Host:"ftps.mysite.com" ; Username:"username" ;Password:"password"]

No server certificate validation

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

FTPS implicit

Use the optional arguments to use implicit FTPS mode "ImplicitFTPS=true".
 Set Variable[$result; Value: FTPeek_ConnectFTPS("ftps.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; Value: FTPeek_ConnectFTPS("ftps.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". 

 Set Variable[$result; Value: FTPeek_ConnectFTPS("ftps.mysite.com";"username";"password" ;"ActiveMode=true";"encoding=UTF8")]

SSL flags

 Set Variable[$result; Value: FTPeek_ConnectFTPS("ftps.mysite.com" ;"username" ;"password" ;"DisableDataSslClosure=true" ;"DisableSslClosure=true")]

Logging level

 Set Variable[$result; FTPeek_ConnectFTPS("ftps.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_ConnectS3 ( regionAndBucket; accessKey; secretKey )

Connects to Amazon S3, which you can then upload, download, and list files from like any other FTP Server.
 FTPeek_ConnectS3(Region And Bucket:"us-east-1/static.360works.com";Access Key:"AmazonAccessKeyHere";Secret Key:"AmazonSecretKeyHere")]

Parameters:
regionAndBucket - : This is the name of an S3 region, followed by a slash and the bucket name. For example, to access the bucket static.360works.com in the Virginia region, you would specify 'us-east-1/static.360works.com'. Value values are: ,
    , ,
  • ,us-east-1 (Virginia),
    • , ,
  • ,us-west-1 (California),
    • , ,
  • ,us-west-2 (São Paulo),
    • , ,
  • ,eu-west-1 (Ireland),
    • , ,
  • ,eu-central-1 (Frankfurt),
    • , ,
  • ,ap-southeast-1 (Singapore),
    • , ,
  • ,ap-southeast-2 (Sydney),
    • , ,
  • ,ap-northeast-1 (Tokyo),
    • , ,
accessKey - Your Amazon Web Services (AWS) access key
secretKey - Your Amazon Web Services (AWS) secret key
Returns: 1 on success, ERROR on failure

FTPeek_ConnectSFTP ( host ; hostPublicKey ; username ; password { ; LoggingLevel=true ; PublicKeyAuth=1 ; PrivateKeyPath=path/to/key ; ChallengePassword=password ; ... } )

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. 

 FTPeek_ConnectSFTP[Host: "sftp.mysite.com" ;Host Public Key:"####Public Key####" ;Username:"username" ;Password:"password"]

Logging level

 Set Variable[$result; Value: FTPeek_ConnectSFTP("sftp.mysite.com" ;"####Public Key####" ;"username" ;"password";"LoggingLevel=DEBUG")]

In the above example FTPeek_ConnectSFTP is using public key authentication to connect to the server by passing in PublicKeyAuth=1 and PrivateKeyPath=/Users/username/.ssh/id_rsa as additional arguments. The password parameter in this case refers to the encryption password of the id_rsa file. In the event that your private key file does not have an encryption password you should pass in an empty string "" as the password parameter. If you are having trouble connecting with this method please ensure that your SSH server is configured to allow public key authentication, and that the client's public key is listed as an authorized key in the correct location on the server.

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 ,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_CreateDownloadLink ( filePath { ; immediateDownload=true } )

Takes in the filePath to a Dropbox file and returns a public, shareable link. Clicking this link will cause a user's browser to begin downloading the file. The optional parameter immediateDownload can be set to false which will force users to log into a Dropbox account before initiating the download. By default, immediateDownload is set to true which triggers the immediate file download.

Parameters:
filePath - - The filePath to the file for which a shareable link will be created.

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: 

 FTPeek_DeleteDir[ Remote Dir: "Empty/Directory"] //relative path example ]
 FTPeek_DeleteDir( Remote Dir: "/home/files/Non empty directory" ; Recursive Flag: "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 ; Value: FTPeek_DeleteFile( "remoteFiles.txt" ) ]
 Set Variable [ $deleteFiles ; Value: 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.
 FTPeek_DeleteLocal( Local File: "/Users/username/Desktop/upload.gif" ) ]
 FTPeek_DeleteLocal( Local File: "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.
 FTPeek_DownloadFile(Remote Source Path: "path/to/remote/file";Local Dest Path: "path/to/local/destination";New Local File Name: "myfile.txt"]

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_DropboxGetLoginUrl ( tokenStore { ; state } )

When logging into DropBox, which requires OAuth authentication, you should call this function first. This function will examine the tokenStore provided and return one of:

There is an OAuth example login process at the top part of this documentation.

Parameters:
tokenStore - Can be empty the first time you call this. After a successful login, you should store the tokenStore returned from ,FTPeek_ConnectDropbox, and pass it in the next time this function is called. In most cases this will skip the need for the user to have to log in.
state - A random UUID. Store this UUID so that it can be passed as a parameter to ,FTPeek_ConnectDropbox,. The state parameter is required if calling the function on FileMaker Server, or with a Perform Script on Server, but it is legal to leave the state parameter empty if the plugin is running on FileMaker Pro.
Returns: a login url, an empty result, or ERROR.

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. 
 Set Field[myTable::Results; Value: FTPeek_ExecuteCommand("some valid command here")

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/.
 Set Variable[#currentDir; Value: FTPeek_GetCurrentDir()]

Returns: path of current working directory

FTPeek_GetFileInfo ( remotePath; infoType )

Gets information about the selected file.
 Set Variable[$info;Value: FTPeek_GetFileInfo("path/to/file";"size")//returns the size of the 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. 
     Set Variable[$list; Value: FTPeek_GetFileList]//returns content of current working directory
 

     Set Variable[$list; Value: FTPeek_GetFileList("/tmp"]//returns content of /tmp directory

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.
 Set Field[Settings::PubKey; FTPeek_GetPublicKey("sftp.mysite.com")]

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.
 If [FTPeek_isConnected = 0] //if not connected
 FTPeek_ConnectFTP[Host:"ftp.mysite.com";Username:"username";Password:"password"]

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

If you are calling plugin functions as script steps then you should not use this function. Instead capture errors the same way you would with native FileMaker script steps. See the Error Handling/Reporting section above for more explanation

Returns: Error text, or

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: 

 FTPeek_MakeDir[ Remote Dir: "New Folder"] //relative path example
 FTPeek_MakeDir[ Remote Dir: "/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 or folder on the remote server. The from and to paths can be relative or absolute. This can be used to move a file or folder to a new directory. Directories that do not exist will be created automatically if your user's permissions allow it.
 FTPeek_Rename(From:"/path/to/file.txt";To:"/path/to/newFile.txt"]

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 { ; recursive=true } )

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'.
args - an optional parameter which states whether or not files will be returned recursively.
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 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. This is a boolean value so make sure you do not put the parameter in "". NOTE:This will only suppress error dialogs when plugin functions are called as part of a calculation. If you are calling plugin functions as script steps ( available in FM 16+) then you will need to use the native FileMaker function Set Error Capture On/Off
     Set Variable[$errCap; Value: FTPeekSetErrorCapture(True)] //turns on error capture

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.
 FTPeek_SetShowProgress[Show Progress Flag: 0 ]//turns off progress bars

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.
 FTPeek_SetTransferType[Type: "Binary"]//sets the transfer type to Binary
 

 FTPeek_SetTransferType[Type:"ASCII"]//sets transfer type to ASCII

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: 

 FTPeek_UploadFile( Remote Destination Path""; Local Source Path: "/Library/Desktop Pictures/Lines Blue.jpg"]

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. 
 FTPeek_UploadFileFromContainer ( Remote Dest Path: "/path/for/upload" ; Container to Upload: myTable::myContainer )]

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
 FTPeekUploadFileFromField(Remote Dest Path:"path/to/upload/myFile.txt"; Text Field to Upload: myTable::myTextField]

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