← WebRTC 1.0 Spesifikasyonu

Eşler Arası Bağlantılar

W3C WebRTC 1.0 Spesifikasyonu — Türkçe Çeviri

4. Eşler arası bağlantılar

4.8 Etkileşimli Bağlanabilirlik Kurulumu için Arayüzler

4.8.1 RTCIceCandidate Arayüzü

Bu arayüz, [RFC5245] Bölüm 2’de tanımlandığı üzere bir ICE adayını tanımlar. candidate, sdpMid, sdpMLineIndex ve usernameFragment dışındaki kalan öznitelikler, iyi biçimlendirilmiş olması durumunda candidateInitDict içindeki candidate üyesinin ayrıştırılmasından türetilir. 

[Exposed=Window]
                        interface RTCIceCandidate {
                          constructor(optional RTCIceCandidateInit candidateInitDict = {});
                          readonly attribute DOMString candidate;
                          readonly attribute DOMString? sdpMid;
                          readonly attribute unsigned short? sdpMLineIndex;
                          readonly attribute DOMString? foundation;
                          readonly attribute RTCIceComponent? component;
                          readonly attribute unsigned long? priority;
                          readonly attribute DOMString? address;
                          readonly attribute RTCIceProtocol? protocol;
                          readonly attribute unsigned short? port;
                          readonly attribute RTCIceCandidateType? type;
                          readonly attribute RTCIceTcpCandidateType? tcpType;
                          readonly attribute DOMString? relatedAddress;
                          readonly attribute unsigned short? relatedPort;
                          readonly attribute DOMString? usernameFragment;
                          readonly attribute RTCIceServerTransportProtocol? relayProtocol;
                          readonly attribute DOMString? url;
                          RTCIceCandidateInit toJSON();
                        };

Kurucu

constructor()

RTCIceCandidate() kurucusu, içeriği yeni RTCIceCandidate nesnesini başlatmak için kullanılan candidateInitDict adlı bir sözlük bağımsız değişkeni alır.

Çağrıldığında, aşağıdaki adımları çalıştırın:

  1. candidateInitDict içindeki sdpMid ve sdpMLineIndex üyelerinin her ikisi de null ise, bir TypeError fırlatın.
  2. candidateInitDict ile bir RTCIceCandidate oluşturmanın sonucunu döndürün.

Bir candidateInitDict sözlüğü ile bir RTCIceCandidate oluşturmak için aşağıdaki adımları çalıştırın:

  1. iceCandidate değişkenini yeni oluşturulmuş bir RTCIceCandidate nesnesi olarak belirleyin.
  2. iceCandidate için aşağıdaki özniteliklere ait iç yuvaları oluşturun ve null ile başlatın: foundation, component, priority, address, protocol, port, type, tcpType, relatedAddress ve relatedPort.
  3. iceCandidate için aşağıdaki özniteliklere ait iç yuvaları oluşturun ve bunları candidateInitDict içindeki adaşlarıyla başlatın: candidate, sdpMid, sdpMLineIndex, usernameFragment.
  4. candidate değişkenini candidateInitDict içindeki candidate sözlük üyesi olarak belirleyin. candidate boş bir dize değilse, aşağıdaki adımları çalıştırın:
  5. candidate değerini candidate-attribute dilbilgisini kullanarak ayrıştırın.
  6. candidate-attribute ayrıştırması başarısız olursa, bu adımları iptal edin.
  7. Ayrıştırma sonucundaki herhangi bir alan, iceCandidate içindeki karşılık gelen öznitelik için geçersiz bir değeri temsil ediyorsa, bu adımları iptal edin.
  8. iceCandidate içindeki karşılık gelen iç yuvaları, ayrıştırılmış sonucun alan değerlerine ayarlayın.
  9. iceCandidate nesnesini döndürün.
