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.3

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 NullOptional, 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 OnReceive 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 OnReceive 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().

virtual bool MakeOutboundDataSession(
    int nStreamId,
    EDataSessionType eType,
    NULLABLE void* pResultUserData,
    IOutboundDataSessionHandlerPtr pDataSessionHandler
) = 0;

Parameter	Description
nStreamId	Stream identifier defined by the application. For more information, see Stream ID.
eType	Data session type. For more information, see Data session type.
pResultUserData	User data to be passed along when pDataSessionHandler is called
pDataSessionHandler	Callback handler for the data session

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

• If an outbound data session is created successfully, OnSuccess 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, OnTooLongQueuedData 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
OnTooLongQueuedData (bEnabled=true)	Data traffic is too heavy.	Stop sending data or reduce the transmission bitrate.
OnTooLongQueuedData (bEnabled=false)	Network conditions become better.	Send more data.

Note

If OnTooLongQueuedData 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().

virtual bool GetOutboundDataSession(int nStreamId, OutboundDataSessionPtr* pResult) = 0;

Parameter	Description
nStreamId	Stream ID. For more information, see Stream ID.
pResult	Retrieved outbound data session

Send data

To send data using an outbound data session, use OutboundDataSession::Send().

 virtual bool Send(const void* pData, unsigned int nDataSize, unsigned long long llTimestamp) = 0;

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

Change the destination of data

To change the destination of data, use OutboundDataSession::ChangeDestination().

Note

This method is effective for group calls only.

virtual bool ChangeDestination(UserIdPtr pPeerId, void* pUserData = nullptr, ResultCallback pCallback = nullptr) = 0;

Parameter	Description
pPeerId	Peer who will receive the data. Setting to nullptr 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.
pUserData	User data for pResultHandler
pCallback	Result callback function

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
virtual void OnDataSessionIncoming(DataSessionStreamIdT nStreamId, EDataSessionType eType) = 0;

// For group calls
virtual void OnDataSessionIncoming(const WStringOptional& strSubgroupName, DataSessionStreamIdT nStreamId, EDataSessionType eType) = 0;

Parameter	Description
strSubgroupName	(Group calls only) Subgroup name. NullOptional means the main room.
nStreamId	Stream ID set by the sender. For more information, see Stream ID.
eType	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 NullOptional.

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().

virtual bool MakeInboundDataSession(
    int nStreamId,
    NULLABLE void *pResultUserData,
    IInboundDataSessionHandlerPtr pDataSessionHandler
) = 0;

Parameter	Description
nStreamId	Stream identifier defined by the application. For more information, see Stream ID.
pResultUserData	User data for pDataSessionHandler
pDataSessionHandler	Callback handler for the data session

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

• If an inbound data session is created successfully, OnSuccess 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 OnReceive of the pDataSessionHandler.

Retrieve an inbound data session

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

virtual bool GetInboundDataSession(int nStreamId, InboundDataSessionPtr* pResult) = 0;

Parameter	Description
nStreamId	Stream ID. For more information, see Stream ID.
pResult	Retrieved inbound data session

Report an unsupported data session

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

virtual bool UnsupportInboundDataSession(DataSessionStreamIdT nStreamId) = 0;

Parameter	Description
nStreamId	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 IOutboundDataSessionHandler (for the sender) or IInboundDataSessionHandler (for the receiver) occurs.

The OnClosed event delivers the reason for the closure of the data session with the eClosedReason parameter. The data session closure reasons defined in the EDataSessionClosedReason enum are as follows:

Enum value	Description
PLNK_DATA_SESSION_CLOSED_REASON_SESSION_END	The data session has ended normally.
PLNK_DATA_SESSION_CLOSED_REASON_INTERNAL	An unexpected error occurred internally.
PLNK_DATA_SESSION_CLOSED_REASON_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 EDataSessionFailReason enum are as follows:

Enum value	Description
PLNK_DATA_SESS_FAIL_REASON_NONE	Successfully created a data session.
PLNK_DATA_SESS_FAIL_REASON_INTERNAL	Unexpected error occurred internally.
PLNK_DATA_SESS_FAIL_REASON_NOT_INCOMING	Cannot make an inbound data session without an incoming event (OnDataSessionIncoming).
PLNK_DATA_SESS_FAIL_REASON_ALREADY_EXIST	Data session stream ID already exists.
PLNK_DATA_SESS_FAIL_REASON_INVALID_ID	Data session stream ID is invalid.
PLNK_DATA_SESS_FAIL_REASON_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 CallConnectedParam::IsSupportDataSession() delivered by OnConnected determines whether the peer supports a data session or not.
• Group call
  • The value of Peer::IsDataSessionSupported() 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

• OutboundDataSession::Send()
• OutboundDataSession::ChangeDestination()
• IOutboundDataSessionHandler::OnTooLongQueuedData
• IOutboundDataSessionHandler::OnClosed
• IInboundDataSessionHandler::OnReceive
• IInboundDataSessionHandler::OnClosed
• EDataSessionClosedReason
• EDataSessionFailReason

1-to-1 call

• PlanetKitCall::MakeOutboundDataSession()
• PlanetKitCall::GetOutboundDataSession()
• PlanetKitCall::MakeInboundDataSession()
• PlanetKitCall::GetInboundDataSession()
• PlanetKitCall::UnsupportInboundDataSession()
• ICallEvent::OnDataSessionIncoming

Group call

• Subgroup::MakeOutboundDataSession()
• Subgroup::GetOutboundDataSession()
• Subgroup::MakeInboundDataSession()
• Subgroup::GetInboundDataSession()
• Subgroup::UnsupportInboundDataSession()
• IConferenceEvent::OnDataSessionIncoming