# class SharedObject

#### package openfl.net

#### extends EventDispatcher

Available on all platforms

The SharedObject class is used to read and store limited amounts of data on a user's computer or on a server. Shared objects offer real-time data sharing between multiple client SWF files and objects that are persistent on the local computer or remote server. Local shared objects are similar to browser cookies and remote shared objects are similar to real-time data transfer devices. To use remote shared objects, you need Adobe Flash Media Server.

Use shared objects to do the following:

- Maintain local persistence. This is the simplest way to use a shared object, and does not require Flash Media Server. For example, you can call `SharedObject.getLocal()` to create a shared object in an application, such as a calculator with memory. When the user closes the calculator, Flash Player saves the last value in a shared object on the user's computer. The next time the calculator is run, it contains the values it had previously. Alternatively, if you set the shared object's properties to `null` before the calculator application is closed, the next time the application runs, it opens without any values. Another example of maintaining local persistence is tracking user preferences or other data for a complex website, such as a record of which articles a user read on a news site. Tracking this information allows you to display articles that have already been read differently from new, unread articles. Storing this information on the user's computer reduces server load.
- Store and share data on Flash Media Server. A shared object can store data on the server for other clients to retrieve. For example, call `SharedObject.getRemote()` to create a remote shared object, such as a phone list, that is persistent on the server. Whenever a client makes changes to the shared object, the revised data is available to all clients currently connected to the object or who later connect to it. If the object is also persistent locally, and a client changes data while not connected to the server, the data is copied to the remote shared object the next time the client connects to the object.
- Share data in real time. A shared object can share data among multiple clients in real time. For example, you can open a remote shared object that stores a list of users connected to a chat room that is visible to all clients connected to the object. When a user enters or leaves the chat room, the object is updated and all clients that are connected to the object see the revised list of chat room users.

To create a local shared object, call `SharedObject.getLocal()`. To create a remote shared object, call `SharedObject.getRemote()`.

When an application closes, shared objects are flushed, or written to a disk. You can also call the `flush()` method to explicitly write data to a disk.

Local disk space considerations. Local shared objects have some limitations that are important to consider as you design your application. Sometimes SWF files may not be allowed to write local shared objects, and sometimes the data stored in local shared objects can be deleted without your knowledge. Flash Player users can manage the disk space that is available to individual domains or to all domains. When users decrease the amount of disk space available, some local shared objects may be deleted. Flash Player users also have privacy controls that can prevent third-party domains(domains other than the domain in the current browser address bar) from reading or writing local shared objects.

Note: SWF files that are stored and run on a local computer, not from a remote server, can always write third-party shared objects to disk. For more information about third-party shared objects, see the Global Storage Settings panel in Flash Player Help.

It's a good idea to check for failures related to the amount of disk space and to user privacy controls. Perform these checks when you call `getLocal()` and `flush()`:

- `SharedObject.getLocal()` - Flash Player throws an exception when a call to this method fails, such as when the user has disabled third-party shared objects and the domain of your SWF file does not match the domain in the browser address bar.
- `SharedObject.flush()` - Flash Player throws an exception when a call to this method fails. It returns `SharedObjectFlushStatus.FLUSHED` when it succeeds. It returns `SharedObjectFlushStatus.PENDING` when additional storage space is needed. Flash Player prompts the user to allow an increase in storage space for locally saved information. Thereafter, the `netStatus` event is dispatched with an information object indicating whether the flush failed or succeeded.

If your SWF file attempts to create or modify local shared objects, make sure that your SWF file is at least 215 pixels wide and at least 138 pixels high(the minimum dimensions for displaying the dialog box that prompts users to increase their local shared object storage limit). If your SWF file is smaller than these dimensions and an increase in the storage limit is required, `SharedObject.flush()` fails, returning `SharedObjectFlushedStatus.PENDING` and dispatching the `netStatus` event.

Remote shared objects. With Flash Media Server, you can create and use remote shared objects, that are shared in real-time by all clients connected to your application. When one client changes a property of a remote shared object, the property is changed for all connected clients. You can use remote shared objects to synchronize clients, for example, users in a multi-player game.

Each remote shared object has a `data` property which is an Object with properties that store data. Call `setProperty()` to change an property of the data object. The server updates the properties, dispatches a `sync` event, and sends the properties back to the connected clients.

You can choose to make remote shared objects persistent on the client, the server, or both. By default, Flash Player saves locally persistent remote shared objects up to 100K in size. When you try to save a larger object, Flash Player displays the Local Storage dialog box, which lets the user allow or deny local storage for the shared object. Make sure your Stage size is at least 215 by 138 pixels; this is the minimum size Flash requires to display the dialog box.

