SharedObject.getRemote

Client-Side Communication ActionScript > SharedObject.getRemote

Availability

Flash Player 6.

Flash Communication Server MX.

Usage

SharedObject.getRemote(objectName, URI [, persistence])

Note: The correct syntax is SharedObject.getRemote. To assign the object to a variable, use syntax like myRemoteSO = SharedObject.getRemote.

Parameters

objectName 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: ~ % & \ ; : " ' , < > ? #

URI The URI of the server on which the shared object will be stored. This URI must be identical to the URI of the NetConnection object to which the shared object will be connected. For more information and an example, see the SharedObject (object) entry.

persistence An optional value that specifies whether the attributes of the shared object's data property are persistent locally, remotely, or both, and that may specify where the shared object will be stored locally. Acceptable values are as follows:

	`null` (default) or `false` specifies that the shared object is not persistent on the client or server. (These values have the same effect as omitting the persistence parameter.)
	`true` specifies that the shared object is persistent only on the server.
	A full or partial local path to the shared object indicates that the shared object is persistent on the client and the server; on the client, it is stored in the specified path. On the server, it is stored in a subdirectory within the Flash Communication Server applications directory. For more information, see the description below.

Note: If the user has chosen to never allow local storage for this domain, the object will not be saved locally, even if a local path is specified for persistence. For more information, see the section on local disk space in the SharedObject (object) entry.

Returns

A reference to an object that can be shared across multiple clients. If Flash can't create or find the shared object (for example, if a local path was specified for persistence but no such directory exists), this method returns null.

Description

Method; returns a reference to an object that can be shared across multiple clients by means of the Flash Communication Server. To create a shared object that is available only to the current client, use SharedObject.getLocal.

After issuing this command, use SharedObject.connect to connect the object to the Flash Communication Server, as shown below.

conn = new NetConnection();
conn.connect("rtmp://somedomain.com/applicationName");

myObject = SharedObject.getRemote("mo", conn.uri, false);
myObject.connect(conn);

To confirm that the local and remote copies of the shared object are in sync, use the SharedObject.onSync event handler.

All clients that want to share this object must pass the same values for objectName and URI.

Understanding persistence for remote shared objects By default, the shared object is not persistent on the client or server; that is, when all clients close their connections to the shared object, it is deleted. To create a shared object that is saved locally or on the server, pass a value for persistence.

Once a value has been passed for the local persistence of a remote shared object, it is valid for the life of the object. In other words, once you have gotten a remote shared object which is not locally persistent, you cannot get the same shared object with local persistence while the shared object is active.

For example, the second line of code in the following example does not get a locally persistent remote shared object.

// Get a remote shared object (so1) that is persistent
// on the server but not on the client
so1 = SharedObject.getRemote("someObject", nc_uri, true);

// Get a remote shared object (so2) with the same name and path
// as so1, but with local persistence. 
// so2 will just point to the same object as so1, and an onStatus
// message will be invoked for so2 with the "code" value of the
// information object set to "SharedObject.BadPersistence".
so2 = SharedObject.getRemote("someObject", nc.uri, "somePath");

Also, remote shared objects that are not persistent on the server are created in a different namespace from remote shared objects that are persistent on the server. Therefore, if the following line of code is added to the above example, no SharedObject.BadPersistence error will result because so3 does not point to the same object as so1.

so3 = SharedObject.getRemote("someObject", nc.uri, false);

Understanding naming conventions for remote shared objects To avoid name collisions, Flash looks at the location of the movie that is creating the shared object. For example, if a movie 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 movie at www.yourCompany.com/photoshoot.swf, because the movies originate from two different directories.

To further avoid name collisions, Flash Player appends the application name and instance name to the end of the path of the shared object directory. Unless two movies are located in the same directory, use a shared object with the same name, and are connected to the same application with the same instance name, there will not be a name collision related to persistent shared objects on either local or remote locations.

However, if two different movies located in the same directory create objects with identical names and the same location for persistence, the names will conflict, and one object can overwrite the other without warning. Implemented properly, however, this feature lets movies in the same directory read each other's shared objects.

Similarly, you can use persistence to let movies in different directories in the same domain read and write each other's shared objects. For example, if the full path to the SWF file is www.macromedia.com/a/b/c/d/foo.swf, persistence can be any of the following:

	"/"
	"/a/"
	"/a/b/"
	"/a/b/c/"
	"/a/b/c/d/"
	"/a/b/c/d/foo.swf/"

By specifying a partial path for persistence, you can let several movies from the same domain access the same shared objects. For example, if you specify "/a/b/" for the movie named above and also for a movie whose full path is www.macromedia.com/a/b/foo2.swf, each movie can read shared objects created by the other movie. When specifying persistence, do not include a domain name.

To specify that the path for persistence should be the same as the movie, without having to explicitly specify its value, you can use MovieClip._url:

myRemoteSharedObject = (name, uri, _root._url);

Example

The following example illustrates the sequence of steps required to create a nonpersistent remote shared object.

// open connection to server
nc = new NetConnection();
nc.connect("rtmp://myServer.myCompany.com/someApp");
//
// the URI for the shared object must be the same as
// the URI of the NetConnection it's using
mySO = SharedObject.getRemote("myObject", nc.uri);
mySO.connect(nc);