. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectFTP Xtra
 DirectFTP Xtra

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleMacOS X CompatibleWindows Compatible   

DirectFTP Xtra™ Version 2.1.2 Documentation

Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 1997-2004.
Last updated: August 20th, 2004.

DirectFTP is a cross-platform, easy to use Scripting Xtra for Macromedia Director, Authorware and Shockwave, which provides implementation of the FTP protocol.

FTP stands for File Transfer Protocol. It provides a standard method for transferring files between different computers.

By using DirectFTP Xtra, Director, Authorware and Shockwave applications can log into an FTP server, get directory listings and files information, retrieve files, upload files and perform other file and directory operations, such as create, move, rename, append and delete files or directories.

DirectFTP Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8, 9 and X.

DirectFTP Xtra is Shockwave safe, so it can also be used with Shockwave 7 or later and when safety features in Director are turned on.
When the Xtra is in safe mode it can upload and download files through a built-in file selection dialog box from/to anywhere in the local machine, or without dialog boxes from/to the Shockwave support folder (DswMedia folder).

An auto downloadable Shockwave safe package of DirectFTP Xtra is also available. It is a compressed, small sized (about 30K) version of the Xtra, that can be downloaded automatically from a web site to the user's local machine whenever needed, and once installed provides Shockwave applications on the web with FTP capabilities.

DirectFTP Xtra is fully compliant with RFC 959.

Installation

Registration

Overview

Using DirectFTP Xtra

Sample Code

Functions Reference

New()
Forget()

ftpLogin()

ftpLogout()

ftpDir()
ftpRecvFile()
ftpSendFile()

ftpRecvText()
ftpSendText()

ftpRenameFile()

ftpDeleteFile()

ftpCreateDirectory()

ftpDeleteDirectory()

ftpCDUp()

ftpCWD()

ftpPWD()

ftpCommand()

ftpHelp()

ftpAbort()

ftpDone()

ftpBytesTransferred()

ftpBytesToBeTransferred()

ftpSetPort()

ftpMode()
ftpResult()

ftpErrorCode()
ftpErrorMessage()

Error Codes

History

Installation

DirectFTP Xtra has an authoring version, a run time version and an auto downloadable Shockwave safe package. The trial version only includes the
authoring version.

The authoring version is used by Director and/or Authorware authoring environment while developing your movie/presentation. It should be placed in your Director and/or Authorware "Xtras" folder.

The run time version is used when running your movie/presentation as a stand-alone application. It should be placed in a folder named "Xtras" that is inside the folder that contains the host projector/package. Alternatively, the run time version can be bundled in projectors/packages (in a similar way you bundle other Director\Authorware files).

The run time version is also used with the Authorware web player and can be bundled in the web package. When creating web packages in Authorware, please note that by default, Authorware will attempt to bundle the authoring version of the Xtra. You'd have to modify the application 'Publish Settings' in order to instruct Authorware to bundle the run time version instead of the authoring version.


The auto downloadable Shockwave safe package is used by Shockwave for Director. The package should be uploaded to your server from which it will automatically get downloaded and installed by your Shockwave movie, if needed.

The auto downloadable Shockwave safe package consists of the following files:

DirectFTP.w32 - Shockwave safe package for Windows
DirectFTP.ppc - Shockwave safe package for MacOS 8.x and 9.x
DirectFTP.carb - Shockwave safe package for MacOS X

Please note that Director requires that all the above files would be uploaded to your server even if you're only using the Xtra on one platform.

Once you have decided the location on your server where the auto downloadable packages will be placed, you should modify the "xtrainfo.txt"
file in the Director 7 or above folder accordingly. For example, if you uploaded the downloadable package to "http://www.myserver.com/packs" you should add the following line to "xtrainfo.txt".

