通話の一時停止

通話の一時停止（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通話の一時停止と再開の流れを示します。

APIの概要

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

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

サンプルコード

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

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

PlanetKit::PlanetKitCallPtr m_pCall;

... // Obtain the PlanetKitCall instance from the result of MakeCall() or VerifyCall()

// Hold the call, with optional reason
bool bHoldResult = m_pCall->Hold(PlanetKit::WStringOptional(L"User requested"), nullptr, [](void*, bool bSuccess) {
    if (bSuccess == false) {
        std::wcout << L"Hold() request failed." << std::endl;
    }
});

// Unhold the call
bool bUnholdResult = m_pCall->Unhold(nullptr, [](void*, bool bSuccess) {
    if (bSuccess == false) {
        std::wcout << L"Unhold() request failed." << std::endl;
    }
});

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

class CallEventListener : public PlanetKit::ICallEvent {
public:
    ...

    // This is called after the call is placed on hold.
    // Write your own code here.
    void OnReceivedPeerHold(PlanetKitCallPtr pPlanetKitCall, const WString& strHoldReason) override;

    // This is called after the call is resumed from hold.
    // Write your own code here.
    void OnReceivedPeerUnhold(PlanetKitCallPtr pPlanetKitCall) override;
}

他の機能との関係

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

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

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

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

画面共有

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

• 発表者：OnMyScreenShareStoppedByHold
• ピア：OnPeerStoppedScreenShare

グループ通話

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

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

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

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

APIの概要

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

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

サンプルコード

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

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

PlanetKit::PlanetKitConferencePtr m_pConference;

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

// Hold the conference, with optional reason
bool bHoldResult = m_pConference->Hold(PlanetKit::WStringOptional(L"User requested"), nullptr, [](void*, bool bSuccess) {
    if (bSuccess == false) {
        std::wcout << L"Hold() request failed." << std::endl;
    }
});

// Unhold the conference
bool bUnholdResult = m_pConference->Unhold(nullptr, [](void*, bool bSuccess) {
    if (bSuccess == false) {
        std::wcout << L"Unhold() request failed." << std::endl;
    }
});

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

class ConferenceEventListener : public PlanetKit::IConferenceEvent {
public:
    ...

    // This is called after the conference is placed on hold.
    // Write your own code here.
    void OnReceivedPeersHold(PlanetKitConferencePtr pPlanetKitConference, const PeerHoldArray& arrPeerHold) override;

    // This is called after the conference is resumed from hold.
    // Write your own code here.
    void OnReceivedPeersUnhold(PlanetKitConferencePtr pPlanetKitConference, const PeerArray& arrPeer) override;
}

他の機能との関係

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

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

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

画面共有

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

• 発表者：OnMyScreenShareStoppedByHold
• ピア：IConferenceEvent::OnPeerScreenShareUpdated、IPeerControlEvent::OnScreenShareUpdated（状態はDISABLED）

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

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

関連API

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

1対1通話

メソッド

• PlanetKitCall::Hold()
• PlanetKitCall::Unhold()

イベント

• OnReceivedPeerHold
• OnReceivedPeerUnhold
• OnPeerVideoPaused
• OnPeerVideoResumed
• ICallEvent::OnMyScreenShareStoppedByHold
• OnPeerStoppedScreenShare

グループ通話

メソッド

• PlanetKitConference::Hold()
• PlanetKitConference::Unhold()

イベント

• OnReceivedPeersHold
• OnReceivedPeersUnhold
• OnPeersVideoUpdated
• OnVideoUpdated
• IConferenceEvent::OnMyScreenShareStoppedByHold
• IConferenceEvent::OnPeerScreenShareUpdated
• IPeerControlEvent::OnScreenShareUpdated

関連ドキュメント

• ビデオの一時停止イベント
• 音声通話中のビデオ通話の有効化
• プレゼンテーション - 画面共有