The following is a list of functions available after installation of ShockFiler Xtra.

sf_Register([1111,2222,3333]) -global function, used to register Xtra. It can be called at any time, usually when the Director movie starts. Unregistered versions of the Xtra are fully functional for evaluation purposes, but will display a warning the first time you use a method other than sf_Register.

ShockFiler serial number are strings, and have the generic format SFLXX-1111-2222-3333, where XX is the major Xtra version. In order to protect your serial number from being included as a string in your Director projectors or dcr movies, the sf_Register function requires only the three groups of numbers 1111, 2222 and 3333 inside a Director list. Leading zeroes do not need to be entered.

An example: if your serial number is SFL20-0123-4567-0089 then you should register using the following command, usually on a startmovie handler:

Lingo:

sf_Register([123, 4567,89])

JavaScript syntax :

sf_Register(list(123, 4567,89))

version = sf_Version - Returns a string containing version number of the xtra.

Example:

currentVersion = sf_Version()

put currentVersion

-- "2.0.1"

sf_Send(host, directory,username, password,memberName or vListData, castlibName, remoteFileName, fileType, fileProperties, appendFlag, progressDialogFlag, progressDialogTitle) - where:

host is the address of FTP host;

directory is the relative path from login directory to target directory;

username is either the login username or "" for anonymous;

password is either the login password or "" for anonymous, in which case what gets sent is "shockfiler@nodomain.com";

memberName or vListData is the name of member to export or propertyList exported from vList Xtra;

castlibName is the name of castlib containing member to be exported, can be "" which defaults to internal (lib 1). If a vList propertyList is being passed in the memberName param, then this param should be passed as "";

remoteFileName is the file name to save exported member to in remote FTP directory;

fileType is the Lingo symbol, currently supports #text, #jpeg, #wave,#aiff, #bina;

fileProperties is the Lingo list, contains additional specifications for the file to be written. Pass [] for a file type with no properties;

appendFlag is a boolean, 1 to append to existing file, 0 to overwrite existing file and ignored for all file types except text;

progressDialogFlag is a boolean, 1 to display progress bar as file transfers or 0 not to;

progressDialogTitle is the caption for progress dialog title bar.

Returns 1 if the transfer can start, or a negative error code if there was a problem. Exports a text member, sound member, image member or vList data to a designated file on an FTP server. sf_Send logs in the the server, transmits the file exported from the specified member, and logs out.

The sf_Send command handles connecting sending and disconnecting automatically. If you are not interested in monitoring the status of the transmit, sf_Send is the only command needed to send a file (other than sf_Register for registered users). Transmission of the file operates concurrently with other Director operations. The movie will continue running and other Lingo will execute after sf_Send, while the file is being sent.

An internet connection must be open before you can call sf_Send successfully. If no connection is open you will get an error. ShockFiler maintains one active connection at a time. If you are sending a file or getting a listing and you attempt a second sf_Send or sf_RequestFileList before the operation in progress finishes, you will get a "connection is in use" error.

SERVER PARAMETERS

The host, directory, username, and password parameters are used to log in to the FTP site where the file will be uploaded. They are the same type of information you usually type in to an FTP client to transmit files.You may need to use additional configuration commands before calling this method if you are connecting through a firewall or proxy server.

Host - The host parameter holds the name or IP address of the FTP server, for example "ftp.macromedia.com" or "192.192.192.8". ShockFiler automatically logs in to the standard FTP port, which is 21.

Directory - The directory parameter holds the path to the target directory relative to the login directory. If the login directory IS the target directory, specify "" for the directory parameter. Specify path separators as "/". Do not use a path separator at the beginning or end of the path. Directory names are case-sensitive. For instance, the string "Exchange/mac" specifies the directory "mac" contained in directory "Exchange" which is a subdirectory of the login directory. If the login directory was:

/users/safeway

then a directory parameter of "Exchange/mac" would produce a target directory of:

/users/safeway/Exchange/mac

Username - The username parameter specifies the login name of a user allowed to log in to the FTP server. Some servers allow anonymous login. For anonymous login you can specify either "anonymous" or simply "" for the user name.

However, few servers allow users logged in as "anonymous" to upload files. You will probably need the system administrator to give you a username and password for the FTP server to be able to upload files.