RTCIceCandidate kurucusu, candidateInitDict içindeki sözlük üyeleri için yalnızca temel ayrıştırma ve tür denetimi yapar. candidate, sdpMid, sdpMLineIndex, usernameFragment değerlerinin karşılık gelen oturum tanımıyla iyi biçimlendirilmişliğine ilişkin ayrıntılı doğrulama, RTCIceCandidate nesnesi addIceCandidate() fonksiyonuna geçirildiğinde yapılır.

Geriye dönük uyumluluğu korumak için, candidate özniteliğinin ayrıştırılmasındaki herhangi bir hata yok sayılır. Bu durumda, candidate özniteliği candidateInitDict içinde verilen ham candidate dizesini tutar; ancak foundation, priority vb. türetilmiş öznitelikler null olarak ayarlanır.

Öznitelikler

Aşağıdaki özniteliklerin çoğu [RFC5245] Bölüm 15.1’de tanımlanmıştır.

candidate (DOMString türünde, salt okunur)

Bu, [RFC5245] Bölüm 15.1’de tanımlandığı üzere candidate-attribute değerini taşır. Bu RTCIceCandidate bir adayların sonu göstergesini veya eş-yansıtmalı (peer reflexive) bir uzak adayı temsil ediyorsa, candidate boş bir dizedir.

sdpMid (DOMString türünde, salt okunur, boş olabilir)

null değilse, bu adayın ilişkilendirildiği ortam bileşeni için [RFC5888]’de tanımlanan ortam akışı "identification-tag" değerini içerir.

sdpMLineIndex (unsigned short türünde, salt okunur, boş olabilir)

null değilse, bu adayın ilişkilendirildiği SDP içindeki ortam tanımının indeksini (sıfırdan başlayarak) belirtir.

foundation (DOMString türünde, salt okunur, boş olabilir)

ICE’nin birden fazla RTCIceTransport üzerinde görünen adayları ilişkilendirmesine olanak tanıyan benzersiz bir tanımlayıcıdır.

component (RTCIceComponent türünde, salt okunur, boş olabilir)

Adayın atanmış ağ bileşeni ("rtp" veya "rtcp"). Bu, candidate-attribute içindeki component-id alanına karşılık gelir ve RTCIceComponent içinde tanımlandığı şekilde dize temsiline dönüştürülmüştür.

priority (unsigned long türünde, salt okunur, boş olabilir)

Adayın atanmış önceliğidir.

address (DOMString türünde, salt okunur, boş olabilir)

Adayın adresidir; IPv4 adreslerini, IPv6 adreslerini ve tam nitelikli alan adlarını (FQDN) destekler. Bu, candidate-attribute içindeki connection-address alanına karşılık gelir.

Uzak adaylar, örneğin [[SelectedCandidatePair]].remote aracılığıyla açığa çıkarılabilir. Varsayılan olarak, kullanıcı aracısı açığa çıkarılan herhangi bir uzak aday için address özniteliğini MUST null olarak bırakmalıdır. Bir RTCPeerConnection örneği, web uygulaması tarafından addIceCandidate kullanılarak bir adresi öğrendiğinde, kullanıcı aracısı bu yeni öğrenilen adrese sahip bir uzak adayı temsil eden RTCPeerConnection örneğinin herhangi bir RTCIceCandidate’ında address özniteliği değerini açığa çıkarabilir.

ICE aracılığıyla toplanan ve RTCIceCandidate örnekleri içinde uygulamaya görünür hale getirilen adaylardaki adresler, WebRTC etkin olmayan bir tarayıcıda kullanıcının beklemiş olabileceğinden daha fazla bilgi (ör. konum, yerel ağ topolojisi) açığa çıkarabilir.

Bu adresler her zaman uygulamaya açığa çıkarılır ve potansiyel olarak iletişim kurulan tarafa da açığa çıkarılır; ayrıca herhangi bir özel kullanıcı onayı olmaksızın da açığa çıkarılabilir (ör. veri kanallarıyla kullanılan eş bağlantıları için veya yalnızca ortam almak için).

