RealtimeStore Methods - Android

setValue()

• setValue() stores a value under a key. An existing value is overwritten. Passing null as the value deletes the key.
• setValue() is a suspend function. Call it from a coroutine.
• Everyone observing the key, including you, gets the new value in onValueChanged().

Parameters

• key

  • type: String
  • The unique key to store the data under.

• value

  • type: String?
  • The string value to be stored, at most 1024 bytes in UTF-8. Pass null to delete the key.

Returns

• Unit

Throws

• VideoSDKException when the call is refused or fails:
  • 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED) before the room is joined, or after it is left.
  • 3065 (ERROR_ROOM_RECONNECTING) while the room is reconnecting.
  • 3072 (ERROR_PAYLOAD_TOO_LARGE) when the value is larger than 1024 bytes.
  • 4045 (FAILED_TO_SET_VALUE) when key is empty or the server refuses the request.
  • 3079 (ERROR_OPERATION_TIMED_OUT) when the server does not answer in time. The value may still have been stored.
• 3035, 4045 and 3079 are also reported on onError().

Example

lifecycleScope.launch {
    try {
        room.realtimeStore.setValue("YOUR_KEY", message)
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Error: ${e.code} ${e.message}")
    }
}

---

getValue()

• getValue() retrieves the current value associated with a given key.
• getValue() is a suspend function. Call it from a coroutine.

Parameters

• key:
  • type: String
  • The key whose value you want to retrieve.

Returns

• String? - the current value, or null when the server answers with no value. A key that is not set throws 4046.

Throws

• VideoSDKException when the call is refused or fails:
  • 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED) before the room is joined, or after it is left.
  • 3065 (ERROR_ROOM_RECONNECTING) while the room is reconnecting.
  • 4046 (FAILED_TO_GET_VALUE) when the key is not set or was cleared, or the server otherwise refuses the request.
  • 3079 (ERROR_OPERATION_TIMED_OUT) when the server does not answer in time.
• 3035, 4046 and 3079 are also reported on onError().

Example

lifecycleScope.launch {
    try {
        val value: String? = room.realtimeStore.getValue("YOUR_KEY")
        Log.d("VideoSDK", "Value: $value")
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Error: ${e.code} ${e.message}")
    }
}

---

observe()

• observe() watches a key. Each time its value changes, your RealtimeStoreListener gets onValueChanged().
• observe() is a regular function, not a suspend function.
• You only get changes made after you start observing. To read the current value, call getValue().
• Adding a listener that already observes the key does nothing.
• The first listener for a key subscribes to it on the server. A change made before that subscription lands is not reported, so call getValue() if you need the current value. A failed subscription is reported on onError() with 4085.
• Called before the room is joined, or while it is reconnecting, observe() adds no listener. It reports 3035 or 3065 on onError() and does not throw.

Parameters

• key:

  • type: String
  • The key to observe.

• listener:

  • type: RealtimeStoreListener
  • An object that will receive notifications about value changes.

Throws

• IllegalArgumentException when key is empty.

Returns

• Unit

Example

val realtimeStoreListener = object : RealtimeStoreListener {
    override fun onValueChanged(newValue: String?, updatedBy: Participant?) {
        Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy?.displayName ?: "unknown"}")
        Log.d("VideoSDK", "onValueChange: New Value -> $newValue")
    }
}

room.realtimeStore.observe("YOUR_KEY", realtimeStoreListener)

---

stopObserving()

• stopObserving() stops receiving updates for a specific key and listener combination.
• It works whether or not the room is joined, and it reports nothing on onError(). A key or listener that is not being observed is ignored.

Parameters

• key:

  • type: String
  • The key you want to stop observing.

• listener:

  • type: RealtimeStoreListener
  • The listener that should be removed.

Returns

• Unit

Example

room.realtimeStore.stopObserving("YOUR_KEY", realtimeStoreListener)