本文にスキップする
Version: 6.2

通話の一時停止

通話の一時停止（hold）および再開（unhold）機能を使用すると、通話接続を維持したまま、メディアの送受信を一時停止したり再開したりできます。

  • ユーザーが通話を一時停止すると、
    • メディアの送受信が一時停止されます。
    • ピアは、通話の一時停止とユーザーのメディア状態の変更に関するイベントを受け取ります。
  • ユーザーが通話を再開すると、
    • メディアの送受信が再開されます。
    • ピアは、通話の再開とユーザーのメディア状態の変更に関するイベントを受け取ります。

通話の一時停止および再開の動作は、通話タイプによって異なります。ここでは、通話を一時停止または再開する方法について説明します。

通話タイプSDKの最低バージョン
1対1通話、グループ通話（カンファレンス）PlanetKit 3.0
Note

PlanetKit 5.5以前では、通話の一時停止および再開がカメラの作動に直接的な影響を及ぼすことはありませんでした。しかし、PlanetKit 5.5から通話の一時停止および再開が次のようにカメラを制御します。

  • 通話を一時停止すると、PlanetKitがカメラをオフにしてビデオ送信を無効にするため、カメラインジケーター（camera indicator）がオフになります。
  • 通話を再開すると、PlanetKitがカメラをオンにしてビデオ送信を有効にするため、カメラインジケーターがオンになります。
Note

PlanetKit 6.0以前では、通話の一時停止および再開がマイクの作動に直接的な影響を及ぼすことはありませんでした。しかし、PlanetKit 6.0から通話の一時停止および再開が次のようにマイクを制御します。

  • 通話を一時停止すると、PlanetKitがカメラをオフにしてオーディオ送信を無効にするため、マイクインジケーター（microphone indicator）がオフになります。
  • 通話を再開すると、PlanetKitがマイクをオンにしてオーディオ送信を有効にするため、マイクインジケーターがオンになります。

1対1通話​

1対1通話を一時停止または再開するには、PlanetKitCallのhold()またはunhold()を使用します。

hold()を呼び出してアプリケーションのメディアストリームの送受信を一時停止した後、ピアは通信を再開するためにunhold()が呼び出されるまで待つ必要があります。ピア側のアプリケーションは、PlanetKitが通話パラメーターに設定された一時停止音（hold tone）を再生させます。

下図は、1対1通話の一時停止と再開の流れを示します。

1対1通話一時停止のシーケンス図

APIの概要​

1対1通話で通話の一時停止および再開に使用されるAPIは、次のとおりです。

メソッド説明関連イベントコールバック
hold()一時停止ステータスを開始します。一時停止の理由を提供できます。peerDidHold
unhold()一時停止ステータスを終了します。peerDidUnhold

サンプルコード​

1対1通話で通話の一時停止および再開機能を実装する方法は、次のとおりです。

通話を一時停止または再開する​

let call: PlanetKitCall

... // Obtain the PlanetKitCall instance from the result of makeCall() or verifyCall()

// Hold the call, with optional reason
call.hold(reason: "User requested") { success in
    NSLog("hold result: \(success).")
}

// Unhold the call
call.unhold() { success in
    NSLog("unhold result: \(success).")
}

通話の一時停止に関するイベントを処理する​

extension CallDelegateExample : PlanetKitCallDelegate {
    ...

    func peerDidHold(_ call: PlanetKitCall, reason: String?) {
        // This is called after the call is placed on hold.
        // Write your own code here.
    }

    func peerDidUnhold(_ call: PlanetKitCall) {
        // This is called after the call is resumed from hold.
        // Write your own code here.
    }
}

他の機能との関係​

他のメディア制御機能に関する参考事項は、次のとおりです。

ビデオ通話の有効化および無効化​

通話中に一時停止をリクエストしたクライアント（Client 01）では、ビデオ通話の有効化および無効化をリクエストできません。

しかし、相手のクライアント（Client 02）では、enableVideo()およびdisableVideo()メソッドでビデオ通話の有効化および無効化をリクエストできます。1対1通話でビデオ通話の有効化および無効化は常に両方から同時に行われます。したがって、Client 02がビデオ通話の有効化または無効化をリクエストすると、Client 02だけでなくClient 01もビデオ通話の有効化または無効化が実行されます。その後、以前に一時停止状態だったClient 01は、一時停止状態を継続します。

画面共有​

画面共有中に発表者（画面共有をしているユーザー）のクライアントがhold()を呼び出すと、画面共有が中止され、次のようなイベントが発生します。

  • 発表者：myScreenShareDidStopByHold
  • ピア：peerDidStopScreenShare

グループ通話​

グループ通話を一時停止または再開するには、PlanetKitConferenceのhold()またはunhold()を使用します。

グループ通話では、一時停止の動作が1対1通話と異なります。主に以下のような違いがあります。

  • 1対1通話では、両方のユーザーのメディア送受信が一時停止されますが、グループ通話では、通話を一時停止したユーザーのメディア送受信のみが一時停止されます。
  • 一時停止音という概念が存在しません。

下図は、グループ通話の一時停止および再開の流れを示します。

グループ通話一時停止のシーケンス図

APIの概要​

グループ通話で通話の一時停止および再開に使用されるAPIは、次のとおりです。

メソッド説明関連イベントコールバック
hold()一時停止ステータスを開始します。一時停止の理由を提供できます。peersDidHold
unhold()一時停止ステータスを終了します。peersDidUnhold

サンプルコード​

グループ通話で通話の一時停止および再開機能を実装する方法は、次のとおりです。

通話を一時停止または再開する​

let conference: PlanetKitConference

... // Obtain the PlanetKitConference instance from the result of joinConference()

// Hold the conference, with optional reason
conference.hold(reason: "User requested") { success in
    NSLog("hold result: \(success).")
}

// Unhold the conference
conference.unhold() { success in
    NSLog("unhold result: \(success).")
}

通話の一時停止に関するイベントを処理する​

extension ConferenceDelegateExample : PlanetKitConferenceDelegate {
    ...

    func peersDidHold(_ conference: PlanetKitConference, peerHolds: [PlanetKitConferencePeerHold]) {
        // This is called after the conference is placed on hold.
        // Write your own code here.
    }

    func peersDidUnhold(_ conference: PlanetKitConference, peers: [PlanetKitConferencePeer]) {
        // This is called after the conference is resumed from hold.
        // Write your own code here.
    }
}

他の機能との関係​

他のメディア制御機能に関する参考事項は、次のとおりです。

ビデオ通話の有効化および無効化​

通話中に一時停止をリクエストしたクライアント（Client 01）では、ビデオ通話の有効化および無効化をリクエストできません。

画面共有​

画面共有中に発表者（画面共有をしているユーザー）のクライアントがhold()を呼び出すと、画面共有が中止され、次のようなイベントが発生します。

  • 発表者：myScreenShareDidStopByHold
  • ピア：PlanetKitConferenceDelegateのscreenShareDidUpdate、PlanetKitPeerControlDelegateのdidUpdateScreenShare（状態はDISABLED）

グループ通話では、画面共有の範囲によってイベントを受信するピアが次のように変わります。

  • 画面共有が基本ルーム（main room）を対象とする場合、ルームの中のすべてのピアがイベントを受け取ります。
  • 画面共有がサブグループを対象とする場合、サブグループに加入したピアのみがイベントを受け取ります。

関連API​

通話の一時停止および再開機能に関連するAPIは、次のとおりです。

1対1通話​

メソッド​

イベント​

グループ通話​

メソッド​

イベント​

関連ドキュメント​