통화 일시 중지

통화 일시 중지(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()	일시 중지 상태를 시작합니다. 일시 중지 이유를 제공할 수 있습니다.	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 통화

메서드

• PlanetKitCall의 hold()
• PlanetKitCall의 unhold()

이벤트

• peerDidHold
• peerDidUnhold
• peerVideoDidPause
• peerVideoDidResume
• PlanetKitCallDelegate의 myScreenShareDidStopByHold
• peerDidStopScreenShare

그룹 통화

메서드

• PlanetKitConference의 hold()
• PlanetKitConference의 unhold()

이벤트

• peersDidHold
• peersDidUnhold
• peersVideoDidUpdate
• didUpdateVideo
• PlanetKitConferenceDelegate의 myScreenShareDidStopByHold
• PlanetKitConferenceDelegate의 screenShareDidUpdate
• PlanetKitPeerControlDelegate의 didUpdateScreenShare

관련 문서

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