Password - The password parameter specifies the password owned by the user allowed to log in to the FTP server. Some servers allow anonymous login.When a username of anonymous is entered, the server expects to see an e-mail address for the password. If you have entered "anonymous" for the username you can specify either your e-mail address or "" for the password. If you use "", ShockFiler sends "shockfiler@nodomain.com" for the e-mail address.

MEMBER TYPES SUPPORTED

sf_Send works with the following internal member types: field, text, bitmap, sound, richtext. Linked cast members are not supported. Compressed members are not supported.

Text, field, richtext members - For field, text, and richtext, the text property of the member is exported. That means that no style information will be exported for richtext, just plain text. However, you can copy any of the following properties of those types of members into a second field member and export the information as a text file through the xtra:

html of member

rtf of member

scriptText of member

The text files exported are plain text files with the type of line ending specified in the fileProperties parameter.

#mac - CR (CarriageReturn)

#win - CR, LF (LineFeed)

#unix - LF

Bitmap and picture members - Bitmap and picture members are saved as JPEG files with a 72 dpi resolution and the same pixel dimensions as the original cast member. The quality of the JPEG can be set in the fileProperties parameter.

You can export other graphic member types that have a picture property, by setting the picture property of an existing #bitmap member to the picture property of the other graphic member.

member("bitmap member").picture = member("not directly supported graphic type").picture

Sound members - Sound members are saved as either WAVE or AIFF files depending on which is specified as the fileType parameter. Sound files are saved with the number of channels, sample rate and sample depth properties of the original sound member. WAVE export only supports standard Win sampling rates (11025, 22050, 44100). Trying to export a member with a different Mac sampling rate, for instance 11027, will return a -4 "member type does not match export file type" error.

ShockFiler can export any sound member recorded at runtime and most sound member types created by importing a sound. The following table shows the various sound member types and any additional information needed to export them using ShockFiler.

EXPORTED FILES

ShockFiler Xtra uses the data from the specified cast member to create a new file on the FTP server or append data to an existing file (Append applies to text only).

filetype - The filetype parameter currently accepts 5 file types - #text, #jpeg, #wave , #aiff or #bina. Type #bina is for vList data. The file type specified must match the member type or the transfer will error. For instance, specifying #wave to export a text member will not work.

Javascript note: Use the symbol function to convert a string to the Lingo symbol datatype ex: symbol("jpeg")

fileProperties - The file properties list contains additional properties that are particular to the file type. Currently they are:

Pass [] for file types that do not have any additional file properties.

JavaScript note: Use the list and propList functions to create a Lingo list to pass in this parameter. You cannot pass a JavaScript Array. EX: propList( symbol("quality"),100)

#lineEndings: The line endings property converts any existing line endings characters in the text to the ending type specified. It does not add line endings to text.

#quality: The quality property adjusts the amount of compression applied to the file and therefore the size of the resulting file as well as the time it will take to transmit the data. The lower the quality setting the higher the compression and the smaller the data and the resulting file.

appendFlag - ShockFiler Xtra has the capability to append text to an existing text file on the FTP server, if the server software supports APPEND, if the server has been configured to allow APPEND, and the login account being used has the permission to APPEND.

If the appendFlag parameter is 0 a new file is created on the FTP server if a file of that name does not exist. If the file already exists, and the login user has overwrite permission, the existing file is overwritten. If the file exists and the login user does not have overwrite permission, an error will be returned.

If the appendFlag parameter is 1 and the transfer is for fileType #text, the text will be appended to any existing file of the same name, otherwise a new file will be created. The appendFlag parameter is ignored for any file type other than #text.

You can use the append feature to maintain data files containing data from many users.

PROGRESS DIALOG

Please note the limitations of this feature.

Passing 1 for the progressDialogFlag parameter displays a moveable, nonmodal dialog that shows a progress thermometer and percent done. The progressDialogTitle parameter is the text that will display in the title bar of the progress dialog. Note: The progress dialog always displays in the unregistered version of ShockFiler Xtra.

If the user pressed the cancel button on the dialog during the transfer, the transfer will abort and sf_getTransferStatus will show a status of "Error" and an error string of "Cancelled by server".

