SharedObject.flush

Client-Side Communication ActionScript > SharedObject.flush

SharedObject.flush

Availability

Flash Player 6.

Flash Communication Server MX (not required).

Usage

myLocalOrRemoteSharedObject.flush([minimumDiskSpace])

Parameters

minimumDiskSpace An optional integer specifying the number of bytes that must be allotted for this object. The default value is 0.

Returns

A Boolean value of true or false, or a string value of "pending".

	If the user has permitted local information storage for objects from this domain, and the amount of space allotted is sufficient to store the object, this method returns `true`. (If you have passed a value for `minimumDiskSpace`, the amount of space allotted must be at least equal to that value for `true` to be returned).
	If the user has permitted local information storage for objects from this domain, but the amount of space allotted is not sufficient to store the object, this method returns `"pending"`.
	If the user has permanently denied local information storage for objects from this domain, or if Flash is unable to save the object for any reason, this method returns `false`.

Description

Method; immediately writes a locally persistent shared object to a local file. The shared object can be remote or local; however, this method only writes the file locally. If you don't use this method, Flash writes the shared object to a file when the shared object session ends—that is, when the SWF movie is closed, when the shared object is garbage-collected because it no longer has any references to it, or when you call SharedObject.close.

If this method returns "pending", the Flash Player displays a dialog box asking the user to increase the amount of disk space available to objects from this domain. See the section on local disk space in the SharedObject (object) entry. To allow space for the shared object to "grow" when it is saved in the future, thus avoiding return values of "pending", pass a value for minimumDiskSpace. When Flash tries to write the file, it looks for the number of bytes passed to minimumDiskSpace, instead of looking for just enough space to save the shared object at its current size.

For example, if you expect a shared object to grow to a maximum size of 500 bytes, even though it may start out much smaller, pass 500 for minimumDiskSpace. If Flash asks the user to allot disk space for the shared object, it will ask for 500 bytes. After the user allots the requested amount of space, Flash won't have to ask for more space on future attempts to flush the object (as long as its size doesn't exceed 500 bytes).

After the user responds to the dialog box, this method is called again and returns either true or false; also, SharedObject.onStatus is invoked with a code property of SharedObject.Flush.Success or SharedObject.Flush.Failed.

Example

The following function gets a shared object, SO, and fills writable properties with user-provided settings. Finally, flush is called to save the settings and allot a minimum of 1000 bytes of disk space.

this.SyncSettingsCore=function(soname, override, settings)
{
	var SO=SharedObject.getLocal(soname, "http://www.mydomain.com/app/sys");

	// settings list index
	var i;
	
	// For each specified value in settings:
	// If override is true, set the persistent setting to the provided value.
	// If override is false, fetch the persistent setting, unless there
	// isn't one, in which case, set it to the provided value.
	for (i in settings) {
		if (override || (SO.data[i] == null)) {
			SO.data[i]= settings[i];
		} else {
			settings[i]= SO.data[i];
		}
	}
	SO.flush(1000);
}

For a remote shared object, calling SharedObject.flush in the client-side ActionScript file flushes the object only on the client, not the server. The following example shows how a server-side script can flush a remote shared object on the server.

// This is a SERVER-SIDE script, not ActionScript
// Get the shared object when the application is loaded.
application.onAppStart = function()
{
	application.mySO = SharedObject.get("SharedObjName", true);
}

// When a user disconnects, flush the shared object.
application.onDisconnect = function(client)
{
	application.mySO.flush();
}

// You can also set a timer to periodically flush the shared object
// onto the hard disk on the server
application.onAppStart = function()
{
	application.mySO = SharedObject.get("SharedObjName", true);
	setInterval(function() { application.mySO.flush(); }, 60000);
}

See also

SharedObject.close

	Flash Player 6.
	Flash Communication Server MX (not required).