If the user selects Allow, the server saves the shared object and dispatches a `netStatus` event with a `code` property of `SharedObject.Flush.Success`. If the user select Deny, the server does not save the shared object and dispatches a `netStatus` event with a `code` property of `SharedObject.Flush.Failed`.

@event asyncError Dispatched when an exception is thrown asynchronously -

                  that is, from native asynchronous code.

@event netStatus Dispatched when a SharedObject instance is reporting its

                  status or error condition. The `netStatus`
                  event contains an `info` property, which is an
                  information object that contains specific information
                  about the event, such as whether a connection attempt
                  succeeded or whether the shared object was successfully
                  written to the local disk.

@event sync Dispatched when a remote shared object has been updated

                  by the server.

### Variables

###

`client:Dynamic`

###

`read onlydata:Dynamic`

The collection of attributes assigned to the `data` property of the object; these attributes can be shared and stored. Each attribute can be an object of any ActionScript or JavaScript type - Array, Number, Boolean, ByteArray, XML, and so on. For example, the following lines assign values to various aspects of a shared object:

For remote shared objects used with a server, all attributes of the `data` property are available to all clients connected to the shared object, and all attributes are saved if the object is persistent. If one client changes the value of an attribute, all clients now see the new value.

###

`write onlyfps:Float`

###

`objectEncoding:UInt`

###

`read onlywrite onlysize:UInt`

The current size of the shared object, in bytes.

Flash calculates the size of a shared object by stepping through all of its data properties; the more data properties the object has, the longer it takes to estimate its size. Estimating object size can take significant processing time, so you may want to avoid using this method unless you have a specific need for it.

### Methods

###

`clear ():Void`

For local shared objects, purges all of the data and deletes the shared object from the disk. The reference to the shared object is still active, but its data properties are deleted.

For remote shared objects used with Flash Media Server, `clear()` disconnects the object and purges all of the data. If the shared object is locally persistent, this method also deletes the shared object from the disk. The reference to the shared object is still active, but its data properties are deleted.

###

`close ():Void`

###

`connect (myConnection:NetConnection, ?params:String):Void`

###

`flush (minDiskSpace:Int = 0):SharedObjectFlushStatus`

Immediately writes a locally persistent shared object to a local file. If you don't use this method, Flash Player writes the shared object to a file when the shared object session ends - that is, when the SWF file is closed, when the shared object is garbage-collected because it no longer has any references to it, or when you call `SharedObject.clear()` or `SharedObject.close()`.

If this method returns `SharedObjectFlushStatus.PENDING`, Flash Player displays a dialog box asking the user to increase the amount of disk space available to objects from this domain. To allow space for the shared object to grow when it is saved in the future, which avoids return values of `PENDING`, pass a value for `minDiskSpace`. When Flash Player tries to write the file, it looks for the number of bytes passed to `minDiskSpace`, instead of looking for 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 might start out much smaller, pass 500 for `minDiskSpace`. If Flash asks the user to allot disk space for the shared object, it asks 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. A `netStatus` event is dispatched with a `code` property of `SharedObject.Flush.Success` or `SharedObject.Flush.Failed`.

Parameters:

`minDiskSpace` | The minimum disk space, in bytes, that must be allotted for this object.

Throws:

`Error` | Flash Player cannot write the shared object to disk. This error might occur if the user has permanently disallowed local information storage for objects from this domain. Note: Local content can always write shared objects from third-party domains(domains other than the domain in the current browser address bar) to disk, even if writing of third-party shared objects to disk is disallowed.

Returns:

Either of the following values: * `SharedObjectFlushStatus.PENDING`: 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. Flash Player prompts the user to allow more space. To
        allow space for the shared object to grow when it is saved, thus
        avoiding a `SharedObjectFlushStatus.PENDING` return
        value, pass a value for `minDiskSpace`.
         * `SharedObjectFlushStatus.FLUSHED`: The shared
        object has been successfully written to a file on the local
        disk.

###

`send (arguments:Array<Dynamic>):Void`

###

`setDirty (propertyName:String):Void`

###

`setProperty (propertyName:String, ?value:Object):Void`

### Static variables

###

`staticdefaultObjectEncoding:Int`

### Static methods

###

`staticgetLocal (name:String, ?localPath:String, secure:Bool = false):SharedObject`

Returns a reference to a locally persistent shared object that is only available to the current client. If the shared object does not already exist, this method creates one. If any values passed to `getLocal()` are invalid or if the call fails, Flash Player throws an exception.

The following code shows how you assign the returned shared object reference to a variable:

`var so:SharedObject = SharedObject.getLocal("savedData");`

Note: If the user has chosen to never allow local storage for this domain, the object is not saved locally, even if a value for `localPath` is specified. The exception to this rule is local content. Local content can always write shared objects from third-party domains(domains other than the domain in the current browser address bar) to disk, even if writing of third-party shared objects to disk is disallowed.

