Contents sharing

The contents sharing API allows a user to share time-dependent data with peers. Shared data can be of any type, but it must be limited to a maximum size of 1 kilobyte.

Supported call type	Minimum SDK version
1-to-1 call, group call (conference)	PlanetKit 3.3 (Room-scoped sharing: PlanetKit 3.6.19)

Tip

In both 1-to-1 calls and group calls, contents sharing APIs are available only after the call setup is completed.

Types of contents sharing

LINE Planet provides the following types of contents sharing.

Contents sharing type	Description	Note
Normal sharing	Each user shares their own data.
Exclusive sharing	Everyone in a room needs the same shared data. For more information, see Exclusive sharing.
Room-scoped sharing	The lifetime of the shared data is scoped to the room. For more information, see Room-scoped sharing.	Available in group calls only

Note

Since the three types of contents sharing are independent, they can be operated simultaneously within a room.

Related APIs

This sections describes the APIs related to contents sharing by call type.

1-to-1 call

To share contents in 1-to-1 calls, use the following methods of ContentShareCall.

Type	Method	Description	Related event callback
Normal sharing	SetSharedContents()	Sets shared data to be shared with all peers	OnPeersSetSharedContents
-	UnsetSharedContents()	Clears previously set shared data	OnPeersUnsetSharedContents
Exclusive sharing	SetExclusivelySharedContents()	Sets exclusively shared data to be shared with all peers	OnPeerSetExclusivelySharedContents
-	UnsetExclusivelySharedContents()	Clears previously set exclusively shared data	OnPeerUnsetExclusivelySharedContents

Group call

To share contents in group calls, use the following methods of ContentShareConference.

Type	Method	Description	Related event callback
Normal sharing	SetSharedContents()	Sets shared data to be shared with all peers	OnPeersSetSharedContents
-	UnsetSharedContents()	Clears previously set shared data	OnPeersUnsetSharedContents
Exclusive sharing	SetExclusivelySharedContents()	Sets exclusively shared data to be shared with all peers	OnPeerSetExclusivelySharedContents
-	UnsetExclusivelySharedContents()	Clears previously set exclusively shared data	OnPeerUnsetExclusivelySharedContents
Room-scoped sharing	SetRoomSharedContents()	Sets room shared data to be shared with all peers in the room	OnPeerSetRoomSharedContents
-	UnsetRoomSharedContents()	Clears previously set room shared data	OnPeerUnsetRoomSharedContents

Information delivered to peers

Once a user starts to share data using one of the methods for setting shared contents, other users are notified by the corresponding event callback, which delivers an object of CommonSetSharedContent class that provides the following getter methods:

Methods	Description
GetPeerID()	Gets the ID information of the peer who set the shared data
GetPeer()	Gets the information of the peer who set the shared data
Data()	Gets the shared data
DataSize()	Gets the size of the shared data
ElapsedAfterSetMsec()	Gets elapsed time since the shared data was last modified (in milliseconds)

The elapsed time lets you calculate how much time has passed since the last modification of the shared data.

Exclusive sharing

The term "exclusive sharing" means that there is only one instance of the shared data for the room (or the call).

Use SetExclusivelySharedContents() and UnsetExclusivelySharedContents() if everyone in a room needs the same shared data.

Note

In case of exclusively shared contents, only the participant who called SetExclusivelySharedContents() can modify the shared data.

Room-scoped sharing

PlanetKit provides SetRoomSharedContents() and UnsetRoomSharedContents() for room-scoped content sharing. This feature is available in group calls only and has the following characteristics:

• Data lifetime
  • In room-scoped content sharing, unless you call UnsetRoomSharedContents(), the lifetime of the data and the lifetime of the room are the same.
  • On the other hand, the lifetime of data shared by SetSharedContents() and SetExclusivelySharedContents() depends on the participant who called the API. Therefore, when the participant leaves, the data is also invalidated.
  • However, data shared by SetRoomSharedContents() is maintained until all participants leave or someone calls UnsetRoomSharedContents().
• Multi-setter and one instance
  • In room-scoped content sharing, data shared by SetRoomSharedContents() can be changed by all participants. Therefore, the value of the data will be the one set by the last called SetRoomSharedContents().
  • Room-scoped content sharing assumes that there can be multiple setters, so even if the last setter leaves, the remaining participants will receive the related event.

Example: Raise hands before speaking

Let's look at a simple example that shows you how to use the contents sharing APIs. This example illustrates what exclusive sharing is and how to design the structure of shared data.

Suppose you plan to implement a feature that allows a participant to "raise hands" before speaking, using the contents sharing API. In addition, let's assume that the "raise hands" flag is valid only for 3 seconds (3000 msec).

The first case assumes the participants can raise hands at the same time, so multiple participants can raise hands.

1. The structure of shared data is flag.
2. Anyone who wants to speak calls SetSharedContents() with the flag=true.
3. All participants become aware of who wants to speak through the user ID in OnPeersSetSharedContents.
4. Only participants who meet the condition of "elapsed time < 3000 msec" can raise hands. Consequently, when a new participant joins after 4000 msec, the participant will be notified of who raised hands by OnPeersSetSharedContents but will not be eligible for raising hands.

The second case assumes that only one speaker can raise hands at one time, so only one participant can raise hands. This case requires a master participant. Let's assume that user-m is the user ID of the master.

1. The structure of shared data is flag.
2. The master calls SetExclusivelySharedContents() with h-user-id=NULL, flag=false. From this moment on, calling of SetExclusivelySharedContents() by other participants are ignored.
3. Anyone who wants to speak calls sendShortData() to user-m.
4. The master picks only one participant (assume user-a).
5. The master calls SetExclusivelySharedContents() with (h-user-id=user-a, flag=true).
6. All participants become aware that user-a (h-user-id) wants to speak (flag=true) through OnPeerSetExclusivelySharedContents.