RTCPeerConnection.addIceCandidate()

candidate Optional

RTCIceCandidateInit 딕셔너리 혹은 RTCIceCandidate 객체에 해당하는 객체입니다. 이 객체의 내용은 signaling 채널을 통해 수신 받은 메세지로 구성되어야합니다. 메세지는 이미 로컬 ICE 에이전트에 전달 될 준비가 된 새로 수신받은 ICE candidate를 설명합니다.candidate 객체가 지정되어있지 않거나, null 이라면, "candidate 종료" 신호가 end-of-candidates a-line을 사용해서 원격 유저에게 전달됩니다. a-line의 형식은 아래와 같습니다: a=end-of-candidates

이전 버전의 문서에서는 이 함수를 콜백 기반으로 사용하도록 되어있습니다. 콜백 기반 함수는 이제 더 이상 사용되지 않으며, 사용하지 않는 것을 권장합니다. 이미 사용 중이라면, Promise 버전인 addIceCandidate()를 사용하도록 코드를 업데이트 하십시오. 이전 버전의 코드를 업데이트 하는 것을 쉽게 하기 위해 고안된 addIceCandidate()의 특정 변수에 대해 아래에서 설명합니다.

successCallback 지원이 중단되었습니다

ICE candidate가 성공적으로 추가되었을 때에 호출되는 함수입니다. 이 함수는 입력 변수가 없으며, 아무런 값도 반환하지 않도록 되어있습니다.

failureCallback 지원이 중단되었습니다

ICE candidate 추가 시도가 실패하면 호출되는 함수입니다. 실패에 대한 이유를 설명하는 객체인 DOMException을 입력 변수로 받습니다.

Promise는 candidate가 ICE 에이전트에 의해 원격 유저의 설명 (description)에 성공적으로 추가되면 fulfilled 됩니다. 프로미스는 입력 변수가 없습니다.

ICE candidate 추가 시도 중 에러가 발생하면, 이 메소드에서 반환되는 Promise는 거절됩니다. 그리고 거절 핸들러로 전달되는 지정된 DOMException 객체안에 존재하는 name 속성으로 아래의 에러 중 하나를 반환하게 됩니다.

TypeError

명시한 candidate의 sdpMid 및sdpMLineIndex가 모두 null 입니다.

InvalidStateError

현재 RTCPeerConnection은 어떠한 원격 유저와도 연결이 되어있지 않습니다. remoteDescription 값이 null입니다.

OperationError

이 에러는 여러가지 이유 때문에 발생합니다:* 지정된 sdpMid 값이 non-null이고, remoteDescription안에 존재하는 어떠한 미디어 description의 미디어 ID와도 일치하지 않음

• 지정된 sdpMLineIndex의 값이 원격 설명 (description)에 포함된 미디어의 숫자와 같거나 큼
• 지정된 ufrag가 어떠한 원격 설명 (description) 안의 ufrag 필드와 일치하지 않음
• candidate 문자열에 존재하는 하나 혹은 여러개의 값들이 올바르지 않거나, 파싱 될 수 없음
• 어떠한 이유에서던 candidate를 추가하려는 시도가 실패

아래의 코드는 임의의 signaling 채널을 통해 어떻게 ICE candidate를 알리는지를 보여줍니다.

// 본 예제는 다른 유저가 아래와 같은 signaling 채널을 사용한다고 가정합니다:
//
// pc.onicecandidate = event => {
//   if (event.candidate) {
//     signalingChannel.send(JSON.stringify({ice: event.candidate})); // "ice" is arbitrary
//   } else {
//     // All ICE candidates have been sent
//   }
// }

signalingChannel.onmessage = (receivedString) => {
  const message = JSON.parse(receivedString);
  if (message.ice) {
    // A typical value of ice here might look something like this:
    //
    // {candidate: "candidate:0 1 UDP 2122154243 192.168.1.9 53421 typ host", sdpMid: "0", ...}
    //
    // Pass the whole thing to addIceCandidate:

    pc.addIceCandidate(message.ice).catch((e) => {
      console.log("Failure during addIceCandidate(): " + e.name);
    });
  } else {
    // handle other things you might be signaling, like sdp
  }
};

원격 유저에 의해 이러한 방식으로 신호를 전달한 마지막 candiate는 "candidate 종료"를 나타내는 특수한 candidate가 됩니다. "candidate 종료"를 수동으로 설정하려면 다음과 같이 하면 됩니다:

pc.addIceCandidate({ candidate: "" });

하지만, 대부분의 경우 RTCPeerConnection가 적절한 이벤트를 보내서 처리해주기 때문에 이를 수동으로 확인해야 할 필요는 없습니다.

• WebRTC API
• Signaling and video calling
• WebRTC architecture overview
• WebRTC connectivity
• Lifetime of a WebRTC session