PubSub Class Methods - Android

publish()

• publish() sends a message on a topic in the room.

• publish() is a suspend function. Call it from a coroutine. It returns once the server has taken the message.

Parameters

• topic

  • type: String
  • This is the name of the topic the message is published on. Subscribers of the topic receive the message, including you when you are subscribed.

• message

  • type: String
  • This is the actual message.

• options

  • type: PubSubPublishOptions
  • OPTIONAL
  • This specifies the options for publish. If you pass null or leave it out, the message is sent to everyone currently subscribed and is not stored.

• payload

  • type: JSONObject
  • OPTIONAL
  • If you need to include additional information along with a message, pass it here as a JSONObject. It comes after options, so pass it last or as a named argument.

Returns

• Unit

Example

// Publish message for 'CHAT' topic
val publishOptions = PubSubPublishOptions(persist = true)

lifecycleScope.launch {
    try {
        room.pubSub.publish("CHAT", "Hello from Android", publishOptions)

        // With a payload, which comes after the options
        val payload = JSONObject().put("type", "greeting")
        room.pubSub.publish("CHAT", "Hello from Android", publishOptions, payload)
    } catch (e: VideoSDKException) {
        // Room not joined, reconnecting, or the message could not be sent
        Log.d("VideoSDK", "publish failed: ${e.code} ${e.message}")
    }
}

caution

publish() requires a joined room. Called before onRoomJoined(), or after leaving the room, it throws a VideoSDKException with code 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED). While the room is RECONNECTING it throws 3065 (ERROR_ROOM_RECONNECTING). When the message could not be sent, it throws 4087 (PUBSUB_PUBLISH_FAILED).

Every failure except 3065 is also reported on onError. A message that failed is not sent later: the SDK doesn't queue messages while the room is reconnecting, and a message sent just before the connection dropped fails with 4087 when its acknowledgement doesn't arrive. Publish it again once the room is CONNECTED.

---

subscribe()

• subscribe() starts delivering a topic's messages to your listener.

• subscribe() is a suspend function. Call it from a coroutine. It returns once the server has confirmed the subscription.

• Right after subscribing, the topic's stored messages are replayed to the listener through onOldMessagesReceived().

Parameters

• topic:

  • type: String
  • Participants can listen to messages on that particular topic.

• listener:

  • type: PubSubMessageListener

• options:

  • type: PubSubSubscribeOptions
  • OPTIONAL
  • Controls history limit, live-message pacing and overflow behaviour. If you pass null or leave it out, the topic's whole history is replayed.

Returns

• Unit

Example

val pubSubMessageListener = object : PubSubMessageListener {
    override fun onMessageReceived(message: PubSubMessage) {
        Log.d("#message", "onMessageReceived: ${message.message}")
    }

    override fun onOldMessagesReceived(messages: List<PubSubMessage>, info: PubSubHistoryInfo) {
        Log.d("#message", "onOldMessagesReceived: $messages, isLast: ${info.isLast}")
    }
}

lifecycleScope.launch {
    try {
        // Subscribe for 'CHAT' topic
        room.pubSub.subscribe("CHAT", pubSubMessageListener)
    } catch (e: VideoSDKException) {
        // Not joined, reconnecting, subscription failed, or already subscribed
        Log.d("VideoSDK", "subscribe failed: ${e.code} ${e.message}")
    }
}

To replay only part of the topic's history, subscribe with PubSubSubscribeOptions instead:

val options = PubSubSubscribeOptions(oldMessageLimit = 100)

lifecycleScope.launch {
    try {
        room.pubSub.subscribe("CHAT", pubSubMessageListener, options)
    } catch (e: VideoSDKException) {
        Log.d("VideoSDK", "subscribe failed: ${e.code} ${e.message}")
    }
}

caution

Invalid options, or subscribing the same listener to the same topic twice, throw 3073 (ERROR_INVALID_PARAMETER) without firing onError. These are checked first.

subscribe() requires a joined room. Called before onRoomJoined(), or after leaving the room, it throws a VideoSDKException with code 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED). While the room is RECONNECTING it throws 3065 (ERROR_ROOM_RECONNECTING). When the subscription fails, it throws 4088 (PUBSUB_SUBSCRIBE_FAILED). 3035 and 4088 are also reported on onError.

When subscribe() throws, or its coroutine is cancelled, nothing is registered. Subscribe again once the room is joined and CONNECTED.

---

unsubscribe()

• unsubscribe() stops delivering a topic's messages to a listener you subscribed earlier.

• unsubscribe() is a suspend function. Call it from a coroutine. When you remove the topic's last listener, it returns once the server has dropped the subscription.

Parameters

• topic:

  • type: String
  • This is the name of the topic to be unsubscribed.

• listener:

  • type: PubSubMessageListener

Returns

• Unit

Example

// Unsubscribe for 'CHAT' topic
lifecycleScope.launch {
    try {
        room.pubSub.unsubscribe("CHAT", pubSubMessageListener)
    } catch (e: VideoSDKException) {
        // Room not joined, reconnecting, or the server call failed
        Log.d("VideoSDK", "unsubscribe failed: ${e.code} ${e.message}")
    }
}

caution

The topic itself is unsubscribed only once its last listener is removed. Removing that last listener requires a joined room: called before onRoomJoined(), or after leaving the room, it throws a VideoSDKException with code 3035, and while the room is RECONNECTING it throws 3065. When the server call fails, it throws 4089 (PUBSUB_UNSUBSCRIBE_FAILED). 3035 and 4089 are also reported on onError.

When unsubscribe() throws, the listener stays subscribed. Removing any other listener, or one that is not subscribed to the topic, never throws.