diff options
Diffstat (limited to 'files/ko/web/api/rtcpeerconnection/addicecandidate/index.html')
| -rw-r--r-- | files/ko/web/api/rtcpeerconnection/addicecandidate/index.html | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/files/ko/web/api/rtcpeerconnection/addicecandidate/index.html b/files/ko/web/api/rtcpeerconnection/addicecandidate/index.html new file mode 100644 index 0000000000..9062abc861 --- /dev/null +++ b/files/ko/web/api/rtcpeerconnection/addicecandidate/index.html @@ -0,0 +1,148 @@ +--- +title: RTCPeerConnection.addIceCandidate() +slug: Web/API/RTCPeerConnection/addIceCandidate +translation_of: Web/API/RTCPeerConnection/addIceCandidate +--- +<div>{{APIRef("WebRTC")}}</div> + +<p><span class="seoSummary">{{domxref("RTCPeerConnection")}}을 사용하는 웹이나 앱이 신규 ICE candidate를 signaling 채널을 통해 원격 유저로부터 수신하게되면, <code><strong>RTCPeerConnection.addIceCandidate()</strong></code>를 호출해서 브라우저의 {{Glossary("ICE")}} 에이전트에게 새로 수신한 candidate를 전달합니다.</span> 이 메소드는 <code>RTCPeerConnection</code>의 원격 설명 (remote description)에 연결의 원격쪽 상태를 설명해주는 신규 원격 candidate를 추가합니다. </p> + +<p><code>addIceCandidate()</code> 호출시 <code>candidate</code> 매개변수가 존재하지 않거나 값이 <code>null</code>인 경우에, 추가된 ICE candidate는 "candidate 종료"를 알려줍니다. 지정한 객체의{{domxref("RTCIceCandidate.candidate", "candidate")}} 값이 존재하지 않거나, 빈 문자열 (<code>""</code>)인 경우에도 원격 candidate들이 모두 전달되었음을 알려줍니다. </p> + +<p>"candidate 종료" 알림은 a-line 값의 <code>end-of-candidates</code>를 가진 candidate와 함께 원격 유저에 송신됩니다.</p> + +<p>네고시에이션 중에 앱이 위의 방법처럼 ICE 에이전트에 전달할 다수의 candidate를 수신 받을 수 있고, 이는 가능한 연결 방법들의 리스트를 만들 수 있도록 도와줍니다. 자세한 내용은 <a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a>와 <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a>를 참고하십시오.</p> + +<h2 id="Syntax">Syntax</h2> + +<pre class="syntaxbox"><em>aPromise </em>= <em>pc</em>.addIceCandidate(<em>candidate</em>); + +addIceCandidate(<em>candidate</em>, <em>successCallback</em>, <em>failureCallback</em>); {{deprecated_inline}} +</pre> + +<h3 id="매개변수">매개변수</h3> + +<dl> + <dt><code>candidate</code> {{optional_inline}}</dt> + <dd> + <p>{{domxref("RTCIceCandidateInit")}} 딕셔너리 혹은 {{domxref("RTCIceCandidate")}} 객체에 해당하는 객체입니다. 이 객체의 내용은 signaling 채널을 통해 수신 받은 메세지로 구성되어야합니다. 메세지는 이미 로컬 ICE 에이전트에 전달 될 준비가 된 새로 수신받은 ICE candidate를 설명합니다.</p> + + <p><code>candidate </code>객체가 지정되어있지 않거나, <code>null</code>이라면, "candidate 종료" 신호가 <code>end-of-candidates</code> a-line을 사용해서 원격 유저에게 전달됩니다. a-line의 형식은 아래와 같습니다:</p> + + <pre>a=end-of-candidates</pre> + </dd> +</dl> + +<h3 id="더_이상_사용되지_않는_변수_(Deprecated)">더 이상 사용되지 않는 변수 (Deprecated)</h3> + +<p>이전 버전의 문서에서는 이 함수를 콜백 기반으로 사용하도록 되어있습니다. 콜백 기반 함수는 이제 더 이상 사용되지 않으며, 사용하지 않는 것을 권장합니다. 이미 사용 중이라면, {{jsxref("Promise")}} 버전인 <code>addIceCandidate()</code>를 사용하도록 코드를 업데이트 하십시오. 이전 버전의 코드를 업데이트 하는 것을 쉽게 하기 위해 고안된 <code>addIceCandidate()</code>의 특정 변수에 대해 아래에서 설명합니다.</p> + +<dl> + <dt><code>successCallback</code> {{deprecated_inline}}</dt> + <dd>ICE candidate가 성공적으로 추가되었을 때에 호출되는 함수입니다. 이 함수는 입력 변수가 없으며, 아무런 값도 반환하지 않도록 되어있습니다. </dd> + <dt><code>failureCallback</code> {{deprecated_inline}}</dt> + <dd>ICE candidate 추가 시도가 실패하면 호출되는 함수입니다. 실패에 대한 이유를 설명하는 객체인 {{domxref("DOMException")}}을 입력 변수로 받습니다.</dd> +</dl> + +<h3 id="반환_값">반환 값</h3> + +<p>{{jsxref("Promise")}}는 candidate가 ICE 에이전트에 의해 원격 유저의 설명 (description)에 성공적으로 추가되면 fulfilled 됩니다. 프로미스는 입력 변수가 없습니다.</p> + +<h3 id="예외_처리">예외 처리</h3> + +<p>ICE candidate 추가 시도 중 에러가 발생하면, 이 메소드에서 반환되는 {{jsxref("Promise")}}는 거절됩니다. 그리고 거절 핸들러로 전달되는 지정된 {{domxref("DOMException")}} 객체안에 존재하는 {{domxref("DOMException.name", "name")}} 속성으로 아래의 에러 중 하나를 반환하게 됩니다.</p> + +<dl> + <dt><code>TypeError</code></dt> + <dd>명시한 candidate의 {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}} 및{{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}}가 모두 <code>null</code> 입니다.</dd> + <dt><code>InvalidStateError</code></dt> + <dd>현재 <code>RTCPeerConnection</code>은 어떠한 원격 유저와도 연결이 되어있지 않습니다. {{domxref("RTCPeerConnection.remoteDescription", "remoteDescription")}} 값이 <code>null</code>입니다.</dd> + <dt><code>OperationError</code></dt> + <dd>이 에러는 여러가지 이유 때문에 발생합니다: + <ul> + <li>지정된 {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}} 값이 non-<code>null</code>이고, {{domxref("RTCPeerConnection.remoteDescription", "remoteDescription")}}안에 존재하는 어떠한 미디어 description의 미디어 ID와도 일치하지 않음</li> + <li>지정된 {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}}의 값이 원격 설명 (description)에 포함된 미디어의 숫자와 같거나 큼</li> + <li>지정된 {{domxref("RTCIceCandidate.usernameFragment", "ufrag")}}가 어떠한 원격 설명 (description) 안의 <code>ufrag</code> 필드와 일치하지 않음</li> + <li>{{domxref("RTCIceCandidate", "candidate")}} 문자열에 존재하는 하나 혹은 여러개의 값들이 올바르지 않거나, 파싱 될 수 없음</li> + <li>어떠한 이유에서던 candidate를 추가하려는 시도가 실패<span style="display: none;"> </span></li> + </ul> + </dd> +</dl> + +<h2 id="예시">예시</h2> + +<p>아래의 코드는 임의의 signaling 채널을 통해 어떻게 ICE candidate를 알리는지를 보여줍니다.</p> + +<pre class="brush: 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 + } +}</pre> + +<p>원격 유저에 의해 이러한 방식으로 신호를 전달한 마지막 candiate는 "candidate 종료"를 나타내는 특수한 candidate가 됩니다. "candidate 종료"를 수동으로 설정하려면 다음과 같이 하면 됩니다:</p> + +<pre class="brush: js">pc.addIceCandidate({candidate:''}); +</pre> + +<p>하지만, 대부분의 경우 {{domxref("RTCPeerConnection")}}가 적절한 이벤트를 보내서 처리해주기 때문에 이를 수동으로 확인해야 할 필요는 없습니다.</p> + +<h2 id="명세">명세</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">명세</th> + <th scope="col">상태</th> + <th scope="col">코멘트</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-addIceCandidate-Promise-void--RTCIceCandidateInit-RTCIceCandidate-candidate', 'RTCPeerConnection.addIceCandidate()') }}</td> + <td>{{ Spec2('WebRTC 1.0') }}</td> + <td>Initial specification.</td> + </tr> + <tr> + <td>{{SpecName("WebRTC 1.0", "#widl-RTCPeerConnection-addIceCandidate-void-RTCIceCandidateInit-RTCIceCandidate-candidate-VoidFunction-successCallback-RTCPeerConnectionErrorCallback-failureCallback", "RTCPeerConnection.addIceCandidate()")}} {{deprecated_inline}}</td> + <td>{{Spec2("WebRTC 1.0")}}</td> + <td>Initial specification.</td> + </tr> + </tbody> +</table> + +<h2 id="브라우저_호환성">브라우저 호환성</h2> + + + +<p>{{Compat("api.RTCPeerConnection.addIceCandidate")}}</p> + +<h2 id="참조">참조</h2> + +<ul> + <li><a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a></li> + <li><a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a></li> + <li><a href="/en-US/docs/Web/API/WebRTC_API/Architecture">WebRTC architecture overview</a></li> + <li><a href="/en-US/docs/Web/API/WebRTC_API/Connectivity">WebRTC connectivity</a></li> + <li><a href="/en-US/docs/Web/API/WebRTC_API/Session_lifetime">Lifetime of a WebRTC session</a></li> +</ul> |