Have you explored the newest version of the OpenTok platform? Check out OpenTok 2.0, built on top of WebRTC. Learn more

StateManager class

The StateManager lets you work with the state of a session. You obtain a StateManager object by calling the getStateManager() method of a Session object. You can use the StateManager object for a session to set the state of a session and to add event listeners for state changes.

A session's state is a set of key-value pairs. When you call the set() method, you pass either a pair of strings — a key and a value — or you pass in an Object that contains a set of key-value pairs. For example, the following code sets the "foo" key to "bar":

var stateManager = session.getStateManager();
stateManager.set("key", "bar");

(The example assumes that the session variable contains a TokBox Session object that you have connected to.)

The following code sets multiple properties at once:

var stateManager = session.getStateManager();
var newStateValues = {backgroundColor: "FFCC00", caption: "My dog has fleas."};
stateManager.set(newStateValues);

When a new key-value pair (or set of pairs) is set, the StateManager object dispatches a changed event (defined by the StateChangedEvent class). The StateManager object also dispatches an event for each key-value pair change, and the type property of the event is changed:keyName, where "keyName" is the name of the key. For example, the following code sets up two event listeners: one for all changes to state changes and one for all changes to the foo key only:

var stateManager = session.getStateManager();
stateManager.addEventListener("changed", stateChangedHandler);
stateManager.addEventListener("changed:foo", fooStateChangedHandler);

function stateChangedHandler(event) {
    for (key in event.changedValues) {
        alert("Changed state. Key: " + key + ". Value: " + event.changedValues[key]);
    }
}

function fooStateChangedHandler(event) {
    alert("Foo changed state. Value: " + event.changedValues["foo"]);
}

Set a key to null to delete it from the state:

var stateManager = session.getStateManager();
stateManager.set("foo", null);

Note that the changed values are defined in the changedValues property of the StateChangedEvent object. For the initial event dispatched, the changedValues property contains current state. For a changed event, it contains the entire current state, with a key-value pair for each property in the state. For a changed:keyName event, the initial event's changedValues property contains one property, pertaining to the specific key's (and the value is set to null if the key is not set in the state). An initial event is dispatched to each unique event listener you register, and the event's changedValues property reflects the state at the time you add the event listener.

For subsequent events (after the initial event), the changedValues property contains key-value pairs for changed properties in the state. For a changed:keyName event, the changedValues property contains one property, for the specific key, and the event is only dispatched when that key's value changes. A value is set to null when a key is deleted.

When a key name begins with moderator_ or publisher_, the property can only be set (or changed) by a client that has a token that has been assigned the role of moderator or publisher. However any client can subscribe to any state property. For example, if a client that is not assigned the role of moderator calls the following lines of code, the StateManager object dispatching a changeFailed event (defined by the ChangeFailedEvent class):

var stateManager = session.getStateManager();
stateManager.set("moderator_foo", "bar");

There are other limitations when calling the set() method. Failure to conform to these limitations results in the StateManager object dispatching a changeFailed event:

  • Keys must be 100 characters or less, and they cannot contain spaces.
  • Value must be 1000 characters or less. Values must be String objects. Setting a value to null deletes the key.
  • You are limited to setting up to 20 keys.

StateManager methods

StateManager objects have the following methods:

Method Description
addEventListener(eventType:String, listener:Function) Registers a method as an event listener for a specific event.
removeEventListener(type:String, listener:Function) Removes an event listener for a specific event.
set(param1:Object, [param2:String]) Sets state data for a session.

addEventListener(type:String, listener:Function)

Registers a method as an event listener for a specific event.

Parameters

type (String) — The string identifying the type of event. See StateManager events.

listener (Function) — The function to be invoked when the StateManager object dispatches the event.

If a handler is not registered for an event, the event is ignored locally. If the JavaScript method does not exist, the event is ignored locally.

Throws an exception if the listener name is invalid.

removeEventListener(type:String, listener:Function)

Removes an event listener for a specific event.

Throws an exception if the listener name is invalid.

Parameters

type (String) — The string identifying the type of event.

listener (Function) — The event listener function to remove.

set(param1:Object, [param2:String])

Lets you set a state change for a session's state.

A session's state is a set of key-value pairs. When you call the set() method, you pass either a pair of strings — a key and a value — or you pass in an Object that contains a set of key-value pairs. For example, the following code sets the "foo" key to "bar":

var stateManager = session.getStateManager();
stateManager.set("key", "bar");

(The example assumes that the session variable contains a TokBox Session object that you have connected to.)

The following code sets multiple properties at once:

var stateManager = session.getStateManager();
var newStateValues = {backgroundColor: "FFCC00", caption: "My dog has fleas."};
stateManager.set(newStateValues);

Parameters

param1 (Object) — Either a String, specifying the key to set, or an Object containing key-value pairs.

param2 (String) — Optional. The value to assign to the key specified by param1. Specify the param2 value only if you pass a String value (the key name) to param1

Events

changed (StateChangedEvent) — The state was set. The changedValues property contains the changed data.

changed:keyName (StateChangedEvent) — The state data for the key matching keyName was set. The changedValues property contains the changed data.

changeFailed (ChangeFailedEvent) — The attempt to set data failed. The event includes a reason and reasonCode property that define the reason that the attempt to change data failed. The failedValues property contains the data that you tried to set.

When a key name begins with moderator_ or publisher_, the property can only be set (or changed) by a client that has a token that has been assigned the role of moderator or publisher. However any client can subscribe to any state property. For example, if a client that is not assigned the role of moderator calls the following lines of code, the StateManager object dispatching a changeFailed event:

var stateManager = session.getStateManager();
				stateManager.set("moderator_foo", "bar");

There are other limitations when calling the set() method. Failure to conform to these limitations results in the StateManager object dispatching a changeFailed event:

  • Keys must be 100 characters or less, and they cannot contain spaces.
  • Each value must be 1000 characters or less. Values must be String objects. Set a value to null to delete the key.
  • You are limited to setting up to 20 keys.

StateManager events

A StateManager object can dispatch two types of event:

Event type Event class Description
"changed" StateChangedEvent The StateManager object dispatches a changed event when any property in the state data changed.
"changed:keyName" StateChangedEvent The StateManager object dispatches this type of event when a specific key, corresponding to the specified keyName, changes.
"changeFailed ChangeFailedEvent The attempt to set data failed. The event includes a reason and reasonCode property, which define the reason for which the attempt to change data failed. The failedValues property contains the data that you tried to set.

IRC Live Chat

Have a quick question? Chat with TokBox Support on IRC. Join chat