To avoid name conflicts, Flash looks at the location of the SWF file 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 does 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 different directories.

Although the `localPath` parameter is optional, you should give some thought to its use, especially if other SWF files need to access the shared object. If the data in the shared object is specific to one SWF file that will not be moved to another location, then use of the default value makes sense. If other SWF files need access to the shared object, or if the SWF file that creates the shared object will later be moved, then the value of this parameter affects how accessible the shared object will be. For example, if you create a shared object with `localPath` set to the default value of the full path to the SWF file, no other SWF file can access that shared object. If you later move the original SWF file to another location, not even that SWF file can access the data already stored in the shared object.

To avoid inadvertently restricting access to a shared object, use the `localpath` parameter. The most permissive approach is to set `localPath` to `/`(slash), which makes the shared object available to all SWF files in the domain, but increases the likelihood of name conflicts with other shared objects in the domain. A more restrictive approach is to append `localPath` with folder names that are in the full path to the SWF file. For example, for a `portfolio` shared object created by the SWF file at www.myCompany.com/apps/stockwatcher.swf, you could set the `localPath` parameter to `/`, `/apps`, or `/apps/stockwatcher.swf`. You must determine which approach provides optimal flexibility for your application.

When using this method, consider the following security model:

- You cannot access shared objects across sandbox boundaries.
- Users can restrict shared object access by using the Flash Player Settings dialog box or the Settings Manager. By default, an application can create shared objects of up 100 KB of data per domain. Administrators and users can also place restrictions on the ability to write to the file system.

Suppose you publish SWF file content to be played back as local files (either locally installed SWF files or EXE files), and you need to access a specific shared object from more than one local SWF file. In this situation, be aware that for local files, two different locations might be used to store shared objects. The domain that is used depends on the security permissions granted to the local file that created the shared object. Local files can have three different levels of permissions:

1. Access to the local filesystem only.
2. Access to the network only.
3. Access to both the network and the local filesystem.

Local files with access to the local filesystem(level 1 or 3) store their shared objects in one location. Local files without access to the local filesystem(level 2) store their shared objects in another location.

You can prevent a SWF file from using this method by setting the `allowNetworking` parameter of the the `object` and `embed` tags in the HTML page that contains the SWF content.

For more information, see the Flash Player Developer Center Topic: Security.

Parameters:

`name` | 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: `~ % & \ ; : " ' , < > ? #`
`localPath` | The full or partial path to the SWF file that created the shared object, and that determines where the shared object will be stored locally. If you do not specify this parameter, the full path is used.
`secure` | Determines whether access to this shared object is restricted to SWF files that are delivered over an HTTPS connection. If your SWF file is delivered over HTTPS, this parameter's value has the following effects: If this parameter is set to `true`, Flash Player creates a new secure shared object or gets a reference to an existing secure shared object. This secure shared object can be read from or written to only by SWF files delivered over HTTPS that call `SharedObject.getLocal()` with the `secure` parameter set to `true`. If this parameter is set to `false`, Flash Player creates a new shared object or gets a reference to an existing shared object that can be read from or written to by SWF files delivered over non-HTTPS connections. If your SWF file is delivered over a non-HTTPS connection and you try to set this parameter to `true`, the creation of a new shared object
                (or the access of a previously created secure shared
object) fails and `null` is returned. Regardless of the value of this parameter, the created shared objects count toward the total amount of disk space allowed for a domain. The following diagram shows the use of the `secure` parameter:

Throws:

