通話の一時停止
通話の一時停止（hold）および再開（unhold）機能を使用すると、通話接続を維持したまま、メディアの送受信を一時停止したり再開したりできます。
- ユーザーが通話を一時停止すると、
- メディアの送受信が一時停止されます。
- ピアは、通話の一時停止とユーザーのメディア状態の変更に関するイベントを受け取ります。
- ユーザーが通話を再開すると、
- メディアの送受信が再開されます。
- ピアは、通話の再開とユーザーのメディア状態の変更に関するイベントを受け取ります。
通話の一時停止および再開の動作は、通話タイプによって異なります。ここでは、通話を一時停止または再開する方法について説明します。
| 通話タイプ | SDKの最低バージョン |
|---|---|
| 1対1通話、グループ通話（カンファレンス） | 0.7 |
1対1通話
1対1通話を一時停止または再開するには、PlanetKitCallのhold()またはunhold()を使用します。
hold()を呼び出してアプリケーションのメディアストリームの送受信を一時停止した後、ピアは通信を再開するためにunhold()が呼び出されるまで待つ必要があります。ピア側のアプリケーションは、PlanetKitが通話パラメーターに設定された一時停止音（hold tone）を再生させます。
下図は、1対1通話の一時停止と再開の流れを示します。
関連API
1対1通話で通話の一時停止および再開に関連するAPIは次のとおりです。
| メソッド | 説明 | 関連イベントコールバック |
|---|---|---|
hold() | 一時停止ステータスを開始します。一時停止の理由を提供できます。 | onPeerHold |
unhold() | 一時停止ステータスを終了します。 | onPeerUnhold |
サンプルコード
1対1通話で通話の一時停止および再開機能を実装する方法は、次のとおりです。
通話を一時停止または再開する
// Hold the call, with optional reason
Future<void> holdCall(PlanetKitCall call) async {
final bool holdResult = await call.hold(
reason: 'User requested', // Optional reason string
);
print('hold result=$holdResult');
}
// Unhold the call
Future<void> unholdCall(PlanetKitCall call) async {
final bool unholdResult = await call.unhold();
print('unhold result=$unholdResult');
}
通話の一時停止に関するイベントを処理する
// Implement related callbacks of the PlanetKitCallEventHandler class
final PlanetKitCallEventHandler callEventHandler = PlanetKitCallEventHandler()
..onPeerHold = (PlanetKitCall call, String? reason) {
// This is called after the peer places the call on hold.
// Write your own code here.
}
..onPeerUnhold = (PlanetKitCall call) {
// This is called after the peer resumes the call from hold.
// Write your own code here.
};
他の機能との関係
他のメディア制御機能に関する参考事項は、次のとおりです。
ビデオ通話の有効化および無効化
通話中に一時停止をリクエストしたクライアント（Client 01）では、ビデオ通話の有効化および無効化をリクエストできません。
しかし、相手のクライアント（Client 02）では、enableVideo()およびdisableVideo()メソッドでビデオ通話の有効化および無効化をリクエストできます。1対1通話でビデオ通話の有効化および無効化は常に両方から同時に行われます。したがって、Client 02がビデオ通話の有効化または無効化をリクエストすると、Client 02だけでなくClient 01もビデオ通話の有効化または無効化が実行されます。その後、以前に一時停止状態だったClient 01は、一時停止状態を継続します。
画面共有
画面共有中に発表者（画面共有をしているユーザー）のクライアントがhold()を呼び出すと、画面共有が中止され、次のようなイベントが発生します。
- ピア：
onPeerScreenShareStopped
グループ通話
グループ通話を一時停止または再開するには、PlanetKitConferenceのhold()またはunhold()を使用します。
グループ通話では、一時停止の動作が1対1通話と異なります。主に以下のような違いがあります。
- 1対1通話では、両方のユーザーのメディア送受信が一時停止されますが、グループ通話では、通話を一時停止したユーザーのメディア送受信のみが一時停止されます。
- 一時停止音という概念が存在しません。
下図は、グループ通話の一時停止および再開の流れを示します。
関連API
グループ通話で通話の一時停止および再開に関連するAPIは次のとおりです。
| メソッド | 説明 | 関連イベントコールバック |
|---|---|---|
hold() | 一時停止ステータスを開始します。一時停止の理由を提供できます。 | onPeersHold |
unhold() | 一時停止ステータスを終了します。 | onPeersUnhold |
サンプルコード
グループ通話で通話の一時停止および再開機能を実装する方法は、次のとおりです。
通話を一時停止または再開する
// Hold the conference, with optional reason
Future<void> holdConference(PlanetKitConference conference) async {
final bool holdResult = await conference.hold(
reason: 'User requested', // Optional reason string
);
print('conference hold result=$holdResult');
}
// Unhold the conference
Future<void> unholdConference(PlanetKitConference conference) async {
final bool unholdResult = await conference.unhold();
print('conference unhold result=$unholdResult');
}
通話の一時停止に関するイベントを処理する
// Implement related callbacks of the PlanetKitConferenceEventHandler class
final PlanetKitConferenceEventHandler conferenceEventHandler =
PlanetKitConferenceEventHandler()
..onPeersHold = (
PlanetKitConference conference,
List<PeerHoldData> peers,
) {
// This is called after the conference is placed on hold.
// Write your own code here.
}
..onPeersUnhold = (
PlanetKitConference conference,
List<PlanetKitConferencePeer> peers,
) {
// This is called after the conference is resumed from hold.
// Write your own code here.
};
他の機能との関係
他のメディア制御機能に関する参考事項は、次のとおりです。
ビデオ通話の有効化および無効化
通話中に一時停止をリクエストしたクライアント（Client 01）では、ビデオ通話の有効化および無効化をリクエストできません。
画面共有
画面共有中に発表者（画面共有をしているユーザー）のクライアントがhold()を呼び出すと、画面共有が中止され、次のようなイベントが発生します。
- ピア：
PlanetKitPeerControlHandlerのonScreenShareUpdate（状態はDISABLED）
関連API
通話の一時停止および再開機能に関連するAPIは、次のとおりです。