Examples

All examples

Automatic update of folders with FTP
Example of UltimateNet Xtra in use

Downloads
UltimateNetExample_1.zip Description: Associated source files Size: 115 kB Requirements: Director MX 2004 UltimateNet Xtra 1.1

Sample task

Let's presume that we have a presentation which displays texts and graphics loaded from external files and runs movies saved as .dir files. All those files exist in "data" folder. We want this presentation to check at every start-up if there are more recent copies of those files at a given FTP server. When such copies are found, there should be displayed a dialog window with question "Do you want to update now?".

If the user clicks "Yes", all files from "/pub/data" folder and its subfolders which need updating should start downloading to "data" folder at the local machine. The user should be able to check the progress during the download process and cancel it at any time.

We are going to show that when using our xtra UltimateNet Xtra this task is fast and easy. All main operations take place inside the xtra, we have only to initiate them in Lingo code.

Doing the task

We open a project (or create a new one) which uses data from external files (texts, graphics) and runs other .dir movies. First of all, we add UltimateNet Xtra and set its properties in the dialog window.

Adding UltimateNet Xtra

Let's select UltimateNet Xtra item from Insert > StarSoft Xtras menu. When its dialog window comes up, let's take a closer look at FTP tab. There we should enter all the data required for establishing the connection to FTP server. For instance, these settings could look like shown below:



If we are able to connect to FTP server at the working machine, we can check the correctness of our settings by clicking Test connection button. A successful attempt will be confirmed by message:



After we close the xtra dialog window with OK, it will be added to a current cast as a cast member. Its default name is "UltimateNet1".

Establishing the FTP connection

Now we must decide on when during presentation the update process should start. For example, it can take place right after presentation starts i.e. in its first frame, on the event on exitFrame. So we add to the first frame (with Score window, Frame Scripts channel) the following script:

on exitFrame me
  -- ...
  member("UltimateNet1").FtpConnect()
  -- ...
end
	

Note: The string "-- ..." stands for any instructions included in our presentation which are irrelevant here.

Therefore, on exit the first frame the connection with FTP server will be initiated. As we already know from UltimateNet Xtra Manual, all network operations are asynchronous i.e. performed in the background without any disruption to running presentation. Hence, FtpConnect function will end almost immediately after it is called, and its result will be raised after indefinite time as Lingo event with the name FtpConnect. This event must be handled in cast member UltimateNet Xtra script.

Preparing for update

The actual update (i.e. downloading the most recent copies of files at FTP server) must be preceded by comparing the contents of two folders: the source one at FTP server and the destination one at the local machine. It is performed by FtpPrepareForUpdateDir function, which creates a list of FTP files which are of more recent dates or different sizes than their local counterparts.

Therefore we should open UltimateNet Xtra cast member script window and add the following code:

on FtpConnect Result
  FTPDIR = "pub/data" -- FTP source directory
  LOCALDIR = "data"   -- Local destination directory
  
  if Result[#Error] = "OK" then
    -- ...
    member("UltimateNet1").FtpPrepareForUpdateDir(LOCALDIR, FTPDIR)
  else
    -- Error handling here
  end if
end
	

In this example, if the connection is successful, the local "data" folder is prepared for update, whereas "pub/data" FTP folder is the source one.

FtpPrepareForUpdateDir function is asynchronous, hence we get its results at the event with the same name.

Confirming the update

Before the actual update begins, we can give the user the opportunity to confirm or resign from it. In order to do it we can use a separate MIAW dialog window (containing question "Do you want to update now?") with name "dialog.dir", put in folder "internal".

Result[#Modified] parameter informs us if there are any files which need updating. If its value is 1 (true), the dialog window with our question will be displayed.

on FtpPrepareForUpdateDir Result
  if Result[#Error] = "OK" then  
    if Result[#Modified] then
      -- ...
      window("internal/dialog").open()
    else
      -- No files to update
      -- ...
    end if
  else
    -- Error handling here
  end if    
end
	

Update

When the user clicks "Yes" in the dialog window, the global function "UpdateYes" will be called in the main file of presentation. To this function we can add code which starts the actual update i.e. downloading modified files from FTP server.

The entire process of download is executed by nonparameter function FtpUpdateDir which uses the internal list of files prepared by function FtpPrepareForUpdateDir.

on UpdateYes
  -- ...
  member("UltimateNet1").FtpUpdateDir()
  -- ...      
end
	

When download process is complete we will be notified by on FtpUpdateDir event. In its handling function we should close the FTP connection and, if need be, refresh the objects displayed on the stage, we can also display a message about successful download. For example:

on FtpUpdateDir Result
  if Result[#Error] = "OK" then
    UpdateMembers() -- Our custom function
    member("editUpdateStatus").text = "Update done successfully"    
  else
    member("editUpdateStatus").text = "Error: " & Result[#ErrorText]
  end if
  member("UltimateNet1").FtpDisconnect()	
end	
	

Update progress bar

With on FtpProgress event we can easily create a bar indicating the progress of download.

Here is one of the simplest examples:

-- Movie script:

on UpdateFTPProgressBar Percentage
  UpdateProgressBar(Percentage, sprite("ProgressBar"))
end

on UpdateProgressBar Percentage, progressBar
  progressFrame = sprite(progressBar.spriteNum - 1)
  -- Count new progress bar dimensions
  rightBound = progressFrame.left + progressFrame.width * Percentage / 100
  progressBar.rect = rect(progressFrame.left + 1, progressFrame.top + 1, \
    rightBound , progressFrame.bottom - 1)
end

-- UltimateNet Xtra cast member script:
	
on FtpProgress Result
  UpdateFTPProgressBar(Result[#BytesSoFar] * 100 / Result[#BytesTotal])
end
	

Let's presume that the bar is made of 2 sprites - bounding frame and a bar of variable length. The bar sprite has a name "ProgressBar", whereas the frame bar lies in the channel one number less than the bar sprite's. The size of bar is calculated basing on the size of frame and the current download progress per cent.

Presentation

The .dir file attached to this example (designed for Director MX 2004) includes all the above scripts, and apart from that shows several other issues useful for Director developers who want to add the automatic FTP update option to their presentations.


Any comments? -

---

All examples