SharedObject.getLocal()

Availability

Flash Player 6.
Flash Media Server (not required).

Usage

SharedObject.getLocal(name [, localPath][, secure])

NOTE

The correct syntax is SharedObject.getLocal(). To assign the object to a variable, use syntax like var myLocal_so:SharedObject = SharedObject.getLocal(objectName).

Parameters

name A string value that represents the name of the object. The name can include forward slashes (/); for example, work/addresses is a legal name. Spaces are not allowed in a shared object name, nor are the following characters:

~ % & \ ; :  " ' , < > ? #

localPath An optional string parameter that specifies the full or partial path to the SWF file that created the shared object, and that determines where the shared object will be stored locally. The default value is the full path. For more information on using this parameter, see SharedObject.getRemote().

secure (Flash Player 8 only) An optional Boolean value that determines whether access to this shared object is restricted to SWF files that are delivered over an HTTPS connection. Assuming that your SWF file is delivered over HTTPS:

If this parameter is set to true, Flash Player creates a new secure shared object or gets a reference to an existing secure shared object. This secure shared object can be read from or written to only by SWF files delivered over HTTPS that call SharedObject.getLocal() with the secure parameter set to true.
If this parameter is set to false, Flash Player creates a new shared object or gets a reference to an existing shared object. This shared object can be read from or written to by SWF files delivered over non-HTTPS connections.

If your SWF file is delivered over a non-HTTPS connection and you try to set this parameter to true, the creation of a new shared object (or the access of a previously created secure shared object) fails and null is returned. Regardless of the value of this parameter, the created shared objects count toward the total amount of disk space allowed for a domain. The default value is false.

The following diagram shows the use of the secure parameter:

Returns

A reference to a shared object that is persistent locally and is available only to the current client. If Flash can't create or find the shared object (for example, if localPath was specified but no such directory exists), this method returns null.

This method fails and returns null if persistent shared object creation and storage by third-party Flash content is prohibited (does not apply to local content). Users can prohibit third-party persistent shared objects on the Global Storage Settings panel of the Settings Manager.

Description

Method; returns a reference to a locally persistent shared object that is available only to the current client. To create a shared object that is available to multiple clients by means of the Flash Media Server, use SharedObject.getRemote().

NOTE

If the user has chosen to never allow local storage for this domain, the object will not be saved locally, even if a value for localPath is specified. For more information, see Local disk space considerations.

Because local shared objects are available only to a single client, the SharedObject.onSync handler is not called when the object is changed, and there is no need to implement conflict-resolution techniques.

To avoid name collisions, Flash looks at the location of the SWF file that is creating the shared object. For example, if a SWF file at www.myCompany.com/apps/stockwatcher.swf creates a shared object named portfolio, that shared object will not conflict with another object named portfolio that was created by a SWF file at www.yourCompany.com/photoshoot.swf, because the SWF files originate from two different directories.

Example

The following example creates a shared object that stores text that is typed into a TextInput component instance. The resulting SWF file loads the saved text from the shared object when it starts playing. Every time the user presses Enter, the text in the text field is written to the shared object.

To use this example, drag a TextInput component onto the Stage, and name the instance myText_ti. Copy the following code into the main Timeline (click in an empty area of the Stage or press Escape to remove focus from the component):

// Create the shared object and set localpath to server root.
var my_so:SharedObject = SharedObject.getLocal("savedText", "/");
/* Load saved text from the shared object into the myText_ti TextInput
component. */
myText_ti.text = my_so.data.myTextSaved;
/* Assign an empty string to myText_ti if the shared object is undefined
to prevent the text input box from displaying "undefined" when
this script is first run. */
if (myText_ti.text == undefined) {
    myText_ti.text = "";
}
// Create a listener object and function for <enter> event.
var textListener:Object = new Object();
textListener.enter = function(eventObj:Object) {
    my_so.data.myTextSaved = eventObj.target.text;
    my_so.flush();
};
// Register the listener with the TextInput component instance.
myText_ti.addEventListener("enter", textListener);

The following example saves the last frame that a user entered to a local shared object kookie:

// Get the kookie.
var my_so:SharedObject = SharedObject.getLocal("kookie");
// Get the user of the kookie and go to the frame number saved for this user.
if (my_so.data.user != undefined) {
    this.user = my_so.data.user;
    this.gotoAndStop(my_so.data.frame);
}

The following code block is placed on each SWF file frame:

// On each frame, call the rememberme function to save the frame number.
function rememberme() {
    my_so.data.frame=this._currentframe;
    my_so.data.user="John";
}