Data session

LINE Planet provides a data session that allows applications to send and receive application data. For example, an application can send or receive text messages to enable text chatting during a group call (conference).

Keep in mind that the data communication protocol must be defined by the application. The data session provided by LINE Planet serves only as a communication channel for application-defined data communication protocols.

Supported call type	Minimum SDK version
1-to-1 call, group call	PlanetKit 3.2

Note

• LINE Planet is a real-time communication platform. On the internet, real-time communication is not guaranteed because packets may be lost or delayed depending on network conditions. These network impairments affect real-time communication quality, and in severe cases, calls can be interrupted. Heavy traffic can also cause various network impairments. If your application uses a data session, note that data communication might degrade the quality of voice or video calls.
• A data session is available only after a call is set up or participants join a group call.

Data session specifications

Data session APIs are directional, so there are sender and receiver. For each side, applications should request a data session with a pre-defined stream ID. Here, "pre-defined" means that the stream ID value must be defined between both sides before the implementation stage.

Stream ID

A stream ID is an identifier for data communication. The characteristics of stream IDs are as follows:

• Stream IDs are not dynamically generated. They are assigned during the design stage of the application and remain constant throughout the service operation. This means that if a receiver is unable to handle a particular stream ID, applications must stop using that specific stream ID.
• Stream IDs must be chosen from a specific range of integers, from 100 through 999.
• A single stream ID can be used by both the sender and the receiver. This means that the same identifier is used for communication in both directions, allowing for a bidirectional flow of data.

Subgroup support

Data sessions belonging to a subgroup can be used to send and receive data between the subgroup members. Even if the same stream ID is used, if the subgroups are different, different data sessions are defined and used.

Subgroups are separated by subgroup name. If the subgroup name is null, it means the main room.

Note

• To use a data session within a subgroup in an application, the "dataSession" subgroup attribute must be true.
• Data sessions within a subgroup are supported in PlanetKit 4.1 or higher.

For more information about subgroups, refer to the documents in the Subgroup category.

Lifetime of a data session

The lifetime of a data session by call type is as follows:

• 1-to-1 call
  • Once a data session is created, it remains active until the call is ended.
• Group call - main room data session
  • Once a data session is created, it remains active until the group call is ended.
• Group call - subgroup data session
  • Once a data session is created for a specific subgroup, it remains active while the participant who created the data session remains subscribed to the subgroup. When the participant unsubscribes from the subgroup, the data session is deactivated.

Data session type

Data sessions have four types. Applications should choose which type to use, depending on application data characteristics.

Data session type	Description
Reliable message	Lost packets are retransmitted. The onDataReceived callback is called when each message is aggregated, so the callback is called as many times as send() is called.
Unreliable message	Lost packets are not retransmitted. The onDataReceived callback is called when each message is aggregated. When there is no packet loss, the callback is called as many times as send() is called. When there is packet loss, however, the callback can be called fewer times than send().
Reliable bytes	Lost packets are retransmitted. PlanetKit fragments data if the application data is large. However, packets are not aggregated on the receiver side, so applications should aggregate the fragmented packets.
Unreliable bytes	Lost packets are not retransmitted. PlanetKit fragments data if the application data is large. However, packets are not aggregated on the receiver side, so applications should aggregate the fragmented packets.

Maximum transmission bandwidth

Data sessions cannot transmit data at more than 2 Mbps. This is because data session bandwidth can degrade voice or video quality. For this reason, PlanetKit controls the data rate. If your application is sending excessive traffic, PlanetKit generates an exception event to notify your application that the data transmission should be slowed down.

Sender side

This section describes APIs and tasks for the sender side.

Sender side APIs

The following APIs are used by the sender side.

API	Description
makeOutboundDataSession()	Creates an outbound data session with a stream ID
getOutboundDataSession()	Retrieves a previously created outbound data session
send()	Sends data using the outbound data session
changeDestination()	Changes the destination of data

Create an outbound data session

To create an outbound data session, use makeOutboundDataSession().

fun makeOutboundDataSession(
    IntRange(from = 100, to = 999) streamId: Int,
    type: PlanetKitDataSessionType,
    listener: OutboundDataSessionListener
)

