FTP.UCD & FTP.U32
May 1, 1997

A 16-bit and 32-bit FTP UCD for Authorware 4.0

Copyright (c) 1997 Macromedia.  All rights reserved.

This software is provided for no charge and, accordingly,
Macromedia makes no warranties, express or implied, regarding
this product or any service or item offered, sold or otherwise
provided to you as a result of your use of this product.
Macromedia specifically disclaims any warranties,
merchantability and fitness for a particular purpose regarding
this product or any such service or item.  Macromedia makes no
warranty that the information contained in this product is
complete or accurate.  Macromedia does not assume and hereby
disclaims any liability to any person or entity for any loss or
damages (including, without limitation, special, indirect,
incidental or consequential damages) caused by errors or
omissions in the information contained in the product, your
installation and/or use of the product and/or any service or
item provided to you as a result of your use of this product,
regardless of whether resulting from negligence, accident of any
other cause whatsoever.

Overview
========

FTP services are provided to the Windows version of Authorware
4.0 as a 16-bit and 32-bit UCD.  Each of the functions
supported by the FTP UCD are listed below:

FtpOpen
FtpClose
FtpConnect
FtpDisconnect
FtpRetrieve
FtpStore
FtpAppend
FtpDelete
FtpRename
FtpList
FtpNameList
FtpGetWorkingDir
FtpChangeWorkingDir
FtpChangeParentDir
FtpRemoveDir
FtpMakeDir
FtpAbort
FtpStatus
FtpResult

Most of these functions are asynchronous, meaning that
Authorware will not wait for the operation to complete before
proceeding. If the operation is not complete, the function will
return a status value of 1.  To determine when the FTP
operation initiated by the function is complete, the function
FtpStatus should be periodically called.  When the FTP
operation is complete, a call to FtpStatus will return a value
of 0 to indicate the operation completed OK or a negative error
value if the operation encountered an error.


FTP Function Return Values
==========================

Most of the FTP functions return a status value that indicates
the status of the function call.  These status values are
described below.

0 - Status OK

This return value indicates that the function completed
without any errors.

1 - Status Waiting

This return value indicates that the function is still waiting
to be completed.

-1 - Status Busy

This return value indicates that the FTP operation cannot be
performed because another FTP operation is still in progress.
The current FTP operation must be finished or aborted before a
new FTP operation can be initiated.

-2 - Status Connected

This return value indicates that an FTP connection is already
established.  This is a possible error value for the function
FtpConnect().

-3 - Status Disconnected

This return value indicates that an FTP connection is NOT
established or has been disconnected.  This is an possible
status value for all functions except for FtpConnect().

-4 - Status FTP Error

This return value indicates the FTP server returned a negative
reply indicating the FTP operation failed.

-5 - Status FTP ID Invalid

This return value indicates the FTP ID passed into the
function is invalid.

-6 - Status FTP ID Closed

This return value indicates the FTP ID passed into the
function is an FTP ID that is not open or that has been
closed.

-7 - Status Bad String Value

This return value indicates that a string value passed into
the function is invalid.  Usually this indicates a string
value is empty or too long.

-8 - Status Out Of Memory

This return value indicates that the FTP UCD is no longer able
to allocate memory from the operating system.

-9 - Status Out Of Resources

This return value indicates that the FTP UCD is no longer able
to allocate FTP resources.  This usually occurs when too many
FTP sessions have been opened without being closed.

-10 - Status WinSock Error

This return value indicates that WinSock error occurred which
prevented the FTP operation from completing.

-11 - Status WinSock Init Failed

This return value indicates that the WinSock DLL could not be
initialized.  This usually occurs if WinSock is improperly
installed on the computer.

-12 - Status WinSock Version Invalid

This return value indicates that the WinSock DLL version is
not supported by this FTP UCD.

-13 - Status Windows Create Failed

This return value indicates that the communication window used
by the UCD could not be created.  This is usually due to low
memory conditions.

-14 - Status File Open Failed

This return value indicates that the local file could not be
opened for reading or writing.

-15 - Status Server Invalid

This return value indicates that the server specified could
not be found on the Internet.


FTP Function Descriptions
=========================

Each of the functions provided by the FTP UCD are described
below:

FtpOpen
=======

ftpID := FtpOpen( )

Allocates and initializes resources for the FTP session. It
must be the first function called by the client Authorware
application. Returns the handle to the FTP session or zero if
an error occurred.

Returned value:

positive  FTP session ID that must be passed to other functions.
negative  Error occurred in function.


FtpClose
========

status := FtpClose( ftpID )

Closes the FTP session.  It must be called after all other
functions to free the resources allocated for the FTP session.
The handle to the FTP session is no longer valid after calling
this function.

Returned status values:

0         Function OK.
negative  Error occurred in function.



FtpConnect
==========

status := FtpConnect( ftpID, server, port, userID, password )

Establishes an FTP connection to a server using the port,
userID, and password specified.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Connect operation is waiting.
0         Connect operation completed OK.
negative  Error occured.


FtpDisconnect
=============

status := FtpDisconnect( ftpID )

