SharedObject.getRemote()

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

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 class 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:

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 Media 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 Media Server, as follows:

var my_nc:NetConnection = new NetConnection();
my_nc.connect("rtmp://somedomain.com/applicationName");
var myRemote_so = SharedObject.getRemote("mo", my_nc.uri, false);
myRemote_so.connect(my_nc);

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 does not get a locally persistent remote shared object:

/* Get a remote shared object (remote01_so) that is persistent
on the server but not on the client.*/
var remote01_so:SharedObject = SharedObject.getRemote("someObject", my_nc.uri, true);

/* Get a remote shared object (remote02_so) with the same name and path
as remote01_so, but with local persistence. remote02_so will just point to the same object as remote01_so, and an onStatus message will be invoked for remote2_so with the "code" value of the information object set to "SharedObject.BadPersistence".*/
var remote02_so:SharedObject = SharedObject.getRemote("someObject", my_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 preceding example, no SharedObject.BadPersistence error will result because remote03_so does not point to the same object as remote01_so:

var remote03_so:SharedObject = SharedObject.getRemote("someObject", my_nc.uri, false);

Understanding naming conventions for remote shared objects 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.

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 SWF files 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 SWF files 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 SWF files in the same directory read each other's shared objects.

Similarly, you can use persistence to let SWF files 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:

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

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

var myRemote_so:SharedObject = (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.
var my_nc:NetConnection = new NetConnection();
my_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. */
var myRemote_so:SharedObject = SharedObject.getRemote("myObject", my_nc.uri);
my_so.connect(my_nc);

Comments

John27832 said on Nov 13, 2006 at 1:52 AM :

Bug (undefined object?):

my_so.connect(my_nc);

Should be:

myRemote_so.connect(my_nc);

SharedObject.getRemote()

Availability

Usage

Parameters

Returns

Description

Example

See also

Comments