Parameter	Description
streamId	Stream identifier defined by the application. For more information, see Stream ID.
type	Data session type. For more information, see Data session type.
listener	Listener for handling events related to the outbound data session

The result of creating an outbound data session can be determined by the callback of the listener.

• If an outbound data session is created successfully, onSessionMade is called.
• If an outbound data session could not be created, onError is called with the reason of the failure. For more information, see Data session fail reason.

After the outbound session is created, onTooLongQueueData reports the status of data traffic. Refer to the following table and take necessary action in your application.

Event	Description	Action required by an application
onTooLongQueueData (isTriggered=true)	Data traffic is too heavy.	Stop sending data or reduce the transmission bitrate.
onTooLongQueueData (isTriggered=false)	Network conditions become better.	Send more data.

Note

If onTooLongQueueData events continue to occur, it can negatively impact the quality of voice and video communication. To mitigate this, you should reduce the data transmission bitrate.

Retrieve an outbound data session

To retrieve an existing outbound data session, use getOutboundDataSession().

fun getOutboundDataSession(streamId: Int): PlanetKitOutboundDataSession?

Parameter	Description
streamId	Stream ID. For more information, see Stream ID.

Send data

To send data using an outbound data session, use send() of PlanetKitOutboundDataSession.

fun send(data: ByteBuffer, timestamp: Long): Boolean

Parameter	Description
data	Data to send. The maximum size for "Message" type is 128 kBytes, and the maximum size for other types is 4 MBytes.
timestamp	User-defined timestamp to identify the data

Change the destination of data

To change the destination of data, use changeDestination() of PlanetKitOutboundDataSession.

Note

This method is effective for group calls only.

fun changeDestination(peer: PlanetKitUser?, userData: Any?, callback: PlanetKitRequestCallback?): Boolean

Parameter	Description
peer	Peer who will receive the data. Setting to null has the following effect: - For a main room data session, send data to all peers in the room. - For a subgroup data session, send data to all subgroup members.
userData	User data for the callback
callback	Optional callback to receive the result of the request

Receiver side

This section describes APIs and tasks for the receiver side.

Receiver side APIs

The following APIs are used by the receiver side.

API	Description
onDataSessionIncoming	Called when the sender newly created an outbound data session
makeInboundDataSession()	Creates an inbound data session to receive data
getInboundDataSession()	Retrieves a previously created inbound data session
unsupportInboundDataSession()	Informs the sender that the application do not support the stream ID

Get notified of an incoming data session

When the sender creates a new data session, the receiver side is notified of the event through onDataSessionIncoming.

// For 1-to-1 calls
fun onDataSessionIncoming(call: PlanetKitCall, streamId: Int, type: PlanetKitDataSessionType)

// For group calls
fun onDataSessionIncoming(conference: PlanetKitConference, subgroupName: String?, streamId: Int, type: PlanetKitDataSessionType)

Parameter	Description
call or conference	Instance of the 1-to-1 call or group call
subgroupName	(Group calls only) Subgroup name. null means the main room.
streamId	Stream ID set by the sender. For more information, see Stream ID.
type	Data session type. For more information, see Data session type.

In a group call, a participant who joined after someone started data streaming using the main room data session will also receive onDataSessionIncoming when receiving data upon completion of the join flow. In this case, since the data session is for the main room, the subgroup name will be null.

For the subgroup cases, members who subscribe after someone starts data streaming using the subgroup data session will also receive an onDataSessionIncoming with an appropriate the subgroup name when receiving data upon completion of the subscription flow.

Create an inbound data session

To create an inbound data session, use makeInboundDataSession().

fun makeInboundDataSession(
    @IntRange(from = 100, to = 999) streamId: Int,
    listener: InboundDataSessionListener
)

Parameter	Description
streamId	Stream identifier defined by the application. For more information, see Stream ID.
listener	Listener for handling events related to the inbound data session

The result of creating an inbound data session can be determined by the callback of the listener.

• If an inbound data session is created successfully, onSessionMade is called.
• If an inbound data session could not be created, onError is called with the reason of the failure. For more information, see Data session fail reason.

You can get notified of the data reception event through onDataReceived of the listener.

Retrieve an inbound data session

To retrieve an existing inbound data session, use getInboundDataSession().

