SharedObject Object

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

SharedObject Object

Flash 6

local data storage and remote data transmission

Constructor

None; instances are created with getLocal( ) or getRemote( ).

Properties

data: Container for the SharedObject's data.

Methods

close( ): Closes the connection between a remote shared object and Comm Server. See the Comm Server documentation.
connect( ): Connects to a remote shared object on Comm Server. See the Comm Server documentation.
flush( ): Forces data to be written to disk.
getLocal( ): Returns a reference to a specified local SharedObject instance.
getRemote( ): Returns a reference to a remote SharedObject instance managed by Comm Server. See the Comm Server documentation.
getSize( ): Returns the size of the SharedObject, in bytes.
setFPS( ): Sets the frequency with which changes to a remote shared object are sent to Comm Server. See the Comm Server documentation.

Event Handlers

onStatus( ): Invoked when a SharedObject generates a status message (e.g., an error, information, or a warning).

Description

The SharedObject object provides tools for storing ActionScript data on the end user's computer and transferring data between Flash clients via Comm Server. When used for local data storage, the SharedObject is referred to as a local SharedObject (LSO). When used for remote data transfer, the SharedObject is referred to as a remote SharedObject (RSO). This section covers only the local data storage capabilities of SharedObject. Information on remote data transfer features can be found in the Comm Server documentation at:

http://www.macromedia.com/software/flashcom/

Like JavaScript cookies in a web browser, a local SharedObject saves information permanently on the local filesystem. When a movie is closed, the information is stored in a file. When the movie is reopened, the information is available once again. This allows movies to, say, record a player's high score and make it available across multiple game sessions. Local SharedObjects are more flexible than JavaScript cookies. They allow typed data to be stored and accessed directly through object properties rather than through an awkward cookie string of name/value pairs. Specifically, SharedObjects support the following datatypes: number, string, boolean, undefined, null, array, and object (custom classes plus XML and Date). Other built-in ActionScript classes and objects (such as MovieClip and Function) cannot be stored in a SharedObject.

We do not create SharedObject instances with a constructor function. Instead, to create a new local SharedObject, we use the getLocal( ) method, which takes the name of the SharedObject to create as an parameter:

player1Info_so = SharedObject.getLocal("player1");

If a SharedObject by the specified name ("player1") already exists for the current movie, this code retrieves it from the local filesystem; if no such object exists, the Player creates it. Note the use of the suffix "_so"; this is Macromedia's official SharedObject suffix, which will enable code hinting in future versions of Flash.

After our shared object is created (or retrieved), we can add information to it by assigning custom properties to the built-in data property, such as:

player1Info_so.data.highScore = 1200;

When the movie is closed, the flush( ) method is invoked, or the SharedObject is deleted and garbage-collected, Flash attempts to save the properties of data to a binary file with an extension of .sol. The save attempt fails if the size of the saved data exceeds the user-defined size limits, as discussed under SharedObject.getLocal( ). Therefore, you should always flush( ) your data deliberately rather than relying on automatic saving, which does not allow you to handle size overages.

Once saved, the SharedObject can be retrieved later with the getLocal( ) method, exactly as it was created:

// Load the SharedObject we created earlier player1Info_so = SharedObject.getLocal("player1");

Any properties defined on the object can be used immediately after getLocal( ) is invoked to retrieve the LSO. For example, here we set the value of the hiScore_txt text field to the value of player1Info_so.data.highScore, which we created earlier:

hiScore_txt.text = player1Info_so.data.highScore;

By default, movies from any given domain can store a cumulative total of up to 100 KB of data on the user's computer. For information on requesting more space and handling storage requests that exceed the user's defined space limits, see SharedObject.flush( ).

For a prolonged example showing how to store address book contacts with a SharedObject, see the following article, written by me:

http://www.macromedia.com/desdev/mx/flash/articles/addressbook.html

Example

The following code creates a SharedObject, named userProfile, that tracks the total amount of time the user has spent viewing the movie:

var userProfile_so = SharedObject.getLocal("userProfile"); trace(userProfile_so.data.totalVisitTime); var then = 0;     this.onEnterFrame = function () {   var now = getTimer();   var frameTime = now - then;   userProfile_so.data.totalVisitTime += frameTime;   this.then = now; }