| SharedObject.getLocal( ) Method | Flash 6 |
| returns a reference to a specified SharedObject instance |
The string name of the local SharedObject. Can contain a forward slash (/). Cannot contain the following characters: ~ % & \ ; : " ' , < > ? #
An optional string specifying part of the local path to the .sol file saved on the client computer. Must match all or part of the actual path to the movie that creates theSharedObj.
A local SharedObject named objectName, or null if an illegal localPath was specified.
The getLocal( ) method is the means by which a local SharedObject is created and retrieved. When invoked, it searches for an .sol file named objectName at a location partially specified by localPath. The .sol file contains the data needed to recreate the ActionScript SharedObject object as it was last saved. If a matching .sol file is found, getLocal( ) returns a local SharedObject with a data property populated with the values last saved to the .sol file. If no matching .sol file is found, getLocal( ) creates and returns a new SharedObject named objectName. If the specified localPath is not valid, getLocal( ) returns null, indicating that the operation failed.
When localPath is not specified, the .sol file is retrieved from an operating system-dependent location that mirrors the path to the movie that invoked getLocal( ). The path normally includes the movie name itself. For example, on my Windows XP system, a SharedObject named "player1", created by the movie so.swf at http://www.moock.org/asdg/so.swf, is retrieved from:
C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\moock.org\asdg\so.swf\player1.sol
Notice that so.swf actually is used as a directory name in the path to the .sol file. This prevents .sol filename conflicts amongst SharedObjects created by multiple movies in the same directory. For example, if the movies asteroids.swf and pong.swf (posted at moock.org/games/) both use a SharedObject named "player1", then their locations on my computer are:
// Asteroids C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\moock.org\games\asteroids.swf\player1.sol // Pong C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\moock.org\games\pong.swf\player1.sol
If both asteroids.swf and pong.swf want to share a single SharedObject, they must specify a common localPath when invoking getLocal( ). The localPath must contain part or all of the actual path to the .swf file, after the domain name. For example, pong.swf can use a localPath of "/", "/games", or "/games/pong.swf", resulting in the following file locations (again on my computer):
// For localPath "/", the location is: C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\moock.org\player1.sol // For localPath "/games", the location is: C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\moock.org\games\player1.sol // For localPath "/games/pong.swf", the location is: C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\moock.org\games\pong.swf\player1.sol
Hence, any movie in the /games directory on moock.org can access the SharedObject named "player1" by invoking getLocal( ), like this:
getLocal("player1", "/games");
And any movie on the entire moock.org site can access the SharedObject named "userInfo" by invoking getLocal( ) like this:
// Use this notation to store globally available SharedObjects
getLocal("userInfo", "/");
However, a movie in the /products directory cannot access a SharedObject created with a localPath of "/games".
|
If a movie creates a SharedObject and is then moved to a new directory on the same domain, it will thereafter look for SharedObjects according to its new location, and it will not find any SharedObjects created at its old location unless a valid localPath is specified.
Movies running on the local filesystem (say, in the Standalone Player) are assigned the domain "localhost". For example, here is the location of phoneNumbers.sol, created by a movie running on the root of any hard drive on my computer:
C:\Documents and Settings\fritz\Application Data\Macromedia\Flash Player\localhost\phoneNumbers.sol
Note that two local movies running from identical paths but on different local drives will conflict with each other because the .sol files are always stored on the system disk by default. For example, the following two movies can read and write each other's local SharedObjects:
C:\circle\demo.swf D:\circle\demo.swf
To delete an .sol file from disk, delete all the properties assigned to the corresponding SharedObject's data property. For example:
// Retrieve the SharedObject player1
player1Info_so = SharedObject.getLocal("player1");
// Delete all properties of player1Info_so.data
for (var p in player1Info_so.data) {
delete playerInfo_so.data[p];
}
A small local storage limit setting in the Player does not prevent the creation of SharedObject instances in ActionScript. However, when the movie closes or when flush( ) is invoked, the corresponding .sol file will not be created unless enough space is available. See SharedObject.flush( ) and System.showSettings( ).
In Flash 6, up through build 29 (version 6.0.29.0), when a movie is retrieved from a URL with a query string, the query string is included in the directory name that contains the local .sol file. For example, an .sol file saved from a movie loaded from:
is stored erroneously in the local directory:
www.moock.org/intro.swf?type=long/
On Windows, question marks are not allowed in filenames, so the attempt to write the local .sol file fails in the preceding case. In later versions of the Flash Player (build 6.0.30.0 or later), the .sol file is stored correctly in:
www.moock.org/intro.swf/
When using a local SharedObject in a movie loaded with a query string, use the localPath parameter of getLocal( ) to prevent the query string from being included in the directory name for the local .sol file.
Refer to the Flash Comm Server documentation for details on the SharedObject object's getRemote( ), connect( ), and close( ) methods, which are used to manage remote shared objects.
SharedObject.getSize( ), System.showSettings( )