INTEGRATION WITH AUDIO XTRA AND VLIST

Audio Xtra (version 6 and later) includes a new function, axConvertToSFData(), that can be used to pass binary audio data as a vList-compatible property list, ready to be used with ShockFiler. See the Audio Xtra documentation for more information on how to use this function.

vList Xtra saves Lingo lists and other data types to members and files. ShockFiler Xtra includes support for receiving data from vList in a format that will create a standalone vList file when saved by ShockFiler to an FTP server. Getting the data from vList to the FTP server requires two steps:

1. Call a function in vList that returns the packaged vList data into a variable

2. Pass the variable containing the vList data as an argument to ShockFiler's sf_Send command

The following vList Xtra function returns data into a variable that you can pass to ShockFiler's sf_Send command:

propList = vList_to_sf ( data, compressionFlag) - where data is a Lingo list or other data type and compressionFlag is a boolean, 1 for compress the data or 0 for don't compress the data. Returns a Lingo property list in the format:

[#data: binary vList data, #length: size of data in bytes]

Use the following parameters in the sf_Send call to send vList data instead of a cast member:

memberName/propList: name of property list variable containing vList data

castlibName: "". Ignored. No cast member is being sent

remoteFileName: name to give exported vList file on FTP server

fileType: #bina

fileProperties: []. Ignored. No properties can be set for a vList file.

Example:

-- vList function

packagedData = vList_to_sf ( [#name: "Andy", #score: 50] , 1)

-- the packaged vList data is now in variable packagedData

--

-- Variable packagedData is passed in the "member" param. It will create a vList file on the

-- FTP server named mydata.lst.

sf_Send ("ftp.macromedia.com", "incoming","guest", "mypassword",packagedData, "", "mydata.lst", #bina, [], 0, 0,"")

SF_SEND EXAMPLES

Saving a user's preferences, as stored in a field of the movie

Example:

err = sf_Send ("ftp1.domain.com", "langModule/gary","languageStudent", "password","preference field", "External castlib", "gary.txt", #text, [#lineEndings: #win], 0, 1, "Storing preferences on server ...")

if err <> 1 then

alert "Cannot initiate transfer"

end if

Logs on to FTP host "ftp1.domain.com" and into the relative directory of "langModule/gary", with a username of "languageStudent" and a password of "password". Exports the text in field "preference field" of castlib "External castlib" to file gary.txt on the FTP server. Any line ending characters in the text will be converted to the Windows convention of CR,LF. The append flag is off, so a new file will be created for the data. The progressDailog flag is on, so a progress dialog will display during the transfer with the caption of "Storing preferences on server ...".

Checks the error value returned. If the error returned is 0 the transfer will start. The movie can continue playing and other Lingo will continue to execute while the file transfer is going on.

Saving a user's art created during the session

Example:

member("screenshot member").picture = (the stage).picture

--

err = sf_Send ("192.243.88.53", "","george", "dogfight","screenshot member", "", "sketch.jpg", #jpeg, [#quality: 75], 0, 1, "Sending your picture to the server ...")

--

if err < 1 then

alert "Cannot initiate transfer"

end if

Logs on to FTP host "192.243.88.53" , with a username of "george" and a password of "dogfight". Since no relative directory has been specified, the login directory will receive the file. Exports the internal bitmap in member "screenshot member" of the first internal castlib to file sketch.jpg on the FTP server. Some compression will be applied to the JPEG because a quality setting of 75 was specified. The append flag is off, but it would be ignored for a #jpeg transfer anyway. The progressDailog flag is on, so a progress dialog will display during the transfer with the caption of "Sending your picture to the server ...".

Appending a user's game score to an existing file on the FTP server

Example:

put name & TAB & score & RETURN into field "sendScore"

--

err = sf_Send ("ftp.games.com", "frogger","froggerplayer", "ribbet","sendscore", "", "highscores.txt", #text, [#lineEndings: #unix], 1, 0, "")

--

if err < 1 then

alert "Sorry, could not transmit your game score"

end if

Logs on to FTP host "ftp.games.com" , and into the relative directory of "frogger", with a username of "froggerplayer" and a password of "ribbet". Appends the text in member "sendScore" of the first internal castlib, to existing file highscores.txt on the FTP server. The return in the text will be replaced with the UNIX line ending of a linefeed. The text is appended to the file instead of creating a new file because the append parameter is set to 1. The progressDailog flag is off, so no progress dialog will display during the transfer and a caption for the dialog is therefore not necessary so that parameter has been left blank.

Sending sound previously recorded to a member using Audio Xtra

Example:

err = sf_Send ("ftp.music.com", "pub/audition","", "","recording 1", "Sound castlib", "rec1.wav", #wave, [], 0, 1, "Sending your recording to server ...")

--

if err < 1 then

alert "Sorry, could not transmit your recording"

end if

Logs on to FTP host "ftp.music.com" , and into the relative directory of "pub/audition". Since the username and password parameters have both been left blank, the login username will be passed as "anonymous" and the password will be passed as "shockfiler@nodomain.com" Transmits the sound member "recording 1" of castlib "Sound castlib" to create a WAVE file on the FTP server named "rec1.wav". There are no additional properties to set for this media type, so that parameter is passed as an empty list. The append flag is off, but it would be ignored for a #wave transfer anyway. The progressDailog flag is on, so a progress dialog will display during the transfer with the caption of "Sending your recording to server ...".

sf_Send ("TODISK", Path,"", "",memberName or vListData, castlibName, fileName, fileType, fileProperties, appendFlag, saveDialogFlag, dialogText) - where:

"TODISK" is a string (pass this string in all caps to sf_Send to indicate that it will be saving the member to disk);

Path is a string, either full path to local directory to save file to or relative path;

notUsed is a string, ignored - pass "";

notUsed is a string, ignored - pass "";

memberName or vListData is a string, the name of member to export or propertyList exported from vList Xtra

castlibName is a string, the name of castlib containing member to be exported, can be "" which defaults to internal (lib 1). If a vList propertyList is being passed in the memberName param, then this param should be passed as "";

fileName is a string, the file name to save exported member to if a full directory was passed in "path", or "" if a relative path was passed in "path";

fileType is a Lingo symbol, currently supports #text, #jpeg, #wave,#aiff, #bina;

fileProperties is a Lingo list, contains additional specifications for the file to be written. Pass [] for a file type with no properties;

appendFlag is a boolean, 1 to append to existing file, 0 to overwrite existing file. Ignored for all file types except text;

saveDialogFlag is a boolean, 1 to display saveFile dialog or 0 not to [always displays in unregistered version];

dialogText is a string, one-line message to display on dialog.

Returns 1 if the file was saved successfully, or a negative error code if there was a problem. Exports a text member, sound member, image member or vList data to a designated file on the local hard drive.

This alternate usage of the sf_Send command saves to disk if the first argument that usually contains the FTP server IP address contains the string "TODISK" in all caps instead. Some arguments such as username and password have no use when you are saving locally so those arguments are ignored, but you must still pass an empty string for the unused argument to keep the number of arguments the same.

No progress dialog displays during a save to disk. Control passes to the system during the file copy and the next line of Lingo executes after the file copy, so it is not possible to poll sf_TransferStatus during the copy. Calling sf_TransferStatus after the copy returns the number of bytes copied and any error that happened during the copy.

NOTE: If you use this command to save a text or field member and the member contains no text, the target file will not be created. If the target file already exists, it will be deleted.

PATH: PASSING THE FULL PATH TO THE FILE TO SAVE

If you provide a full path to a directory in param "path", ShockFiler builds the local file path using the path and fileName params. You must pass the directory path without the trailing delimiter which ShockFiler will add. The following strings:

directoryPath: "C:\TEMP" <--- no ending slash

fileName: "animals.jpg"

will save to the path:

"C:\TEMP\animals.jpg"

If you want to use sf_SaveFileDialog to prompt the user for a path, leave one or both of the path parameters empty and the dialog will appear automatically. If you want to prompt for the path earlier on, use the following code to break up the full file path returned from the dialog into the two pieces required in the directoryPath and fileName params:

on mouseUp

fullpath = sf_saveFileDialog("")

directory = splitFilePath(fullpath)[1]

filename = splitFilePath(fullpath)[2]

end

on splitFilePath path

if (the platform).char[1..3] = "Mac" then

the itemDelimiter = ":"

else

the itemDelimiter = "\"

end if

items = the number of items of path

fname = the last item of path

delete the last item of path

return list(path,fname)

end

PATH: PASSING A RELATIVE PATH TO THE FILE TO SAVE

If you pass a relative path in param "Path" for sf_Send, ShockFiler ignores param "fileName" because it has all of the information it needs to build the path from param "Path". If you pass a relative path in param "Path" then pass "" in param "fileName" because it will be ignored. The following examples show two ways to specify a path of "C:\project\graphics\newpict.jpg" in a movie located at "C:\project\movie.dir".

Full path:

sf_Send ("TODISK", "C:\project\graphics","", "","screenshot member", "", "newpict.jpg", #jpeg, [#quality: 75], 0, 1, "" )

Relative path:

sf_Send ("TODISK", "@graphics\newpict.jpg","", "","screenshot member", "", "", #jpeg, [#quality: 75], 0, 1, "" )

SAVE FILE DIALOG

If you pass 1 in the saveDialogFlag parameter, with both directoryPath and fileName filled, the saveDialog will come up and show the contents of the directory specified in directoryPath and show the file specified in fileName as the default name for the saved file. If the saveDialogFlag parameter is 1, then directoryPath and fileName are only used by the dialog. The actual save path is determined by the user when the dialog appears.

If you pass 0 in the saveDialogFlag parameter, the directoryPath and fileName are used together to form the path where the file will be saved. If either directoryPath or fileName or both are passed as empty strings, even if the saveDialog parameter is 0, the dialog will still display, since there isn't enough information to save the file.

SHOCKWAVE

In Shockwave, the save file dialog always displays before the file is saved and the path the user picks is used. In Shockwave it doesn't matter what is passed in directoryPath or fileName because those arguments are not used.

Example:

on mouseUp

-- capture the stage and store it in a member

member("screenshot member").picture = (the stage).picture

-- save the member to a local jpeg file

err = sf_Send ("TODISK", "C:\TEMP","", "","screenshot member", "", "sketch.jpg", #jpeg, [#quality: 75], 0, 1, "" )

if err < 1 then

alert "Could not save file"

end if

end

The example above saves a captured image of the stage to a JPEG file. The initial path is "C:\TEMP\sketch.jpg" but since the saveDialogFlag param is 1, a save dialog will display starting at the TEMP directory with sketch.jpg as the default file name. Whatever the user chooses as the path is where the file will be saved. The file will be saved with a quality of 75%.

sf_SendFile (host, directory,username, password,localFilePath,remoteFileName,appendFlag, progressDialogFlag,progressDialogTitle) - where host is a string, the address of the FTP host; directory is a string, the relative path from login directory to target directory; username is a string, either the login username or "" for anonymous; password is a string, either the login password or "" for anonymous, in which case what gets sent is "shockfiler@nodomain.com"; localFilePath is a string, the full path to the local file to send, or the relative path or "" to put up an open file dialog and use the path the user picks; remoteFileName is a string, the file name to save the sent file to on the FTP server; appendFlag is a boolean, 1 to append to existing file, 0 to overwrite existing file; progressDialogFlag is a boolean, 1 to display progress bar as file transfers or 0 not to;and progressDialogTitle is a string, the caption for the progress dialog title bar.

Returns 1 if the transfer can start, or a negative error code if there was a problem. Sends a local file on the user's hard drive to an FTP server. In authoring and projectors any valid file path can be passed for localFilePath. In Shockwave, you must use a relative path for the local file path or leave the localFilePath parameter empty, to prompt the user for the save file path. Passing a full path in Shockwave for the localfilepath will error.

Example:

err = sf_SendFile ("ftp.agency.com", "pub/incoming","", "","C:\temp\rough.jpg", "treatment_1.jpg", 1, "Sending your graphic file to server ...")

--

if err < 1 then

alert "Sorry, could not transmit your file"

end if

filePath = sf_OpenFileDialog ( ) - Returns a string containing the chosen file or "" if the user did not chose a file.In authoring and in projectors the full file path to the local file is returned. In Shockwave, the path to the local file is stored internally by the xtra and only the file name is returned.

Puts up a standard file picker dialog. This function was included to provide a way to prompt the user for a local file to send when using sf_SendFile. You first call the function, save its returned file path into a variable, then pass the variable to sf_SendFile:

In authoring and projectors the function operates like a normal open file dialog and can be used any time you want to prompt the user for a local file. In Shockwave, the open file dialog does not return a filepath and therefore is useful only with sf_SendFile. In Shockwave, the dialog returns only the file name chosen and ShockFiler stores the path to the file internally. When you pass the filename returned from the open file dialog to sf_SendFile, ShockFiler determines the full path to the file from the filename and sends the file.

In Shockwave the open file dialog function stores the path to the last file chosen by the user. Once the user has chosen a file using the dialog, you can send the same file multiple times by passing the file name returned from the function to sf_SendFile. To send another file, you must prompt the user again. The new chosen file path is stored internally and the old path is erased. Passing "" in the localFilePath parameter of sf_SendFile will also prompt the user for the local file to send, but the path to the file is not saved internally by the dialog after the transfer completes.

Example:

usersFileChoice = sf_OpenFileDialog ( )

sf_SendFile "ftp.soundbank.com", "pub/incoming","", "",userFileChoice, "sample.wav", 1, "Sending your sound file to the server)

sf_GetFile (host, directory,username, password,localFilePath,remoteFileName,progressDialogFlag,progressDialogTitle) - where host is a string, the address of the FTP host; directory is a string, the relative path from login directory to target directory; username is a string, either the login username or "" for anonymous; password is a string, either the login password or "" for anonymous, in which case what gets sent is "shockfiler@nodomain.com"; localFilePath is a string, the full path to the file to save to or the relative path or "" to display a save file dialog; remoteFileName is a string, the file name to get from the FTP server; progressDialogFlag is a boolean, 1 to display progress bar as file transfers or 0 not to; and progressDialogTitle is a string, the caption for the progress dialog title bar.

Returns 1 if the transfer can start, or a negative error code if there was a problem. Downloads a remote file on an FTP server to the local machine. In authoring and projectors any valid save path can be passed for localFilePath. In Shockwave, you must use a relative path to save the file to the dswMedia folder or leave the localFilePath parameter empty, to prompt the user for the save file path. Passing a full path in Shockwave for the localfilepath will error.

Example:

err = sf_GetFile("ftp.agency.com","updates","ralphieboy", "moonbeam","C:\project\newimages.cst", "weds_images.cst", 1, "Retrieving new image castlib...")

--

if err < 1 then

alert "Sorry, could not get the file"

end if

filePath = sf_SaveFileDialog ( defaultFileName ) - where defaultFileName is a string, the filename to display in the dialog's filename field. Returns a string containing the save file path or "" if the user did not chose a file.In authoring and in projectors the full file path to the local file is returned. In Shockwave, the path to the local file is stored internally by the xtra and only the file name is returned.

Puts up a standard file save dialog. This function was included to provide a way to prompt the user for a place to save the file when using sf_GetFile. You first call the function, save its returned file path into a variable, then pass the variable to sf_GetFile:

In authoring and projectors the function operates like a normal save file dialog and can be used any time you want to prompt the user for a local path to save a file. In Shockwave, the save file dialog does not return a filepath and therefore is useful only with sf_GetFile. In Shockwave, the dialog returns only the file name chosen and ShockFiler stores the path to the file internally. When you pass the filename returned from the save file dialog to sf_GetFile, ShockFiler determines the full path to the file from the filename and saves the file from the FTP server to that path.

In Shockwave the save file dialog function stores the path to the last file chosen by the user. Once the user has chosen a file using the dialog, you can save to the same local file path multiple times by passing the same file name returned from the function to sf_GetFile. To send another file, you must prompt the user again. The new chosen file path is stored internally and the old path is erased. Passing "" in the localFilePath parameter of sf_GetFile will also prompt the user for the local file path to save to, but the path to the file is not saved internally by the dialog after the transfer completes.

Example:

usersFileChoice = sf_SaveFileDialog ("newimages.cst" )

err = sf_GetFile("ftp.agency.com","updates","ralphieboy", "moonbeam",usersFileChoice, "weds_images.cst", 1, "Retrieving new image castlib...)

sf_TransferStatus() - Returns a Lingo property list containing status information. This function call returns the status of the current file transfer or directory listing retrieval. It returns a Lingo property list in the following format:

[ #file: "birds.jpg", #state: "InProgress", #bytesSoFar: 1024 , #bytesTotal: 19782, #error: "None"]

where file is a string filename of the file currently being transferred; state is a string, one of the following: "Connecting", "Started"," InProgress", "Complete" or "Error"; bytesSoFar is an integer, the number of bytes transferred so far; bytesTotal is an integer, the total size of transfer; and error is a string, either "None" or string describing the error.

The commands sf_Send, sf_SendFile, sf_GetFile and sf_RequestFileList do their work while allowing the Director movie to continue running. If you want to know whether one of these commands was successful or when they have finished, you must call sf_TransferStatus periodically. You can also use this function to update a custom file transfer dialog if you don't want to use the one provided. The best place to call it is from an exitframe handler.

CAUTION: Do not call sf_TransferStatus() from within a repeat loop. Lingo repeat loops lock out other processing and will interfere with or completely prevent the file transfer.

JavaScript Note: Use bracket syntax to access the list:

if (sf_TransferStatus()["state"] == "Complete") {

Example:

-- Send text button behavior

property sending

on mouseUp me

host = "ftp.macromedia.com"

directory = "pub"

usersname = "george"

password = "buckley"

sendMember = "newdata"

sendMembersCastlib = ""

remoteFileName = "results.txt"

remoteFileType = #text

remotefileProperties = [#lineEndings:#win]

doappend = 0

showDialog = 1

dialogTitle = "Sending text file ..."

success = sf_Send (host, directory,usersname, password,sendMember, sendMembersCastlib, remoteFileName, remoteFileType, remotefileProperties, doappend, showDialog,dialogTitle)

if success = 1 then

sending = TRUE

else

sending = FALSE

end if

end

on exitframe me

if sending = TRUE then

-- If a file transfer is going on then check the status

statusList = sf_TransferStatus()

-- Take some action if the transfer is done

if statusList.state = "Complete" then

sending = FALSE

go frame "Transfer complete"

-- Take some action if the transfer errored out

else if statusList.state = "Error" then

sending = FALSE

go frame "Transfer errored out"

-- Loop in this frame while the transfer is in progress

else

go the frame

end if

else

go the frames

end if

end

sf_RequestFileList(host, directory,username, password) - where host is the address of the FTP host; directory is the path from root to directory; username can be "" for anonymous; and password can be "" for anonymous, in which case what gets sent is "webfiler@nodomain.com". Returns 1 if the request can start, a negative error if there is a problem.

Requests a directory listing for the specified directory on the host. While the list is being transferred Director will continue to animate. You may need to use additional configuration commands before calling this method if you are connecting through a firewall or proxy server.

This command does not itself return the file listing. ShockFiler parses and stores the returned file listing internally in a Lingo list variable, which you must retrieve with sf_FileListToLingoList after the transfer of list info has finished. The list will not be available until sf_TransferStatus returns a status of "Complete".

Example:

err = sf_RequestFileList ("ftp.adobe.com", "pub","", "")

if err <> 1 then

alert "Invalid parameters or another connection is open"

end if

sf_FileListToLingoList(listType) - where listType is a symbol, either #full, #filename or #raw. Returns a Lingo list containing file information or [] if there was an error, or no files in directory.

#filename returns a linear list containing only the file names of the files in the specified directory, the listing does not include directories.

#full returns a property list where each file name is a property whose value is a property list of file attributes.

[ "loud.wav" : [#size: 40453, #date: "May 1 1999", #type: #file],

"pictures" : [#size: 0, #date: "Aug 21 2000", #type: #directory] ]

#raw returns a linear list of the returned text from a file listing, one line of the listing per string, in order

["total 48", "-rw-rw-r-- 1 0 ftpadmin 786 Nov 7 1997 README.ftp" ,"d--x--x--x 2 0 staff 512 Sep 28 1997 bin"]

If the FTP server does not return information required for one or all of the fields ShockFiler will still return a list in the above format but a field with no information returned will appear as follows:

#size: 0

#date: ""

#type: #invalid

Use this function after initiating a listing request with sf_RequestFileList. Code example 2 shows how to loop in a frame and check the transfer status while waiting for the list to be returned.

JavaScript Note: Use bracket syntax to access the list.

theList = sf_FileListToLingoList(symbol("full"));

// [ "loud.wav" : [#size: 40453, #date: "May 1 1999", #type: #file],"pictures" : [#size: 0, #date: "Aug 21 2000", #type: #directory] ]

soundName = theList.getPropAt(1);

// "load.wav"

soundProps = theList.getProp(soundName);

// [#size: 40453, #date: "May 1 1999", #type: #file]

soundSize = soundProps["size"];

// 40453

Example 1:

fileList = sf_FileListToLingoList(#filename)

put fileList

-- ["6list.html","7list.html","404list.html"]

fileList = sf_FileListToLingoList(#full)

put fileList

-- ["6list.html":[#size: 6400,#date: "Nov 7 1997",#type: #file],"7list.html":[#size: 3604,#date: "May 28 1999",#type: #file],"404list.html":[#size: 1732,#date: "Jun 1 1997",#type: #file] ]

fileList = sf_FileListToLingoList(#raw)

put fileList

-- ["total 3",

"-rw-rw-r-- 1 0 mike 6400 Nov 7 1997 6list.html" ,

"-rw-rw-r-- 2 0 mike 3604 May 28 1999 7list.html",

"-rw-rw-r-- 2 0 mike 1732 Jun 1 1997 404list.html" ]

Example 2:

-- Get listing button behavior

property connecting

on mouseUp me

host = "192.192.192.1"

directory = "junk"

usersname = "anonymous"

password = "gcm@tiac.net"

success = sf_RequestFileList (host, directory,usersname, password)

if success = 1 then

connecting = TRUE

-- Initialize the field that will display the listing

put "" into field "Listing"

else

connecting = FALSE

end if

end

on exitframe me

-- If not connecting then loop in this frame

if connecting = FALSE then

go the frame

else

-- If a connection is in progress then check the status

statusList = sf_TransferStatus()

-- If the listing was successfully retrieved then

-- get it in Lingo list format

if statusList.state = "Complete" then

connecting = FALSE

sending = FALSE

fileList = sf_FileListToLingoList(#raw)

numLines = fileList.count

repeat with x = 1 to numLines

put filelist[x] & RETURN after field "Listing"

end repeat

-- Take some action if the transfer errored out

else if statusList.state = "Error" then

connecting = FALSE

alert "Transfer errored out"

-- Loop in this frame while waiting for the listing

else

go the frame

end if

end if

end

sf_CreateDirectory ( host, directory, username, password, directoryNameToCreate) - where host is the address of FTP host; directory is the path from root to directory; username can be "" for anonymous; password can be "" for anonymous in which case what gets sent is "webfiler@nodomain.com"; and directoryNameToCreate is a string, the name of the subdirectory to create in the login directory.

Logs in to the specified directory and creates a sub-directory within it specified by the directoryNameToCreate parameter. Use sf_TransferStatus() to monitor progress and to determine if the directory was successfully created. Some things that will prevent creation of the directory are:

- The user does not have permission to create directories on the FTP server,

- The directory already exists,

- The login information is incorrect,

- The directory name is illegal for the system the FTP server is running on.

Example:

property sending

on beginsprite me

sending = FALSE

end

on mouseUp me

sf_CreateDirectory("ftp.server.com", "incoming","rhonda", "secretword", "ProjectFiles")

sending = TRUE

end

on exitframe me

if sending = FALSE then exit

st = sf_TransferStatus().state

case st of

"Error":

sending = FALSE

alert "Could not create directory"

"Complete":

sending = FALSE

alert "Done creating directory"

end case

end

The code above logs user "rhonda" into ftp.server.com and changes from her login directory to subdirectory "incoming". Then it creates subdirectory "ProjectFiles" in directory "incoming". It loops in the exitframe handler until sf_TransferStatus() returns a status of "Error" or "Complete", which means that the operation is over.

sf_Disconnect - ShockFiler automatically disconnects after a successful file transfer or listing transfer. In rare circumstances a problem with the FTP server will cause an operation to never return a Complete status. Since only one transfer can happen at a time, use sf_Disconnect to terminate an unsuccessful operation before attempting a new one.