Internet Updater

September 10, 2002
by Daniel Nelson

Internet-updatable software is becoming increasingly prominent for its ability to correct errors, expand functionality, and otherwise maintain a product that has been installed -- or partially installed --on an end user's system. Director projects are very well suited to this type of software maintenance, though it does take a little planning. The technique described in this article can be used to fix bugs in any part of a Director project, as well as to expand functionality and add resources without ever needing to quit and restart the projector. Even the updater can be updated. This method uses only those Xtras included in the Director package. It can operate through firewalls that might block methods dependent on ftp.

Technique

The Internet updater is a Director movie that does not share any resources with the project to be updated. It has an external cast which maintains a description of all files that have been modified. When a user chooses to update, the executing movie stores the project name, a pointer to the current movie, and the URL of the online updates folder into global variables. The project name will be used to look on the server for updates relevant to the project; the movie pointer will be used to determine where to return after updating. These three global variables allow the updater to be protected and used with any project without modification. The movie then jumps to the updater movie using the go movie command; play and play done cannot be used since these calls remember particulars of a script that we may be updating. A description of all current updates is maintained in two text files located at the updates URL defined in the calling movie. Two files are used instead of one to maintain platform-specific update information. The files are formatted exactly the same, so there is little extra work in maintaining two files instead of one. The appropriate update description is downloaded and compared against the list of all previous updates performed by the local updater. Any files in the current update that have not been previously updated are downloaded; their path relative to the projector and their version information are added to the local list. Any files in the local list whose version information is different from that of the file in the current update are likewise downloaded and their version information is updated. This allows a local file to be replaced by an earlier version if the earlier version turns out to be preferable to a subsequent update (thanks to Dave Draeger for pointing out the desirability of this feature). Each file is updated sequentially, in the order that the files appear in the update description. If a network error or a crash occurs, those files already updated prior to the error will not be downloaded again. This is accomplished by downloading one file at a time to its desired location using downloadNetThing, waiting until the download of that netID is complete using netDone, testing the success of the download with netError, updating the local updates list, writing the list to the field member in the external cast, and saving the external cast -- all before beginning download of the next file. Care must be taken in defining the order in which files are downloaded so that if a download fails, the program will continue to function and the Internet updater may be run again at a later time to complete the update. For example, if a new external cast has been added to an existing DXR file, the external cast should precede the revised DXR in the current updates text file. This is performed until all the files to be updated are up to date, at which point the user is notified, and playback can return to the calling movie.

Organization of an Updatable Director Project

Director projects are very well suited to automatic updating when they are organized using a stub projector and external cast structure. The use of external casts keeps the DXR files relatively small. Dividing casts into script casts and data casts minimizes the size of the script casts÷ advantageous since it seems more likely that scripts will need updating than graphics or sounds when chasing down bugs. Large external casts containing imported data and linked resources such as sounds, graphics, and digital video, can remain on CD-ROM. If any need to be modified, the replacement can be downloaded along with a modified DXR file to which has been attached a new external cast that references or includes the modified data. For updates to be simple to implement and to be able to modify all parts of a project, all DXR files, movie scripts, and parent scripts should be installed to the end userâs hard drive. All files should be installed, rather than manually dragged, to avoid a read only attribute in Windows that prevents external casts from being saved and files from being replaced by downloadNetThing. Since executing code can't replace itself, updating the updater involves downloading the new version to a new name (such as internet_updater.1.2.dxr) and subsequently updating the script cast that calls the updater so that it points to the new file.

Structure of the Updates Text File Used by the Accompanying Director Movie Example:

The server side current updates text file can be formatted in many ways. The important information for each file to be updated is the location of the local file relative to the projector, the current update version (which may be a number, a date, etc.), and the location of the update file on the server relative to the folder containing the updates description. It may be worthwhile to include Macintosh and Windows specific update descriptions so that platform specific bugs can be addressed without forcing the unaffected platform to perform the update. Some functionality may also be platform dependent, or may be ready for one platform before it is ready for the other. The example movie looks for a file called projectName_mac.txt or projectName_win.txt, where projectName is set in the calling movie as mentioned above. The update description for each platform is formatted in exactly the same way. The file used in the example movie accompanying this article is in the form of a property list of linear lists, with carriage returns separating the different components for added legibility but ease of converting to a list (by removing the returns from and calling value on the string). The properties are paths relative to the projector of local files to be replaced, with directories separated by /. The linear lists contain the version information and the location of the server-side update file relative to the update folder. The update description for the example movie is as follows:

[ "resources/example_data2.cst": ["23 July 2002", "updateArticle/resources/example_data2.cst"], "resources/example_scripts.cst": ["23 July 2002", "updateArticle/resources/example_scripts.cst"], "example_movie.dir": ["23 July 2002", "updateArticle/example_movie.dir"] ]

The Example Movie

The example project (executed in Director 8) is available for your reference and use as an SIT or ZIP archive. Feel free to use any or all of it; I only ask that you keep the copyright information with any parts you use. I also accept no responsibility for any problems that might arise from this technique or the code included with the provided movies. The base movie that calls the updater includes two means of letting the user decide when to update. When on the second marker, if the user is online and permission was granted on the first marker or at some time in the past, then a behavior automatically checks for updates and prompts the user if one is available. If an update is available, the user can decide to update or not. The second method leaves the update decision entirely up to the user, waiting until an explicit instruction is given before checking the Internet. It is probably prudent to get a user's permission before automatically accessing the Internet, perhaps by asking the user during installation if she would like to automatically check the Internet for updates. After the user chooses to update, if the user is not online, or the update file is unable to be downloaded, then the user is prompted to establish an Internet connection. For full-screen projectors and projectors without a title bar, code is included to hide (Macintosh) or minimize (Windows) the application so that a user can have easy access to what she needs to connect to the Internet. Instructions are given for finding the minimized or hidden application so that novice users will not feel stranded. This feature may be omitted for projectors with title bars. (appMinimize does not work in the authoring environment. Create a projector from the stub movie included in the download package to explore this feature.) The Internet updater returns playback to a frame labeled update complete in the calling movie, giving calling movies a standard, generic return location to which to conform. The applicationPath will not suffice for use in the authoring environment since it will refer to the Director application, so the moviePath has been modified to point to where the projector would be located in this small, example hierarchy. If the runMode is Projector, then each file's definitions are based off of the applicationPath. The projector associated with a project that uses the Internet updater must include the Network Xtras (which can be easily added by pressing the Network Xtras button in the Modify->Movie->Xtras... dialogue). Also include in the projector any Xtras that may be needed for future capability expansion (e.g. if a project does not at present use any vector shapes, but may be expanded in the future to include vector shapes, then include the Flash Asset Xtra in the projector distributed on the CD-ROM so that it will be able to handle the vector shapes after they are added during an update). The only scripts relevant to this article are the first two behaviors in internet_updater.dir and the first five scripts in example_scripts.cst.

Conclusion

The future of software appears to be coupled in some way with the Internet, allowing for software that is improved, repaired, and expanded at minimum cost to both the end user and the distributor. Director is especially well suited to Internet maintenance, which can be performed without requiring the application to be restarted using the standard set of Director Xtras. As the Internet becomes an increasingly prevalent and reliable resource, Director and Director Developers are in an excellent position to use it to create projects that are dynamic not only in their content, but also in their potential.

After several Director/Shockwave projects for an academic institution, Daniel is working to launch Blue Jade Creative Enterprises LLC, which went online 4 September 2002 at www.bluejade.com.