Holding a call
PlanetKit provides a feature to hold or unhold a call, which causes the application to pause or resume sending and receiving media streams. When a user holds or unholds a call, peers receive an event indicating that the user's video has been paused or resumed.
The behavior of holding and unholding a call differs depending on the call type. This page describes how you can hold or unhold a call.
| Supported call type | Minimum SDK version |
|---|---|
| 1-to-1 call, group call (conference) | PlanetKit 3.0 |
1-to-1 call
To hold or unhold a 1-to-1 call, use hold() or unhold() of PlanetKitCall.
After you call hold() to pause the application's transmission and reception of media streams, the peer should wait for unhold() to be called in order to resume communication. On the peer side, the application lets PlanetKit play a hold tone that was set in the call parameter.
The following diagram shows the flow of holding and unholding in a 1-to-1 call.
Related APIs
The following APIs are related to holding and unholding a call in 1-to-1 calls.
| Method | Description | Related event callbacks |
|---|---|---|
hold() iOS, macOS | Starts hold state. You can provide the hold reason. | peerDidHold iOS, macOS |
unhold() iOS, macOS | Stops hold state. | peerDidUnhold iOS, macOS |
Enabling and disabling a video call
A device that requested a hold on the call (Client 01) cannot request the enabling or disabling of a video call.
However, the peer device (Client 02) can request the enabling or disabling of a video call using the enableVideo() and disableVideo() methods. In 1-to-1 calls, enabling and disabling a video call are always processed simultaneously on both sides. Therefore, when Client 02 requests the enabling or disabling of a video call, both Client 02 and Client 01 will perform enabling or disabling of a video call accordingly. After that, the Client 01 device, which was previously on hold, will continue to remain on hold.
Group call
To hold or unhold a group call, use hold() or unhold() of PlanetKitConference.
In group calls, the hold behavior is different from 1-to-1 calls. The key differences are as follows:
- There is no concept of hold tone.
- In 1-to-1 calls, media transmission and reception is paused at the sender (peer) side. In group calls, transmission and reception of peers' media is stopped by Planet Cloud.
The following diagram shows the flow of holding and unholding in a group call.
Related APIs
The following APIs are related to holding and unholding a call in group calls.
| Method | Description | Related event callbacks |
|---|---|---|
hold() iOS, macOS | Starts hold state. You can provide the hold reason. | peersDidHold iOS, macOS |
unhold() iOS, macOS | Stops hold state. | peersDidUnhold iOS, macOS |
Enabling and disabling a video call
A device that requested a hold on the call (Client 01) cannot request the enabling or disabling of a video call.
Screen share
During screen share, if the client of the presenter (the user who is doing screen share) calls hold(), the following events are generated for the presenter and peers:
- Presenter:
myScreenShareDidStopByHold - Peer in a 1-to-1 call:
peerDidStopScreenShare - Peers in a group call:
screenShareDidUpdatewithDISABLEDstate
For group calls, the target of the screen share determines the peers who receive the screenShareDidUpdate event, as follows:
- If the screen share is targeted for the main room, all peers in the room receive the event.
- If the screen share is targeted for a subgroup, only the peers who subscribed to the subgroup receive the event.