fun getInboundDataSession(streamId: Int): PlanetKitInboundDataSession?

Parameter	Description
streamId	Stream ID. For more information, see Stream ID.

Report an unsupported data session

To inform the sender that the application does not support the stream ID, use unsupportInboundDataSession().

fun unsupportInboundDataSession(streamId: Int): Boolean

Parameter	Description
streamId	Stream ID. For more information, see Stream ID.

Call this method if the stream ID received through the onDataSessionIncoming event cannot be processed by the application (that is, unknown to the receiver).

• 1-to-1 call
  • The sender becomes aware that this method has been called through the data session fail reason "Unsupported". The sender cannot send data through this stream anymore.
• Group call
  • The sender does not know that this method has been called because there are multiple receivers.
  • The user of the application that called this method will not receive data through this stream, but the sender can continue to send data through this stream.

Closure of a data session

When a data session is closed, the onClosed event of OutboundDataSessionListener (for the sender) or InboundDataSessionListener (for the receiver) occurs.

The onClosed event delivers the reason for the closure of the data session with the closedReason parameter. The data session closure reasons defined in the PlanetKitDataSessionClosedReason enum are as follows:

Enum value	Description
SESSION_END	The data session has ended normally.
INTERNAL	An unexpected error occurred internally.
UNSUPPORTED	The data session ID is unsupported by the peer.

Data session fail reason

A data session fail reason lets you determine the result of data session creation and its failure reason. The data session fail reasons defined in the PlanetKitDataSessionFailReason enum are as follows:

Enum value	Description
NONE	Successfully created a data session.
INTERNAL	Unexpected error occurred internally.
NOT_INCOMING	Cannot make an inbound data session without an incoming event (onDataSessionIncoming).
ALREADY_EXIST	Data session stream ID already exists.
INVALID_ID	Data session stream ID is invalid.
INVALID_TYPE	Data session type is invalid.

Tip

Data session fail reasons are available since PlanetKit 5.1.

Data session compatibility

Based on the call type, you can determine the data session compatibility as follows:

• 1-to-1 call
  • The value of isDataSessionSupported of PlanetKitCallConnectedParam delivered by onConnected determines whether the peer supports a data session or not.
• Group call
  • The value of isDataSessionSupported of PlanetKitConferencePeer describes whether the participant supports a data session or not.

Even if peers have data session capabilities, handling a specific stream ID is another compatibility issue. This issue is related to handling of a specific stream ID by older versions of clients where handling of the stream ID is not implemented.

You can solve the compatibility issue of a specific stream ID by one of the following methods:

• In older versions of clients, reject unknown stream IDs by calling unsupportInboundDataSession().
• When developing older versions of clients, assign a specific stream ID as a reliable type for compatibility check, and design a protocol for compatibility check. In subsequent versions of clients, use the protocol to solve the compatibility issue in the way you want.

Related API

APIs related to the data session function are as follows.

Common

• send() of PlanetKitOutboundDataSession
• changeDestination() of PlanetKitOutboundDataSession
• onTooLongQueueData of OutboundDataSessionListener
• onClosed of OutboundDataSessionListener
• onDataReceived of InboundDataSessionListener
• onClosed of InboundDataSessionListener
• PlanetKitDataSessionClosedReason
• PlanetKitDataSessionFailReason

1-to-1 call

• makeOutboundDataSession() of PlanetKitCall
• getOutboundDataSession() of PlanetKitCall
• makeInboundDataSession() of PlanetKitCall
• getInboundDataSession() of PlanetKitCall
• unsupportInboundDataSession() of PlanetKitCall
• onDataSessionIncoming of CallListener

Group call

• makeOutboundDataSession() of PlanetKitConference
• getOutboundDataSession() of PlanetKitConference
• makeInboundDataSession() of PlanetKitConference
• getInboundDataSession() of PlanetKitConference
• unsupportInboundDataSession() of PlanetKitConference
• makeOutboundDataSession() of PlanetKitSubgroup
• getOutboundDataSession() of PlanetKitSubgroup
• makeInboundDataSession() of PlanetKitSubgroup
• getInboundDataSession() of PlanetKitSubgroup
• unsupportInboundDataSession() of PlanetKitSubgroup
• onDataSessionIncoming of ConferenceListener