Quits a currently active FTP connection.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Disconnect operation is waiting.
-3        Disconnect operation completed OK.
negative  Error occured.


FtpRetrieve
===========

status := FtpRetrieve( ftpID, remotePath, localPath )

Retrieves the file on the server specified by the remote path.
The local path specifies the name of the file on the local
file system.  The file is always transferred as a binary
image.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Retrieve operation is waiting.
0         Retrieve operation completed OK.
negative  Error occured.


FtpStore
========

status := FtpStore( ftpID, remotePath, localPath )

Stores the file on the server specified by the remote path.
The local path specifies the name of the file on the local
file system.  The file is always transferred as a binary
image.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Store operation is waiting.
0         Store operation completed OK.
negative  Error occured.


FtpAppend
=========

status := FtpAppend( ftpID, remotePath, localPath )

This function transfers the specified file from the local file
system to the remote server.  If the file specified by the
remote path exists at the server site, then the data shall be
appended to that file; otherwise the file specified by the
remote path shall be created at the server side.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Append operation is waiting.
0         Append operation completed OK.
negative  Error occured.


FtpDelete
=========

status := FtpDelete( ftpID, remotePath )

This function deletes the specified file from the server.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Delete operation is waiting.
0         Delete operation completed OK.
negative  Error occured.


FtpRename
=========

status := FtpRename( ftpID, fromName, toName )

This function renames the file on the remote server 'fromName' to
'toName'.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Rename operation is waiting.
0         Rename operation completed OK.
negative  Error occured.


FtpList
=======

status := FtpList( ftpID, remotePath )

This function causes a file list to be sent from the server.
If the pathname specifies a directory or other group of files,
the server should transfer a list of files in the specified
directory.  If the pathname specifies a file then the server
should send current information on the file.  A null argument
implies the user's current working or default directory.  The
data transfer is over the data connection in type ASCII.

Since the information on a file may vary widely from system to
system, this information may be hard to use automatically in a
program, but may be quite useful to a user.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         List operation is waiting.
0         List operation completed OK.
negative  Error occured.


FtpNameList
===========

status := FtpNameList( ftpID, remotePath )

This function causes a directory listing to be sent from the
server.  The pathname should specify a directory or other
system-specific file group descriptor; a null argument implies
the current directory.  The server will return a stream of
names of files and no other information.

The data will be transferred in ASCII over the data connection
as valid pathname strings separated by CR characters.  This
command is intended to return information that can be used by a
program to further process the files automatically.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Name list operation is waiting.
0         Name list operation completed OK.
negative  Error occured.


FtpGetWorkingDir
================

status := FtpGetWorkingDir( ftpID )

This function gets the full path of the current working
directory.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Get working directory operation is waiting.
0         Get working directory operation completed OK.
negative  Error occured.


FtpChangeWorkingDir
===================

status := FtpChangeWorkingDir( ftpID, remotePath )

This function allows the calling application to work with a
different directory for file storage or retrieval.  The
argument is a remote path specifying a directory or other
system dependent file group designator.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Change working directory operation is waiting.
0         Change working directory operation completed OK.
negative  Error occured.


FtpChangeParentDir
==================

status := FtpChangeParentDir( ftpID )

This function is a special case of FtpChangeWorkingDir and is
included to simplify the implementation of programs having to
deal with different server syntaxes for naming the parent
directory.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Change to parent directory operation is waiting.
0         Change to parent directory operation completed OK.
negative  Error occured.


FtpRemoveDir
============

status := FtpRemoveDir( ftpID, remotePath )

This command causes the directory specified by the remote path
to be removed as a directory (if the path is absolute) or as a
subdirectory of the current working directory (if the path is
relative).

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Remove directory operation is waiting.
0         Remove directory operation completed OK.
negative  Error occured.


FtpMakeDir
==========

status := FtpMakeDir( ftpID, remotePath )

This function causes the directory specified by the remote
path to be created as a directory (if the path is absolute) or
as a subdirectory of the current working directory (if the path
is relative).

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Make directory operation is waiting.
0         Make directory operation completed OK.
negative  Error occured.


FtpAbort
========

status := FtpAbort( ftpID )

Aborts the current asynchronous function.  Does nothing if an
asynchronous function is not waiting.

This is an asynchronous function.  If the return value is 1,
then FtpStatus must be called to determine when the function
is complete.

Returned status values:

1         Abort operation is waiting.
0         Abort operation completed OK.
negative  Error occured.


FtpStatus
=========

status := FtpStatus( ftpID )

Returns the status of the last function.  Normally this
function is called to determine when the last function has
asynchronously completed.

Returned status values:

1         Current operation is waiting.
0         Current operation completed OK.
negative  Error occured in current operation.


FtpResult
=========

string := FtpResult( ftpID )

Returns the result string of completed FTP operation. This
call should only be made once an FTP operation has been
completed. This function should be used with FtpGetWorkingDir,
FtpList and FtpNameList to get the result of the corresponding
operation.

---------------------------------------------------------------
FTP UCD Implemented by Mike Thompson - mthompson@macromedia.com
