S > SharedObject (object) |  |

SharedObject (object)

SharedObject

Communications/SharedObject

Availability

Flash Player 6.

Note: The SharedObject object is available only in the expert mode of the Actions panel.

Shared objects are quite powerful: they offer real-time data sharing between objects that are persistent on the local location. 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 movie ends. The next time the movie runs, the calculator contains the values it had when the movie ended. Alternatively, if you set the shared object's properties to `null` before the movie ends, the calculator opens without any prior values the next time the movie 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, Macromedia Flash MX can save locally persistent remote shared objects up to 100 K in size. When you try to save a larger object, the Macromedia Flash Player 6 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 Macromedia Flash MX 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 movie 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 Macromedia Flash MX 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 Macromedia Flash MX 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, Macromedia Flash MX warns the user that any locally saved shared objects will be deleted.

Note: There is no size limit in the Macromedia Flash Player 6 that runs from the Authoring environment; the limit applies only to the stand-alone player.

Method summary for the SharedObject object

Method | Description
--- | ---
`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.

SharedObject

Communications/SharedObject/Methods

Property summary for the SharedObject object

Property (read-only) | Description
--- | ---
`SharedObject.data` | The collection of attributes assigned to the data property of the object, which will be shared and/or stored.

SharedObject

Communications/SharedObject/Properties

Event handler summary for the SharedObject object

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

SharedObject

Communications/SharedObject/Events

Constructor for the SharedObject object

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

SharedObject information objects

The SharedObject object provides an `onStatus` event handler that uses an information object for providing information, status, or error messages. To respond to this event handler, you must create a function to process the information object, and you must know the format and contents of the information object returned.

In addition to the specific `onStatus` method, Macromedia Flash MX also provides a "super" function called `system.onStatus`. If `onStatus` is invoked for a particular object and there is no function assigned to respond to it, Macromedia Flash MX processes a function assigned to `system.onStatus` if it exists.

The following example illustrates how you can create functions to process information objects sent by the `onStatus` method.

    //	 Create generic function
    system.onStatus = function(genericError)
    {
    	// Your script would do something more meaningful here
    	trace("An error has occurred. Please try again.");
    };

By default, every information object has a `code` property containing a string that describes the result of the `onStatus` method, and a `class` property containing a string that is either `"status"`, `"warning"`, or "`error"`. Some information objects have additional default properties, which provide more information about the reason `onStatus` was invoked, as displayed in the following table:

code | class | Meaning
--- | --- | ---
`SharedObject.Flush.Failed` | Error | A `SharedObject.flush` command that returned `"pending"` has failed (the user did not allot additional disk space for the shared object).
`SharedObject.Flush.Success` | Status | A `SharedObject.flush` command that returned `"pending"` has been successfully completed (the user allotted additional disk space for the shared object).