통화 일시 중지

통화 일시 중지(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

관련 문서

• 비디오 일시 중지 이벤트
• 음성 통화 중 영상 통화 활성화
• 프레젠테이션 - 화면 공유