`Error` | Flash Player cannot create the shared object for whatever reason. This error might occur is if persistent shared object creation and storage by third-party Flash content is prohibited(does not apply to local content). Users can prohibit third-party persistent shared objects on the Global Storage Settings panel of the Settings Manager, located at [http://www.adobe.com/support/documentation/en/flashplayer/help/settings_manager03.html](http://www.adobe.com/support/documentation/en/flashplayer/help/settings_manager03.html).

Returns:

A reference to a shared object that is persistent locally and is available only to the current client. If Flash Player can't create or find the shared object(for example, if `localPath` was specified but no such directory exists), this method throws an exception.

###

`staticgetRemote (name:String, ?remotePath:String, persistence:Dynamic = false, secure:Bool = false):SharedObject`

### Inherited Variables

### Inherited Methods

#### Defined by EventDispatcher

###

`addEventListener (type:String, listener:Dynamic ‑> Void, useCapture:Bool = false, priority:Int = 0, useWeakReference:Bool = false):Void`

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. You can register event listeners on all nodes in the display list for a specific type of event, phase, and priority.

After you successfully register an event listener, you cannot change its priority through additional calls to `addEventListener()`. To change a listener's priority, you must first call `removeListener()`. Then you can register the listener again with the new priority level.

Keep in mind that after the listener is registered, subsequent calls to `addEventListener()` with a different `type` or `useCapture` value result in the creation of a separate listener registration. For example, if you first register a listener with `useCapture` set to `true`, it listens only during the capture phase. If you call `addEventListener()` again using the same listener object, but with `useCapture` set to `false`, you have two separate listeners: one that listens during the capture phase and another that listens during the target and bubbling phases.

You cannot register an event listener for only the target phase or the bubbling phase. Those phases are coupled during registration because bubbling applies only to the ancestors of the target node.

If you no longer need an event listener, remove it by calling `removeEventListener()`, or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists(unless the `useWeakReference` parameter is set to `true`).

Copying an EventDispatcher instance does not copy the event listeners attached to it.(If your newly created node needs an event listener, you must attach the listener after creating the node.) However, if you move an EventDispatcher instance, the event listeners attached to it move along with it.

If the event listener is being registered on a node while an event is being processed on this node, the event listener is not triggered during the current phase but can be triggered during a later phase in the event flow, such as the bubbling phase.

If an event listener is removed from a node while an event is being processed on the node, it is still triggered by the current actions. After it is removed, the event listener is never invoked again(unless registered again for future processing).

Parameters:

`type` | The type of event.
`useCapture` | Determines whether the listener works in the capture phase or the target and bubbling phases. If `useCapture` is set to `true`, the listener processes the event only during the capture phase and not in the target or bubbling phase. If `useCapture` is `false`, the listener processes the event only during the target or bubbling phase. To listen for the event in all three phases, call `addEventListener` twice, once with `useCapture` set to `true`, then again with `useCapture` set to `false`.
`priority` | The priority level of the event listener. The priority is designated by a signed 32-bit integer. The higher the number, the higher the priority. All listeners with priority n are processed before listeners of priority n-1. If two or more listeners share the same priority, they are processed in the order in which they were added. The default priority is 0.
`useWeakReference` | Determines whether the reference to the listener is strong or weak. A strong reference(the default) prevents your listener from being garbage-collected. A weak reference does not. Class-level member functions are not subject to garbage collection, so you can set `useWeakReference` to `true` for class-level member functions without subjecting them to garbage collection. If you set `useWeakReference` to `true` for a listener that is a nested inner function, the function will be garbage-collected and no longer persistent. If you create references to the inner function(save it in another variable) then it is not garbage-collected and stays persistent.

Throws:

`ArgumentError` | The `listener` specified is not a function.

###

`dispatchEvent (event:Event):Bool`

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the `dispatchEvent()` method is called.

Parameters:

`event` | The Event object that is dispatched into the event flow. If the event is being redispatched, a clone of the event is created automatically. After an event is dispatched, its `target` property cannot be changed, so you must create a new copy of the event for redispatching to work.

Throws:

`Error` | The event dispatch recursion limit has been reached.

Returns:

A value of `true` if the event was successfully dispatched. A value of `false` indicates failure or that `preventDefault()` was called on the event.

###

`hasEventListener (type:String):Bool`

Checks whether the EventDispatcher object has any listeners registered for a specific type of event. This allows you to determine where an EventDispatcher object has altered handling of an event type in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, use `willTrigger()`.

The difference between `hasEventListener()` and `willTrigger()` is that `hasEventListener()` examines only the object to which it belongs, whereas `willTrigger()` examines the entire event flow for the event specified by the `type` parameter.

When `hasEventListener()` is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

`type` | The type of event.

Returns:

A value of `true` if a listener of the specified type is registered; `false` otherwise.

###

`removeEventListener (type:String, listener:Dynamic ‑> Void, useCapture:Bool = false):Void`

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters:

`type` | The type of event.
`useCapture` | Specifies whether the listener was registered for the capture phase or the target and bubbling phases. If the listener was registered for both the capture phase and the target and bubbling phases, two calls to `removeEventListener()` are required to remove both, one call with `useCapture()` set to `true`, and another call with `useCapture()` set to `false`.

###

`toString ():String`

###

`willTrigger (type:String):Bool`

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. This method returns `true` if an event listener is triggered during any phase of the event flow when an event of the specified type is dispatched to this EventDispatcher object or any of its descendants.

The difference between the `hasEventListener()` and the `willTrigger()` methods is that `hasEventListener()` examines only the object to which it belongs, whereas the `willTrigger()` method examines the entire event flow for the event specified by the `type` parameter.

When `willTrigger()` is called from a LoaderInfo object, only the listeners that the caller can access are considered.

Parameters:

`type` | The type of event.

Returns:

A value of `true` if a listener of the specified type will be triggered; `false` otherwise.