Bu adresler ayrıca geçici veya kalıcı çapraz-köken durumları olarak kullanılabilir ve böylece cihazın parmak izi çıkarma yüzeyine katkıda bulunur. !(Bu bir parmak izi çıkarma vektörüdür.){width="15" height="21"}

Uygulamalar, RTCConfiguration içindeki iceTransportPolicy üyesi aracılığıyla ICE aracısını yalnızca röle adaylarını raporlamaya zorlayarak, adreslerin iletişim kurulan tarafa açığa çıkarılmasını geçici veya kalıcı olarak önleyebilir.

Uygulamanın kendisine açığa çıkarılan adresleri sınırlamak için, tarayıcılar [RFC8828]’de tanımlandığı üzere yerel adreslerin paylaşımıyla ilgili farklı ilkeleri kullanıcılarına sunabilir.

protocol (RTCIceProtocol türünde, salt okunur, boş olabilir)

Adayın protokolüdür ("udp"/"tcp"). Bu, candidate-attribute içindeki transport alanına karşılık gelir.

port (unsigned short türünde, salt okunur, boş olabilir)

Adayın bağlantı noktasıdır.

type (RTCIceCandidateType türünde, salt okunur, boş olabilir)

Adayın türüdür. Bu, candidate-attribute içindeki candidate-types alanına karşılık gelir.

tcpType (RTCIceTcpCandidateType türünde, salt okunur, boş olabilir)

protocol "tcp" ise, tcpType TCP adayının türünü temsil eder. Aksi halde, tcpType null değerindedir. Bu, candidate-attribute içindeki tcp-type alanına karşılık gelir.

relatedAddress (DOMString türünde, salt okunur, boş olabilir)

Röle veya yansıtmalı aday gibi başka bir adaydan türetilen bir aday için relatedAddress, türetildiği adayın IP adresidir. Ana bilgisayar (host) adayları için relatedAddress null’dır. Bu, candidate-attribute içindeki rel-address alanına karşılık gelir.

relatedPort (unsigned short türünde, salt okunur, boş olabilir)

Röle veya yansıtmalı aday gibi başka bir adaydan türetilen bir aday için relatedPort, türetildiği adayın bağlantı noktasıdır. Ana bilgisayar adayları için relatedPort null’dır. Bu, candidate-attribute içindeki rel-port alanına karşılık gelir.

usernameFragment (DOMString türünde, salt okunur, boş olabilir)

Bu, [RFC5245] Bölüm 15.4’te tanımlanan ufrag değerini taşır.

relayProtocol (RTCIceServerTransportProtocol türünde, salt okunur, boş olabilir)

"relay" türündeki yerel adaylar için bu, uç noktanın TURN sunucusuyla iletişim kurmak için kullandığı protokoldür. Diğer tüm adaylar için null’dır.

url (DOMString türünde, salt okunur, boş olabilir)

"srflx" türündeki veya "relay" türündeki yerel adaylar için bu, adayın elde edildiği ICE sunucusunun URL’sidir. Diğer tüm adaylar için null’dır.

Yöntemler

toJSON()

RTCIceCandidate arayüzünün toJSON() işlemini çağırmak için aşağıdaki adımları çalıştırın:

  1. json değişkenini yeni bir RTCIceCandidateInit sözlüğü olarak belirleyin.
  2. «candidate, sdpMid, sdpMLineIndex, usernameFragment» kümesindeki her bir öznitelik tanımlayıcısı attr için:
  3. Bu RTCIceCandidate nesnesi verildiğinde, attr ile tanımlanan özniteliğin temel değerini almanın sonucunu value olarak belirleyin.
  4. json[attr] değerini value olarak ayarlayın.
  5. json nesnesini döndürün.
WebIDLdictionary RTCIceCandidateInit {
                          DOMString candidate = "";
                          DOMString? sdpMid = null;
                          unsigned short? sdpMLineIndex = null;
                          DOMString? usernameFragment = null;
                        };