[#namePPC:"DirectFTP", #nameW32:"DirectFTP.x32", #package:"http://www.myserver.com/packs/DirectFTP"]

Note that the above entry should consist of a single line in the "xtrainfo.txt" file.

Finally, add a reference to the auto downloadable package in your movie.
Open a movie that uses the DirectFTP Xtra. From the Modify->Movie->Xtras dialog in Director, select the DirectFTP Xtra in the list of Xtras. The "Download if needed" check box should now be enabled. (If it's not enabled, make sure the filename in "xtrainfo.txt" matches the actual filename of the Xtra.) Click on the check box and Director will load information from the package file for each platform and add it to the current movie.


IMPORTANT: The authoring, run time and Shockwave versions can not coexist in the same "Xtras" folder, so be sure to place the appropriate version in the appropriate folder. 

 

Registration

DirectFTP Xtra is a commercial product. 

Basically, there are 3 types of licenses: Single, Site and Corporate.

Single License: Entitles an organization to receive one copy of the licensed Xtra(s) which can only be used by a single developer on a single computer at any one time.

Site License: Entitles an organization to receive one copy of the licensed Xtra(s) which can be used by any number of developers on any number of
workstations within one site.

Corporate License: Entitles an organization to receive one copy of the licensed Xtra(s) which can be used by any number of developers on any
number of workstations within the entire corporation (multiple sites).

Important Notes:

  • A copy of the licensed Xtra includes the Authoring and freely distributable Runtime versions.
  • If you intend to distribute your application on both platforms (Windows and MacOS), or if you author your application on one platform and intend to deliver it on the other platform, you'd have to license both the Windows and MacOS versions of the Xtra.
  • Qualification for free and discounted upgrades and updates will be provided based on the registered e-mail address.
  • All licenses now include the Shockwave safe version of the Xtra along with an auto-downloadable Shockwave safe package which can be used with Shockwave movies on the web.
  • Single and Site licenses include free future upgrades and updates for minor revisions of the licensed Xtra(s), while Corporate license includes free future upgrades and updates for both major and minor revisions of the licensed Xtra(s).

Once you have licensed DirectFTP Xtra, you will be given a serial number.
Your DirectFTP Xtra serial number should be passed to the New() function when creating the DirectFTP Xtra instance in order to unlock the trial limitations. Once the Xtra is unlocked, trial warnings will no longer be presented, there will be no other limitations and the run-time and Shockwave versions of the Xtra will become activated.

Be sure to protect the call to New() so that your DirectFTP Xtra serial number would not become exposed to others. This can be done in a similar way you protect the rest of your application source code. If you intend to distribute your application with open source code then pass New() the number 0 as your serial number. This will switch the Xtra into a trial mode and you can instruct developers to change the number 0 with their serial number. Alternatively, you can protect just the appropriate New() calls in your code.

The New() function should be called before any of the other Xtra functions are called.

You can freely distribute the run time version and Shockwave safe package of DirectFTP Xtra with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

Note that if your Shockwave movie needs to run on both Windows and MacOS, you'd need to obtain a license for both the Windows and MacOS versions of the Xtra, in order to obtain both the Windows and MacOS Shockwave safe versions and their auto-downloadable Shockwave safe packages, along with serial numbers to activate them.

 

Overview

DirectFTP Xtra adds functions to Director and Authorware which provide applications with the ability to log into an FTP server, get directory listings and files information, retrieve files, upload files and perform other file and directory operations, such as create, move, rename, append and delete file or directory.

DirectFTP Xtra functions are divided into two categories, asynchronous and synchronous.

Synchronous functions return control to Director/Authorware as soon as they complete their task. They return an error code indicating whether their task was completed successfully. All of the synchronous DirectFTP functions return immediately, as they only retrieve information such as error codes, function results, transfer status, etc.

Asynchronous functions return control to Director/Authorware immediately, while continuing to perform their task in the background. They return an error code indicating whether their task was started successfully.

As an example, ftpRecvFile() function is Asynchronous, letting you download files(s) from an FTP server while at the same time perform other tasks, such as playing an animation indicating that a download operation is in progress, or calling other DirectFTP synchronous functions to track down the download status.

Once DirectFTP asynchronous function succeeds to create a background task, applications should frequently call ftpDone() to check its status. When the background task is completed, applications should call ftpErrorCode() to check whether the task was completed successfully, and ftpResult() to obtain further information about the completed task.

DirectFTP asynchronous functions might fail to create or start the background task. The two most common failures are due to insufficient memory or when another background task is already in progress. If an asynchronous function fails to start a background task it will return an appropriate error code. Applications should check for the asynchronous function result prior to calling ftpDone() to check the status of the background task.

Each instance of DirectFTP Xtra can manage one background task at a time. In order to have multiple background tasks at the same time, create multiple instances of DirectFTP Xtra and work with them simultaneously. 

 

Using DirectFTP Xtra

 

Following are step by step instructions on how an application can use the Xtra.

The next section summary all steps and includes a complete sample code.

Step 1 - Create a new instance of DirectFTP Xtra and store it for a later use. You will have to pass it as the first parameter to the other DirectFTP Xtra functions.

Lingo Sample Code for Director :

Set FTP = new (Xtra "DirectFTP",0)

Sample Code for Authorware :

FTP:=NewObject("DirectFTP",0)

JavaScript Sample Code for Director :

var FTP = new xtra("DirectFTP", 0)

Step 2 - Log into an FTP server.

Lingo Sample Code for Director :

ftpLogin (FTP, "my.ftp.server", "my.ftp.server", "my.ftp.server", "MyAccount")

Sample Code for Authorware :

CallObject (FTP, "ftpLogin", "my.ftp.server", "MyUserName", "MyPassword", "MyAccount")

JavaScript Sample Code for Director :

FTP.ftpLogin ("my.ftp.server", "MyUserName", "MyPassword", "MyAccount")

If ftpLogin() returns zero (no error), move on to the next step.

Step 3 - Frequently call ftpDone() to check the status of the login task which takes place in the background.

As soon as ftpDone() returns TRUE, call ftpErrorCode() to check whether the login operation was completed successfully or not. If ftpErrorCode() returns 0 (zero), the login was completed successfully, otherwise the returned value is a number indicating the error that has occurred. You can then call ftpErrorMessage() to get a human-readable string that describes the error.

Step 4 -

Once your application is logged into the FTP server, you can call any of the other DirectFTP functions such as ftpDir(), ftpRecvFile() and ftpSendFile().

Step 5 -

As soon as your application is done using the FTP server, log out by calling ftpLogout().

Lingo Sample Code for Director :

ftpLogout (FTP)

Sample Code for Authorware :

CallObject (FTP, "ftpLogout")

JavaScript Sample Code for Director :

FTP.ftpLogout ()

If ftpLogout() returns zero (no error), frequently call ftpDone() to check the status of the logout operation which takes place in the background.

Step 6 - To log into another FTP server, jump back to step 2, otherwise delete the DirectFTP instance that you've created in step 1.

Lingo Sample Code for Director : Set FTP=0

Sample Code for Authorware : DeleteObject(FTP)

JavaScript Sample Code for Director :var FTP = 0

Sample Code

This section includes a sample code for Director and Authorware. The sample code is based on the implementation steps which were described in the previous section.

The sample logs into an FTP server, change the working directory to "Samples" and downloads a file named "Image.jpg" from the server working directory to the local directory where the application is located.

Important Notes:

For the code to work properly, you'd need to provide New() with your DirectFTP Xtra serial number instead of the number 0. Otherwise, the Xtra will work in an evaluation mode, which is only functional for 14 days.

You'd also need to modify the FTP server address and login information as well as the file and directory names by changing the initialization of the 'FTPServer', 'MyUserName', 'MyPassword', 'WorkingDirectory' and 'RemoteFileName' variables, respectively.

Please also note that the following code waits in a repeat loop for ftpDone() to return true. We're using a repeat loop here for simplicity reasons. However, Director and Authorware ignore events and halt playback while in a repeat loop. As a result the application may appear to be hung while the function is executing and it may take the function more time to complete. Therefore it is recommended to wait for ftpDone() to return true while processing events and not in an empty repeat loop as we're demonstrating here.

Note that in case of any error, the sample function terminates and the DirectFTP Xtra will get deleted automatically since FTP is declared as a local variable.

After calling an asynchronous function, such as ftpLogin(), the sample checks for the function result in order to tell whether or not the background task was started successfully.  If the task is not started successfully, and appropriate error code will be displayed in the message window along with a generic error message describing the error. If the task is created successfully but fails to complete successfully, an appropriate error code is displayed in the message window along with the server log. 

Lingo Sample Code for Director :

Sample Code for Authorware :

JavaScript Sample Code for Director :

 

 

Functions Reference

 

Director: New ( Xtra "DirectFTP", integer SerialNumber )

Authorware: NewObject ("DirectFTP", integer SerialNumber)

Creates a new DirectFTP Xtra instance.

The returned value is a new instance of DirectFTP Xtra.

Parameter :

SerialNumber : DirectFTP Xtra Serial Number. If you are using the trial version, pass the number 0.

Returns : DirectFTP instance.

Remarks : This function is Synchronous.

 

Director: Forget ( object me )

Authorware: DeleteObject ( object me )

Deletes a DirectFTP Xtra instance.

Parameter :

object me : DirectFTP Instance.

Returns : None.

Remarks : This function is Synchronous.

In Director, you can also delete the DirectFTP Xtra instance by setting it to zero.

Since this function is synchronous, it might not return immediately if you dispose the instance while a background task is in progress (it calls ftpAbort() internally, in synchronous mode, and times out after 10 seconds).


You can get around the delay by calling ftpAbort() to abort the operation in progress gracefully before deleting the instance.

 

ftpLogin ( object me, string HostName, string UserName, string Password, string Account )

Connects to an FTP server and automatically logs in.

Parameters :

object me : DirectFTP Instance.

HostName : The IP address or name of the remote host. (the computer which the server is running on).

UserName : User name for FTP account (e.g. "anonymous").

Password : Password string for the user. This parameter will be ignored if no password is required by the server.

Account : The user's account, which may be required by some servers. This parameter will be ignored if no account is required by the server.

Returns : Error Code.

Remarks : This function is Asynchronous.

To connect to an FTP server through a proxy server, first call ftpSetPort() to set the communication port to the one the proxy server is listening on (if it is different than the default 21), then call this function and specify the proxy server address as the HostName parameter and the user name and FTP server address as the UserName parameter in the format required by the proxy server. A typical format for the UserName parameter when connected through a proxy server is 'UserName@ftp.server.com' .

ftpLogout ( object me )

Gracefully terminates FTP session with a server.

Parameter :

object me : DirectFTP Instance.

Returns : Error Code.

Remarks : This function is Asynchronous.

Upon completion of the created task the connection with the server will be terminated whether or not it succeeds in doing so gracefully. Therefore, if the function succeeds (i.e it returns 0), applications should assume that there is no connection with the server after the created task completes (ftpDone() returns true).

 

ftpDir ( object me, string Filter, integer MoreDetails )

Retrieve the remote directory listing.

Parameters :

object me : DirectFTP Instance.

Filter : Remote path and filename mask. Note that the wildcard expansion is dependent on the remote host and is not necessarily the same as MS DOS format. An empty string will provide listing of the current remote directory.

MoreDetails : Pass TRUE for long or FALSE for short form of listing. The short form only provides the name of the files, while the long form provides further information, such as files size and date. However, the format of the long form may vary from server to server.

 

Returns : Error Code.

Remarks : This function is Asynchronous. The result is available through ftpResult() when the ResultType parameter is set to 0.

 

ftpRecvFile ( object me, string RemoteFileName, string LocalFileName, integer TransferType, integer SourceFilePosition, integer TargetFilePosition )

Downloads a remote file to a local file. 

The function can also be used to resume a previous incomplete download.
The downloaded file can be appended to the local file, or overwrite it.

Parameters :

object me : DirectFTP Instance.

RemoteFileName : Remote file name.

LocalFileName : Full pathname of the local file.

TransferType : Transfer Type. Pass 65 for ASCII and 73 for IMAGE (binary).

SourceFilePosition : Transfer starting position, in bytes, of the remote file. 

TargetFilePosition : Transfer starting position, in bytes, of the local file. 

Returns : Error Code.

Remarks : This function is Asynchronous.

To download the specified remote file, overwriting the local file (if one exists), set the SourceFilePosition and TargetFilePosition parameters to zero.

To download the remote file and append it to the local file, set the SourceFilePosition parameter to zero and the TargetFilePosition parameter to the size of the local file, in bytes.

To resume a download from a specific position, set the SourceFilePosition and TargetFilePosition to the position (in bytes) from which to resume the download.

When the Xtra is in safe mode you can precede the LocalFileName parameter with the "|" character in order to download the specified file to the Shockwave support folder (DswMedia folder). For example, passing "|File.jpg" will have the Xtra save the downloaded file to a file named "File.jpg" that is located in the Shockwave support folder.

If no "|" is preceded the LocalFileName parameter, a dialog box would appear asking the user where to save the downloaded file. 

When using the built-in dialog box you can use the LocalFileName parameter to specify the default file type by passing its extension on Windows (without the dot) or four letter string specifying the file type signature on MacOS, or set it to an empty string to accept any file type. For example, pass "txt" for text files. You may also supply a message for the file type by specifying additional text after the extension and separating it by a "|", for example "txt|Text Files". If the selected file name does not end with the specified file type extension, the Xtra will automatically append one.

 

ftpSendFile ( object me, string LocalFileName, string RemoteFileName, integer TransferType, integer SourceFilePosition, integer TargetFilePosition )

Uploads a local file to a remote file. 

The function can also be used to resume a previous incomplete upload.
The uploaded file can be appended to the remote file, or overwrite it.

Parameters :

object me : DirectFTP Instance.

LocalFileName : Full pathname of the local file.

RemoteFileName : Remote file name.

TransferType : Transfer Type. Pass 65 for ASCII and 73 for IMAGE (binary).

SourceFilePosition : Transfer starting position, in bytes, of the remote file. 

TargetFilePosition : Transfer starting position, in bytes, of the local file. 

Returns : Error Code.

Remarks : This function is Asynchronous.

To upload the specified local file, overwriting the remote file (if one exists), set the SourceFilePosition and TargetFilePosition parameters to zero.

To upload the local file and append it to the remote file, set the SourceFilePosition parameter to zero and the TargetFilePosition parameter to the size of the remote file, in bytes.

To resume an upload from a specific position, set the SourceFilePosition and TargetFilePosition to the position (in bytes) from which to resume the upload.

When the Xtra is in safe mode you can precede the LocalFileName parameter with the "|" character in order to upload the specified file from the Shockwave support folder (DswMedia folder). For example, passing "|File.jpg" will have the Xtra upload the file "File.jpg" that is located in the Shockwave support folder.

If no "|" is preceded the LocalFileName parameter, a dialog box would appear asking the user where the file to be uploaded is located. 

When using the built-in dialog box you can use the LocalFileName parameter to specify the default file type by passing its extension on Windows (without the dot) or four letter string specifying the file type signature on MacOS, or set it to an empty string to accept any file type. For example, pass "txt" on Windows and "TEXT" on MacOS for text files. You may also supply a message for the file type by specifying additional text after the extension and separating it by a "|", for example "txt|Text Files".

If the RemoteFileName parameter is set to an empty string when running in a safe mode, the Xtra will set the remote file name to the name of the selected file.

 

ftpRecvText ( object me, string RemoteFileName, integer SourceFilePosition )

Downloads a remote file to a text string. 

The function can also be used to resume a previous incomplete download.

Parameters :

object me : DirectFTP Instance.

RemoteFileName : Remote file name.

SourceFilePosition : Transfer starting position, in bytes, of the remote file. 

 

Returns : Error Code.

Remarks : This function is Asynchronous. The result is available through ftpResult() when the ResultType parameter is set to 0.

To download the specified remote file, set the SourceFilePosition parameter to zero.

To resume a download from a specific position, set the SourceFilePosition to the position (in bytes) from which to resume the download.

 

ftpSendText ( object me, string Text, string RemoteFileName, integer TargetFilePosition )

Uploads a string variable and stores it in a remote file. 

The function can also be used to resume a previous incomplete upload.
The uploaded text can be appended to the remote file, or overwrite it.

Parameters :

object me : DirectFTP Instance.

Text : A string specifying the text to store in the remote file.

RemoteFileName : Remote file name.

TargetFilePosition : Transfer starting position, in bytes, of the remote file.

 

Returns : Error Code.

Remarks : This function is Asynchronous. The result is available through ftpResult() when the ResultType parameter is set to 0.

To upload the specified text, overwriting the remote file (if one exists), set the TargetFilePosition parameter to zero.

To upload the text and append it to the remote file, set the TargetFilePosition parameter to the size of the remote file, in bytes.

To resume an upload from a specific position, set the TargetFilePosition to the position (in bytes) from which to resume the upload.

 

ftpRenameFile ( object me, string RemoteFileName, string NewRemoteFileName )

Renames a file on the server.

Parameters :

object me : DirectFTP Instance.

RemoteFileName : Pathname of file to rename.

NewRemoteFileName : New pathname for the file.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

 

ftpDeleteFile ( object me, string RemoteFileName )

Deletes a file on the server.

Parameters :

object me : DirectFTP Instance.

RemoteFileName : Pathname of file to delete.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

 

ftpCreateDirectory ( object me,string RemoteDirectoryName )

Creates a directory on the FTP server.

Parameters :

object me : DirectFTP Instance.

RemoteFileName : Pathname of directory to create.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

 

ftpDeleteDirectory ( object me,string RemoteDirectoryName )

Removes a directory on the FTP server.

Parameters :

object me : DirectFTP Instance.

RemoteFileName : Pathname of directory to delete.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

ftpCDUp ( object me )

Changes the current remote working directory to its parent directory.

Parameter :

object me : DirectFTP Instance.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

 

ftpCWD ( object me, string PathName )

Changes the current working directory on the server to the specified directory.

Parameters :

object me : DirectFTP Instance.

PathName : Directory location desired.

 

Returns : Error Code.

Remarks : This function is Asynchronous.

 

ftpPWD ( object me )

Returns the name of the current working directory on the server.

Parameter :

object me : DirectFTP Instance.

 

Returns : Error Code.

Remarks : This function is Asynchronous. The result is available through ftpResult() when the ResultType parameter is set to 0.

 

ftpCommand ( object me, string Command )

Sends an FTP command string to the server.

Parameters :

object me : DirectFTP Instance.

Command : FTP protocol command string.

 

Returns : Error Code.

Remarks : This function is Asynchronous. The result is available through ftpResult() when the ResultType parameter is set to 1.

This function can be used to send FTP commands to the host server, bypassing the Xtra functions. It may be useful if the FTP host is not responding as expected by the protocol, and you wish to troubleshoot the operation, or in cases where the FTP host provides additional functionality not implemented by the Xtra.

Data transfer can not be started with this function.

 

ftpHelp ( object me, string Command )

Retrieves helpful information from the remote server.

Parameters :

object me : DirectFTP Instance.

Command : FTP Command help is requested on or empty string for a global help.

 

Returns : Error Code.

Remarks : This function is Asynchronous. The result is available through ftpResult() when the ResultType parameter is set to 1.

 

ftpAbort ( object me )

Requests from the current asynchronous task to gracefully aborts itself and any associated transfer of data.

Parameter :

object me : DirectFTP Instance.

Returns : Error Code.

Remarks : This function is Synchronous.

While the function returns immediately the current asynchronous task may not abort immediately. After calling this function applications should wait for the task to complete (i.e ftpDone() returns true) then check for errors using ftpErrorCode(). After the task completes error 9003 will be returned if it was aborted successfully. Otherwise, the abort request had no effect on the task because the task was completed prior to receiving it.

Note that if error 9003 is returned the task may be partially completed.

Aborting a task does not terminate the connection with the server except when aborting ftpLogin() or ftpLogOut().

Under rare circumstances the function may not be able to abort the task. If the task is not aborted after a reasonable amount of time applications can brutally abort it and close the connection with the server by deleting the Xtra instance.

 

ftpDone ( object me )

Returns TRUE if the last asynchronous task has been completed and FALSE if not.

Parameter :

object me : DirectFTP Instance.

 

Returns : Error Code.

Remarks : This function is Synchronous.

 

ftpBytesTransferred ( object me )

Returns the number of bytes that has been transferred in the last/current file or directory listing task.

Parameter :

object me : DirectFTP Instance.

 

Remarks : This function is Synchronous.

 

ftpBytesToBeTransferred ( object me )

Returns the total length, in bytes, of the last/current file being transferred.

Parameter :

object me : DirectFTP Instance.

 

Remarks : This function is Synchronous.

Applications must not depend on the returned value as the file size may not be reported by all servers. If the file size is not available the function will return -1. Applications must use ftpDone() to check whether a file transfer was completed and not by comparing ftpBytesTransferred() result to the result of this function. 

 

ftpSetPort ( object me, integer Port )

Sets the port which will be used for the FTP communication. The default is 21. Changes will take affect on the next ftpLogin() call.

Parameters :

object me : DirectFTP Instance.

Port : New port number.

Remarks : This function is Synchronous.

 

ftpMode ( object me, integer Mode )

Sets the FTP communication mode. The default is non passive transfer mode.

Parameters :

object me : DirectFTP Instance.

Mode : Can be one of the following values:

0 - Non-passive transfer mode.
1 - Passive transfer mode.

Remarks : This function is Synchronous.

 

ftpResult ( object me, integer ResultType )

Returns the text result obtained by the last completed FTP task.

The ftpResult() function should be called after ftpDone() indicates that the task is completed and before the next operation starts.

Parameter :

object me : DirectFTP Instance.

ResultType : Type of text result to retrieve. Pass 1 to retrieve the FTP messages sent by the server as a result of the last completed FTP task. Pass 0 to retrieve the directory listing as a result of the last completed ftpDir() or ftpPWD() calls, or the text retrieved by ftpRecvText() call.

Remarks : This function is Synchronous.

 

ftpErrorCode ( object me )

Returns an error code indicating the last error that has occurred.

Parameter :

object me : DirectFTP Instance.

 

Returns : Error Code.

Remarks : This function is Synchronous.

 

ftpErrorMessage ( object me, integer ErrorCode )

Returns a human-readable string that describes the specified error that has occurred. 

If no error string is available for the specified error, an empty string will be returned.

Parameter :

object me : DirectFTP Instance.

integer ErrorCode : Number of the error to translate into an error message.

 

Returns : Error Message.

Remarks : This function is Synchronous.

 

Error Codes

 

0: Success (no error).

FTP Errors:

9000: Not enough memory.
9001: Unexpected FTP reply.
9002: A task is already in progress.
9003: Aborted by user.
9004: FTP timed out.

 


331: User name okay, need password.
332: Need account for login.
350: Requested file action pending further information.
421: Service not available, closing control connection.
425: Can't open data connection.
426: Connection closed; transfer aborted.
450: Requested file action not taken.
451: Requested action aborted: local error in processing.
452: Requested action not taken: insufficient storage space in system.
500: Syntax error, command unrecognized
501: Syntax error in parameters or arguments.
502: Command not implemented.
503: Bad sequence of commands.
504: Command not implemented for that parameter.
530: Not logged in.
532: Need account for storing files.
550: Requested action not taken: file unavailable.
551: Requested action aborted: page type unknown.
552: Requested file action aborted: exceeded storage allocation.
553: Requested action not taken: file name not allowed.

TCP Errors:

10049: Cannot assign requested address.
10051: Network is unreachable.
10053:
Software caused connection abort.
10054: Connection reset by peer.
10056: Socket is already connected.
10057: Socket is not connected.
10060: Connection timed out.
10061: No connection could be made because the target machine actively refused it.
10065: Host is unreachable.
10091:
Network subsystem is unavailable.
11001: Host not found.
11004: Valid name, no data record of requested type.

File Errors:

2: The system cannot find the file specified.
3: The system cannot find the path specified.
5: Access is denied.
6: Invalid file handle.
32: The process cannot access the file because it is being used by another process.
123: The filename, directory name, or volume label syntax is incorrect.

The DirectFTP Xtra functions might return additional platform specific error codes that are not listed above.

 

History

7.2.03 - Version 2.1.2 released.

* When the Xtra is in safe mode it will now accept files from any local dswMedia folder without the user consent.

* Minor fixes and improvements.

6.17.02 - Version 2.1 released.

* The Xtra is now fully compatible with MacOS X.

* Additional sample code for both Director and Authorware is now included in the Xtra documentation.

* ftpMode() was added providing support for passive mode transfers.

* Minor fixes and improvements.

10.01.01 - Version 2.02 released.

* When the Xtra is in safe mode it can now upload/download files to/from the Shockwave support folder (DswMedia folder) without displaying a dialog box.

* ftpRecvFile() will now overwrite files properly.

* Error # 9004 was added

7.04.01 - Version 2.01 released.

* ftpSendFile() - If the RemoteFileName parameter is set to an empty string when running in a safe mode, the Xtra will set the remote file name to the name of the selected file.

* Fixed a problem in the Shockwave safe version when running under Netscape on MacOS 9.

10.06.00 - Version 2.0 released.

- The new version introduces new features, and is now Shockwave safe and fully compatible with both Windows and MacOS.

2.10.99 - Version 1.0 released.



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 9/18/2004 8:36:13 AM.