SharedObject class

Availability

Flash Player 6.

Description

Shared objects are quite powerful: they offer real-time data sharing between objects that are persistent on the user's computer. You can think of local shared objects as "cookies."

You can use local shared objects to maintain local persistence. This is the simplest way to use a shared object. For example, you can call SharedObject.getLocal() to create a shared object, such as a calculator with memory, in the player. Because the shared object is locally persistent, Flash saves its data attributes on the user's machine when the SWF file ends. The next time the SWF file runs, the calculator contains the values it had when the SWF file ended. Alternatively, if you set the shared object's properties to null before the SWF ends, the calculator opens without any prior values the next time the SWF file runs.

To create a local shared object, use the following syntax:

// Create a local shared object 
so = SharedObject.getLocal("foo");

Local disk space considerations

Local shared objects are always persistent on the client, up to available memory and disk space.

By default, Flash can save locally persistent remote shared objects up to 100K in size. When you try to save a larger object, Flash Player displays the Local Storage dialog box, which lets the user allow or deny local storage for the domain that is requesting access. Make sure your Stage size is at least 215 x 138 pixels; this is the minimum size Flash requires to display the dialog box.

If the user clicks Allow, the object is saved and SharedObject.onStatus is invoked with a code property of SharedObject.Flush.Success; if the user clicks Deny, the object is not saved and SharedObject.onStatus is invoked with a code property of SharedObject.Flush.Failed.

The user can also specify permanent local storage settings for a particular domain by right-clicking (Windows) or Control-clicking (Macintosh) while a SWF file is playing, choosing Settings, and then opening the Local Storage panel.

The following list summarizes how the user's disk space choices interact with shared objects:

If the user selects Never, objects are never saved locally, and all SharedObject.flush() commands issued for the object return false.
If the user selects Unlimited (moves the slider all the way to the right), objects are saved locally up to available disk space.
If the user selects None (moves the slider all the way to the left), all SharedObject.flush() commands issued for the object return "pending" and cause the player to ask the user if additional disk space can be allotted to make room for the object, as explained above.
If the user selects 10 KB, 100 KB, 1 MB, or 10 MB, objects are saved locally and SharedObject.flush() returns true if the object fits within the specified amount of space. If more space is needed, SharedObject.flush() returns "pending", and the player asks the user if additional disk space can be allotted to make room for the object, as explained above.

Additionally, if the user selects a value that is less than the amount of disk space currently being used for locally persistent data, the player warns the user that any locally saved shared objects will be deleted.

Note: There is no size limit in Flash Player that runs from the authoring environment.

Method summary for the SharedObject class

Method	Description
`SharedObject.clear()`	Purges all of the data from the shared object and deletes the shared object from the disk.
`SharedObject.flush()`	Immediately writes a locally persistent shared object to a local file.
`SharedObject.getLocal()`	Returns a reference to a locally persistent shared object that is available only to the current client.
`SharedObject.getSize()`	Gets the current size of the shared object, in bytes.

Property summary for the SharedObject class

Property (read-only)	Description
`SharedObject.data`	The collection of attributes assigned to the `data` property of the object; these attributes can be shared and/or stored.

Event handler summary for the SharedObject class

Event handler	Description
`SharedObject.onStatus`	Invoked every time an error, warning, or informational note is posted for a shared object.

Constructor for the SharedObject class

For information on creating local shared objects, see SharedObject.getLocal().