RTCIceCandidateInit Sözlüğü Üyeleri

candidate · (DOMString türünde · varsayılan "")

[RFC5245] Bölüm 15.1’de tanımlandığı üzere candidate-attribute değerini taşır. Bu, adayların sonu göstergesini temsil ediyorsa, candidate boş bir dizedir.

sdpMid · (DOMString türünde · boş olabilir · varsayılan null)

null değilse, bu adayın ilişkilendirildiği ortam bileşeni için [RFC5888]’de tanımlanan ortam akışı "identification-tag" değerini içerir.

sdpMLineIndex · (unsigned short türünde · boş olabilir · varsayılan null)

null değilse, bu adayın ilişkilendirildiği SDP içindeki ortam tanımının indeksini (sıfırdan başlayarak) belirtir.

usernameFragment · (DOMString türünde · boş olabilir · varsayılan null)

null değilse, [RFC5245] Bölüm 15.4’te tanımlanan ufrag değerini taşır.

4.8.1.1 candidate-attribute Dilbilgisi

candidate-attribute dilbilgisi, RTCIceCandidate() kurucusunda candidateInitDict içindeki candidate üyesini ayrıştırmak için kullanılır.

candidate-attribute için birincil dilbilgisi [RFC5245] Bölüm 15.1’de tanımlanmıştır. Buna ek olarak, tarayıcı [RFC6544] Bölüm 4.5’te tanımlanan ICE TCP için dilbilgisi uzantısını MUST desteklemelidir.

Tarayıcı, diğer RFC’lerde tanımlanan candidate-attribute için başka dilbilgisi uzantılarını MAY destekleyebilir.

4.8.1.2 RTCIceProtocol Enum’u

RTCIceProtocol, ICE adayının protokolünü temsil eder.

WebIDLenum RTCIceProtocol {
                          "udp",
                          "tcp"
                        };
Enum değeri Açıklama
udp [RFC5245]’te tanımlandığı üzere bir UDP adayı.
tcp [RFC6544]’te tanımlandığı üzere bir TCP adayı.

RTCIceProtocol Numaralandırma açıklaması

4.8.1.3 RTCIceTcpCandidateType Enum’u

RTCIceTcpCandidateType, [RFC6544]’te tanımlandığı üzere ICE TCP adayının türünü temsil eder.

WebIDLenum RTCIceTcpCandidateType {
                          "active",
                          "passive",
                          "so"
                        };
Enum değeri Açıklama

RTCIceTcpCandidateType Numaralandırma açıklaması

Kullanıcı aracısı genellikle yalnızca active ICE TCP adaylarını toplar.

4.8.1.4 RTCIceCandidateType Enum’u

RTCIceCandidateType, [RFC5245] Bölüm 15.1’de tanımlandığı üzere ICE adayının türünü temsil eder.

WebIDLenum RTCIceCandidateType {
                          "host",
                          "srflx",
                          "prflx",
                          "relay"
                        };
Enum değeri Açıklama
host [RFC5245] Bölüm 4.1.1.1’de tanımlandığı üzere bir ana bilgisayar adayı.
srflx [RFC5245] Bölüm 4.1.1.2’de tanımlandığı üzere bir sunucu yansıtmalı adayı.

Enum değeri Açıklama
prflx [RFC5245] Bölüm 4.1.1.2’de tanımlandığı üzere bir eş yansıtmalı adayı.
relay [RFC5245] Bölüm 7.1.3.2.1’de tanımlandığı üzere bir röle adayı.

RTCIceCandidateType Numaralandırma açıklaması

4.8.1.5 RTCIceServerTransportProtocol Enum’u

RTCIceServerTransportProtocol, [RFC8656] Bölüm 3.1’de tanımlandığı üzere istemci ile sunucu arasında kullanılan taşıma protokolünün türünü temsil eder.

WebIDLenum RTCIceServerTransportProtocol {
                          "udp",
                          "tcp",
                          "tls",
                        };
