RTCPeerConnection.addIceCandidate()
===================================

`RTCPeerConnection` (en-US)을 사용하는 웹이나 앱이 신규 ICE candidate를 signaling 채널을 통해 원격 유저로부터 수신하게되면, \*\*`RTCPeerConnection.addIceCandidate()`\*\*를 호출해서 브라우저의 ICE 에이전트에게 새로 수신한 candidate를 전달합니다. 이 메소드는 `RTCPeerConnection`의 원격 설명 (remote description)에 연결의 원격쪽 상태를 설명해주는 신규 원격 candidate를 추가합니다.

`addIceCandidate()` 호출시 `candidate` 매개변수가 존재하지 않거나 값이 `null`인 경우에, 추가된 ICE candidate는 "candidate 종료"를 알려줍니다. 지정한 객체의`candidate` 값이 존재하지 않거나, 빈 문자열 (`""`)인 경우에도 원격 candidate들이 모두 전달되었음을 알려줍니다.

"candidate 종료" 알림은 a-line 값의 `end-of-candidates`를 가진 candidate와 함께 원격 유저에 송신됩니다.

네고시에이션 중에 앱이 위의 방법처럼 ICE 에이전트에 전달할 다수의 candidate를 수신 받을 수 있고, 이는 가능한 연결 방법들의 리스트를 만들 수 있도록 도와줍니다. 자세한 내용은 WebRTC connectivity (en-US)와 Signaling and video calling를 참고하십시오.

Syntax
------


```js
aPromise = pc.addIceCandidate(candidate);

addIceCandidate(candidate, successCallback, failureCallback);
```

### 매개변수

`candidate` Optional

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

### 더 이상 사용되지 않는 변수 (Deprecated)

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

`successCallback` 
지원이 중단되었습니다

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

`failureCallback` 
지원이 중단되었습니다

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

### 반환 값

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

### 예외 처리

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

`TypeError`

명시한 candidate의 `sdpMid` (en-US) 및`sdpMLineIndex` (en-US)가 모두 `null` 입니다.

`InvalidStateError`

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

`OperationError`

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

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

예시
--

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


```js
// 본 예제는 다른 유저가 아래와 같은 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 종료"를 수동으로 설정하려면 다음과 같이 하면 됩니다:


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


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

명세
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-addicecandidate |

브라우저 호환성
--------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

참조
--

* WebRTC API
* Signaling and video calling
* WebRTC architecture overview (en-US)
* WebRTC connectivity (en-US)
* Lifetime of a WebRTC session (en-US)