Recipe 16.4 Saving a Local Shared Object

16.4.1 Problem

You want to save local shared object data to the client computer.

16.4.2 Solution

Use the SharedObject.flush( ) method in the Flash movie.

16.4.3 Discussion

Flash automatically attempts to save local shared object data to disk when the movie is unloaded from the Player (such as when the Player closes). However, it is not a good practice to rely on the automatic save functionality, as there are several reasons why the data might not save successfully. Instead, you should explicitly instruct the local shared object to write the data to disk using the SharedObject.flush( ) method:

flushResult = my_l_so.flush(  );

When the flush( ) method is invoked, it attempts to write the data to the client computer. The result of a flush( ) invocation can be one of three possibilities:

• If the user set the local storage for the domain to "Never", the data is not saved and the method returns false.

• If the amount of disk space required to save the local shared object's data is less than the local storage setting for the domain, the data is written to disk and the method returns true.

• If the user has not allotted as much space as the shared object data requires, he is prompted to allow enough space or to deny access to save the data. When this happens, the method returns "pending". If the user chooses to grant access, the extra space is automatically allotted and the data is saved.

In the third case, in which the flush( ) method returns "pending", there is an additional step you can take to determine whether the user grants or denies access to save the data. When the user makes a selection from the automatic prompt, the onStatus( ) method of the shared object is automatically invoked. It is up to you to define the method to handle the results in the way that is appropriate for your application. When the callback method is invoked, it is passed a parameter. The parameter is an object with a code property that is set to "SharedObject.Flush.Success" if the user granted access or "SharedObject.Flush.Failed" if the user denied access.

Here is an example that invokes flush( ) to save the data explicitly and then handles the possible responses:

my_l_so = SharedObject.getLocal("myFirstLSO");
my_l_so.data.val = "a value";
result = my_l_so.flush(  );
// If the flush operation completes, check the result. 
// If the operation is pending, the onStatus(  ) method of the 
// shared object is invoked before any result is returned.
if (result) {
  // Saved successfully. Place any code here that you want to execute after the data
  // was successfully saved.
}
else if (!result) {
  // This means the user has the local storage settings to 'Never.' If it is
  // important to save your data, you may want to alert the user here. Also, if you
  // want to make it easy for the user to change his settings, you can open the local
  // storage tab of the Player Settings dialog box with the following code:
  // System.showSettings(1);.
}

// Define the onStatus(  ) method for the shared object. 
// It is invoked automatically after the user makes a selection 
// from the prompt that occurs when flush(  ) returns "pending."
my_l_so.onStatus = function (infoObj) {
  if (infoObj.code == "SharedObject.Flush.Success") {
    // If the infoObj.code property is "SharedObject.Flush.Success", it means the
    // user granted access. Place any code here that you want to execute when the
    // user grants access.
  } else if (infoObj.code == "SharedObject.Flush.Failed") {
    // If the infoObj.code property is "SharedObject.Flush.Failed", it means the user
    // denied access. Place any code here that you want to execute when the user
    // denies access.
  }
};

If you know in advance that a shared object is likely to continue to increase in size with each session, it is prudent to request a larger amount of local storage space when the shared object is created. Otherwise, each time the current allotted space is exceeded, the user is prompted again to accept or deny the storage request. Setting aside extra space avoids repeatedly asking the user for permission to store incrementally more data. You can request a specific amount of space when you call the flush( ) method by passing it a number of bytes to set aside for the shared object:

// Request 500 KB of space for the shared object.
result = mySO.flush(1024 * 500);