Enum değeri Açıklama
udp TURN istemcisi, sunucuya taşıma olarak UDP kullanmaktadır.
tcp TURN istemcisi, sunucuya taşıma olarak TCP kullanmaktadır.
tls TURN istemcisi, sunucuya taşıma olarak TLS kullanmaktadır.

RTCIceServerTransportProtocol Numaralandırma açıklaması

4.8.2 RTCPeerConnectionIceEvent

RTCPeerConnection’ın icecandidate olayı, RTCPeerConnectionIceEvent arayüzünü kullanır.

Bir RTCIceCandidate nesnesi içeren bir RTCPeerConnectionIceEvent olayı tetiklenirken, hem sdpMid hem de sdpMLineIndex için değerler MUST dahil edilmelidir. RTCIceCandidate "srflx" türünde veya "relay" türünde ise, olayın url özelliği, adayın elde edildiği ICE sunucusunun URL’sine ayarlanmalıdır.

icecandidate olayı üç farklı türde gösterim için kullanılır:
  • Bir aday toplanmıştır. Olayın candidate üyesi normal şekilde doldurulur. Uzak eşe sinyallenmeli ve addIceCandidate içine geçirilmelidir.
  • Bir RTCIceTransport, adayların bir üretimini toplamayı tamamlamıştır ve [RFC8838] Bölüm 8.2’de tanımlandığı üzere bir adayların sonu göstergesi sağlamaktadır. Bu, candidate.candidate değerinin boş bir dizeye ayarlanmasıyla gösterilir. candidate nesnesi, adayların sonu göstergesini uzak eşe sağlamak için tipik bir ICE adayı gibi sinyallenmeli ve addIceCandidate içine geçirilmelidir.
  • Tüm RTCIceTransportlar aday toplamayı tamamlamıştır ve RTCPeerConnection nesnesinin RTCIceGatheringState durumu "complete" değerine geçmiştir. Bu durum, olayın candidate üyesinin null olarak ayarlanmasıyla belirtilir. Bu yalnızca geriye dönük uyumluluk için vardır ve bu olayın uzak eşe bildirilmesi gerekmez. "complete" durumundaki bir icegatheringstatechange olayına eşdeğerdir. 
WebIDL[Exposed=Window]
                        interface RTCPeerConnectionIceEvent : Event {
                          constructor(DOMString type, optional RTCPeerConnectionIceEventInit eventInitDict = {});
                          readonly attribute RTCIceCandidate? candidate;
                          readonly attribute DOMString? url;
                        };

Yapıcılar

RTCPeerConnectionIceEvent.constructor()

:

Öznitelikler

candidate · RTCIceCandidate türünde · salt okunur · boş olabilir

candidate özniteliği, olaya neden olan yeni ICE adayını içeren RTCIceCandidate nesnesidir.

Aday toplamanın sona erdiğini belirtmek için bir olay üretildiğinde bu öznitelik

null olarak ayarlanır.

Birden fazla medya bileşeni olsa bile, null aday içeren yalnızca tek bir olay tetiklenir.

url · DOMString türünde · salt okunur · boş olabilir

url özniteliği, bu adayın toplanmasında kullanılan STUN veya TURN sunucusunu tanımlayan STUN ya da TURN URL’sidir. Aday bir STUN veya TURN sunucusundan toplanmadıysa bu parametre null olarak ayarlanır.

Candidate Correction 23: RTCPeerConnectionIceEvent.url özniteliğini kullanım dışı olarak

