통화 일시 중지
통화 일시 중지(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는 다음과 같습니다.