işaretle (PR #2773)

Bu öznitelik kullanım dışıdır; yalnızca eski uyumluluk nedenleriyle vardır. Adayın url değerini tercih edin. 

WebIDLdictionary RTCPeerConnectionIceEventInit : EventInit {
                          RTCIceCandidate? candidate;
                          DOMString? url;
                        };

Sözlük RTCPeerConnectionIceEventInit Üyeleri

candidate · RTCIceCandidate türünde · boş olabilir

RTCPeerConnectionIceEvent arayüzündeki candidate özniteliğine bakın.

url · DOMString türünde · boş olabilir

Bu adayın toplanmasında kullanılan STUN veya TURN sunucusunu tanımlayan STUN ya da TURN URL’sidir.

4.8.3 RTCPeerConnectionIceErrorEvent

RTCPeerConnection nesnesinin icecandidateerror olayı, RTCPeerConnectionIceErrorEvent arayüzünü kullanır. 

WebIDL[Exposed=Window]
                        interface RTCPeerConnectionIceErrorEvent : Event {
                          constructor(DOMString type, RTCPeerConnectionIceErrorEventInit eventInitDict);
                          readonly attribute DOMString? address;
                          readonly attribute unsigned short? port;
                          readonly attribute DOMString url;
                          readonly attribute unsigned short errorCode;
                          readonly attribute USVString errorText;
                        };

Yapıcılar

RTCPeerConnectionIceErrorEvent.constructor()

:

Öznitelikler

address · DOMString türünde · salt okunur · boş olabilir

address özniteliği, STUN veya TURN sunucusuyla iletişim kurmak için kullanılan yerel IP adresidir.

Çok bağlantılı (multihomed) bir sistemde, sunucuya ulaşmak için birden fazla arayüz

kullanılabilir ve bu öznitelik uygulamanın hatanın hangi arayüzde meydana geldiğini belirlemesine olanak tanır.

Yerel IP adresi değeri bir yerel adayın parçası olarak zaten açığa çıkarılmamışsa, address özniteliği null olarak ayarlanır.

port · unsigned short türünde · salt okunur · boş olabilir

port özniteliği, STUN veya TURN sunucusuyla iletişim kurmak için kullanılan bağlantı noktasıdır.

address özniteliği null ise, port özniteliği de

null olarak ayarlanır.

url · DOMString türünde · salt okunur

url özniteliği, hatanın meydana geldiği STUN veya TURN sunucusunu tanımlayan STUN ya da TURN URL’sidir.

errorCode · unsigned short türünde · salt okunur

errorCode özniteliği, STUN veya TURN sunucusu tarafından döndürülen sayısal STUN hata kodudur [STUN-PARAMETERS].

Hiçbir ana makine (host) adayı sunucuya ulaşamazsa, errorCode STUN hata kodu

aralığının dışında olan 701 değerine ayarlanır. Bu hata, RTCIceGatheringState durumu "gathering" iken sunucu URL’si başına yalnızca bir kez tetiklenir.

errorText · USVString türünde · salt okunur

errorText özniteliği, STUN veya TURN sunucusu tarafından döndürülen STUN gerekçe metnidir [STUN-PARAMETERS].

Sunucuya ulaşılamadıysa, errorText hataya ilişkin ayrıntılar sağlayan uygulamaya

özgü bir değere ayarlanır.

WebIDLdictionary RTCPeerConnectionIceErrorEventInit : EventInit {
                          DOMString? address;
                          unsigned short? port;
                          DOMString url;
                          required unsigned short errorCode;
                          USVString errorText;
                        };

Sözlük RTCPeerConnectionIceErrorEventInit Üyeleri

address · DOMString türünde · boş olabilir

STUN veya TURN sunucusuyla iletişim kurmak için kullanılan yerel adres ya da null.

port · unsigned short türünde · boş olabilir

STUN veya TURN sunucusuyla iletişim kurmak için kullanılan yerel bağlantı noktası ya da null.

url · DOMString türünde

Hatanın meydana geldiği STUN veya TURN sunucusunu tanımlayan STUN ya da TURN URL’si.

errorCode · unsigned short türünde · zorunlu

STUN veya TURN sunucusu tarafından döndürülen sayısal STUN hata kodu.

errorText · USVString türünde

STUN veya TURN sunucusu tarafından döndürülen STUN gerekçe metni.

← 4.7 Oturum Müzakere Modeli4.9 Sertifika Yönetimi →