6. Eşler arası Veri API’si

Eşler arası Veri API’si, bir web uygulamasının eşler arasında genel uygulama verilerini gönderip almasına olanak tanır. Veri gönderme ve alma API’si, Web Sockets davranışını modeller.

6.2 RTCDataChannel

RTCDataChannel arayüzü, iki eş arasında çift yönlü bir veri kanalını temsil eder. Bir RTCDataChannel, bir RTCPeerConnection nesnesi üzerindeki bir fabrika yöntemi aracılığıyla oluşturulur. Tarayıcılar arasında gönderilen mesajlar [RFC8831] ve [RFC8832]’de açıklanmıştır.

RTCDataChannel ile bir bağlantı kurmanın iki yolu vardır. Birinci yol, negotiated RTCDataChannelInit sözlük üyesi ayarlanmamış ya da varsayılan değeri olan false olarak ayarlanmış şekilde eşlerden birinde basitçe bir RTCDataChannel oluşturmaktır. Bu, yeni kanalı bant içi olarak duyurur ve diğer eşte karşılık gelen RTCDataChannel nesnesiyle bir RTCDataChannelEvent tetikler. İkinci yol ise uygulamanın RTCDataChannel’ı müzakere etmesine izin vermektir. Bunu yapmak için, negotiated RTCDataChannelInit sözlük üyesi true olarak ayarlanmış bir RTCDataChannel nesnesi oluşturun ve bant dışı olarak (örneğin bir web sunucusu aracılığıyla) diğer tarafa, negotiated RTCDataChannelInit sözlük üyesi true ve aynı id ile karşılık gelen bir RTCDataChannel oluşturması GEREKTİĞİNİ bildirin. Bu, ayrı ayrı oluşturulmuş iki RTCDataChannel nesnesini bağlar. İkinci yol, asimetrik özelliklere sahip kanallar oluşturmayı ve eşleşen id’ler belirterek bildirime dayalı bir şekilde kanallar oluşturmayı mümkün kılar.

Her RTCDataChannel, gerçek veriyi diğer eşe taşımak için kullanılan ilişkili bir temel veri taşımasına sahiptir. Bir RTCSctpTransport kullanan SCTP veri kanalları durumunda (SCTP ilişkisinin durumunu temsil eder), temel veri taşıması SCTP akış çiftidir. Sıralı teslim ayarları ve güvenilirlik modu gibi temel veri taşımasının taşıma özellikleri, kanal oluşturulurken eş tarafından yapılandırılır. Bir kanalın özellikleri, kanal oluşturulduktan sonra değiştirilemez. Eşler arasındaki gerçek tel protokolü WebRTC DataChannel Protocol belirtimi [RFC8831] tarafından tanımlanır.

Bir RTCDataChannel, farklı güvenilirlik modlarında çalışacak şekilde yapılandırılabilir. Güvenilir bir kanal, verinin yeniden iletimler yoluyla diğer eşe teslim edilmesini garanti eder. Güvenilir olmayan bir kanal ise ya yeniden iletim sayısını sınırlayacak şekilde (maxRetransmits) ya da iletimlerin (yeniden iletimler dahil) izin verildiği bir süreyi ayarlayacak şekilde (maxPacketLifeTime) yapılandırılır. Bu özellikler aynı anda kullanılamaz ve böyle bir girişim bir hatayla sonuçlanır. Bu özelliklerden hiçbirinin ayarlanmaması, güvenilir bir kanal ile sonuçlanır.

createDataChannel ile oluşturulan ya da bir RTCDataChannelEvent aracılığıyla dağıtılan bir RTCDataChannel, başlangıçta MUST "connecting" durumunda olmalıdır. RTCDataChannel nesnesinin temel veri taşıması hazır olduğunda, kullanıcı aracısı MUST RTCDataChannel’ı açık olarak duyurmalıdır.

6.2.1 Bir veri kanalı oluşturma

Bir RTCDataChannel oluşturmak için aşağıdaki adımları çalıştırın:

1. channel, yeni oluşturulmuş bir RTCDataChannel nesnesi olsun.
2. channel, [[ReadyState]] adlı bir iç yuvaya sahip olsun ve bu yuva "connecting" olarak başlatılsın.
3. channel, [[BufferedAmount]] adlı bir iç yuvaya sahip olsun ve bu yuva 0 olarak başlatılsın.
4. channel, [[DataChannelLabel]], [[Ordered]], [[MaxPacketLifeTime]], [[MaxRetransmits]], [[DataChannelProtocol]], [[Negotiated]] ve [[DataChannelId]] adlı iç yuvalara sahip olsun.
5. channel, [[IsTransferable]] adlı bir iç yuvaya sahip olsun ve bu yuva true olarak başlatılsın.
6. Aşağıdaki adımı çalıştırmak için bir görev sıraya alın:
7. channel.[[IsTransferable]] değerini false olarak ayarlayın.

Bu görev, channel için veri kanalında mesaj alma algoritması tarafından sıraya alınan herhangi bir görevden önce çalıştırılmalıdır. Bu, bir RTCDataChannel aktarımı sırasında hiçbir mesajın kaybolmamasını sağlar.

1. channel’ı döndürün.

6.2.2 Bir veri kanalını açık olarak duyurma

Kullanıcı aracısı bir RTCDataChannel’ı açık olarak duyuracağı zaman, kullanıcı aracısı MUST aşağıdaki adımları çalıştırmak üzere bir görev sıraya almalıdır:

1. İlişkili RTCPeerConnection nesnesinin [[IsClosed]] yuvası true ise, bu adımları sonlandırın.
2. Duyurulacak RTCDataChannel nesnesi channel olsun.
3. channel.[[ReadyState]] "closing" veya "closed" ise, bu adımları sonlandırın.
4. channel.[[ReadyState]] değerini "open" olarak ayarlayın.
5. channel üzerinde open adlı bir olay tetikleyin.

6.2.3 Bir veri kanalı örneğini duyurma

Bir temel veri taşıması duyurulacağı zaman (diğer eş, negotiated ayarlanmamış ya da false olarak ayarlanmış bir kanal oluşturduğunda), oluşturma sürecini başlatmayan eşin kullanıcı aracısı MUST aşağıdaki adımları çalıştırmak üzere bir görev sıraya almalıdır:

1. connection, temel veri taşımasıyla ilişkili RTCPeerConnection nesnesi olsun.
2. connection.[[IsClosed]] true ise, bu adımları sonlandırın.
3. Bir RTCDataChannel oluşturun, channel.
4. configuration, WebRTC DataChannel Protocol belirtimi [RFC8832] tarafından tanımlanan temel veri taşımasını kurma sürecinin bir parçası olarak diğer eşten alınan bir bilgi paketi olsun.
5. channel.[[DataChannelLabel]], [[Ordered]], [[MaxPacketLifeTime]], [[MaxRetransmits]], [[DataChannelProtocol]] ve [[DataChannelId]] iç yuvalarını configuration içindeki karşılık gelen değerlerle başlatın.
6. channel.[[Negotiated]] değerini false olarak başlatın.
7. channel’ı connection.[[DataChannels]]’a ekleyin.
8. channel.[[ReadyState]] değerini "open" olarak ayarlayın (ancak henüz open olayını tetiklemeyin).

1. connection üzerinde, channel özniteliği channel olarak ayarlanmış şekilde RTCDataChannelEvent arayüzünü kullanarak datachannel adlı bir olay tetikleyin.
2. Veri kanalını açık olarak duyurun.

6.2.4 Kapatma prosedürü

6.2.4 Kapatma prosedürü

Bir RTCDataChannel nesnesinin temel veri taşıması, kapatma prosedürü çalıştırılarak ani olmayan bir şekilde sonlandırılabilir. Bu gerçekleştiğinde kullanıcı aracısı MUST aşağıdaki adımları çalıştırmak üzere bir görev sıraya almalıdır:

1. Temel veri taşıması kapatılan RTCDataChannel nesnesi channel olsun.
2. channel ile ilişkili RTCPeerConnection nesnesi connection olsun.
3. channel’ı connection.[[DataChannels]]’dan kaldırın.
4. Prosedür channel.close tarafından başlatılmadıysa, channel.[[ReadyState]] değerini "closing" olarak ayarlayın ve channel üzerinde closing adlı bir olay tetikleyin.
5. Aşağıdaki adımları paralel olarak paralel olarak çalıştırın:
6. channel’ın şu anda beklemede olan tüm mesajlarının gönderimini tamamlayın.
7. channel’ın temel veri taşıması için tanımlanan kapatma prosedürünü izleyin:
8. SCTP tabanlı bir taşıma durumunda, [RFC8831], bölüm 6.7’yi izleyin.
9. İlişkili prosedürü izleyerek channel’ın veri taşımasını closed kapatın.

6.2.5 Bir veri kanalını kapalı olarak duyurma

Bir RTCDataChannel nesnesinin temel veri taşıması kapatıldığında, kullanıcı aracısı MUST aşağıdaki adımları çalıştırmak üzere bir görev sıraya almalıdır:

1. Temel veri taşıması kapatılan RTCDataChannel nesnesi channel olsun.
2. channel.[[ReadyState]] "closed" ise, bu adımları sonlandırın.
3. channel.[[ReadyState]] değerini "closed" olarak ayarlayın.
4. Hâlâ oradaysa, channel’ı connection.[[DataChannels]]’dan kaldırın.
5. Taşıma bir hata ile kapatıldıysa, channel üzerinde errorDetail özniteliği "sctp-failure" olarak ayarlanmış şekilde RTCErrorEvent arayüzünü kullanarak error adlı bir olay tetikleyin.
6. channel üzerinde close adlı bir olay tetikleyin.

6.2.6 Veri kanalı aktarımı

value ve dataHolder verildiğinde RTCDataChannel aktarım adımları şunlardır:

1. value.[[IsTransferable]] false ise, bir DataCloneError DOMException fırlatın.
2. dataHolder.[[ReadyState]] değerini value.[[ReadyState]] olarak ayarlayın.
3. dataHolder.[[DataChannelLabel]] değerini value.[[DataChannelLabel]] olarak ayarlayın.
4. dataHolder.[[Ordered]] değerini value.[[Ordered]] olarak ayarlayın.
5. dataHolder.[[MaxPacketLifeTime]] değerini value..[[MaxPacketLifeTime]] olarak ayarlayın
6. dataHolder.[[MaxRetransmits]] değerini value.[[MaxRetransmits]] olarak ayarlayın.
7. dataHolder.[[DataChannelProtocol]] değerini value.[[DataChannelProtocol]] olarak ayarlayın.
8. dataHolder.[[Negotiated]] değerini value.[[Negotiated]] olarak ayarlayın.
9. dataHolder.[[DataChannelId]] değerini value.[[DataChannelId]] olarak ayarlayın.
10. dataHolder’ın temel veri taşımasını value’nun temel veri taşıması olarak ayarlayın.
11. value.[[IsTransferable]] değerini false olarak ayarlayın.
12. value.[[ReadyState]] değerini "closed" olarak ayarlayın.

dataHolder ve channel verildiğinde RTCDataChannel aktarım-alma adımları şunlardır:

1. channel.[[ReadyState]] değerini dataHolder.[[ReadyState]] ile başlatın.
2. channel.[[DataChannelLabel]] değerini dataHolder.[[DataChannelLabel]] ile başlatın.
3. channel.[[Ordered]] değerini dataHolder.[[Ordered]] ile başlatın.
4. channel.[[MaxPacketLifeTime]] değerini dataHolder.[[MaxPacketLifeTime]] ile başlatın.
5. channel.[[MaxRetransmits]] değerini dataHolder.[[MaxRetransmits]] ile başlatın.
6. channel.[[DataChannelProtocol]] değerini dataHolder.[[DataChannelProtocol]] ile başlatın.
7. channel.[[Negotiated]] değerini dataHolder.[[Negotiated]] ile başlatın.
8. channel.[[DataChannelId]] değerini dataHolder.[[DataChannelId]] ile başlatın.
9. channel’ın temel veri taşımasını dataHolder’ın temel veri taşıması ile başlatın.

Yukarıdaki adımların [[BufferedAmount]]’ı aktarmasına gerek yoktur; çünkü değeri her zaman 0 olacaktır. Bunun nedeni, bir RTCDataChannel’ın yalnızca transferden önce send() algoritması çağrılmadıysa aktarılabilmesidir.

Aktarım-alma adımları sırasında temel veri taşıması kapalıysa, RTCDataChannel nesnesi, aktarım-alma adımlarından hemen sonra bir veri kanalını kapalı olarak duyurma algoritması çalıştırılarak kapatılacaktır.

6.2.7 Veri kanalı oluşturma sırasında hata

Bazı durumlarda kullanıcı aracısı, bir RTCDataChannel’ın temel veri taşımasını oluşturamayabilir. Örneğin, veri kanalının id değeri, SCTP el sıkışması sırasında [RFC8831] uygulamaları tarafından müzakere edilen aralığın dışında olabilir. Kullanıcı aracısı, bir RTCDataChannel’ın temel veri taşımasının oluşturulamayacağını belirlediğinde, kullanıcı aracısı MUST aşağıdaki adımları çalıştırmak üzere bir görev sıraya almalıdır:

1. Kullanıcı aracısının temel veri taşımasını oluşturamadığı RTCDataChannel nesnesi channel olsun.
2. channel.[[ReadyState]] değerini "closed" olarak ayarlayın.
3. channel üzerinde errorDetail özniteliği "data-channel-failure" olarak ayarlanmış şekilde RTCErrorEvent arayüzünü kullanarak error adlı bir olay tetikleyin.
4. channel üzerinde close adlı bir olay tetikleyin.

6.2.8 Bir veri kanalında mesaj alma

Bir RTCDataChannel mesajı, type türü ve rawData verisiyle temel veri taşıması üzerinden alındığında, kullanıcı aracısı MUST aşağıdaki adımları çalıştırmak üzere bir görev sıraya almalıdır:

1. Kullanıcı aracısının bir mesaj aldığı RTCDataChannel nesnesi channel olsun.
2. channel ile ilişkili RTCPeerConnection nesnesi connection olsun.
3. channel.[[ReadyState]] "open" değilse, bu adımları sonlandırın ve rawData’yı atın.
4. type ve channel.binaryType üzerinden anahtarlama yaparak alt adımı yürütün:

• type, rawData’nın bir string olduğunu gösteriyorsa:

rawData’nın UTF-8 olarak çözümlenmesinin sonucunu temsil eden bir DOMString olan datayı tanımlayın.

• type, rawData’nın ikili olduğunu ve binaryType’ın "blob" olduğunu gösteriyorsa:

Ham veri kaynağı olarak rawData’yı içeren yeni bir Blob nesnesi olan datayı tanımlayın.

• type, rawData’nın ikili olduğunu ve binaryType’ın "arraybuffer" olduğunu gösteriyorsa:

Ham veri kaynağı olarak rawData’yı içeren yeni bir ArrayBuffer nesnesi olan datayı tanımlayın.

1. channel üzerinde, origin özniteliği connection.[[DocumentOrigin]]’in bir kökeninin serileştirilmesi ile başlatılmış ve data özniteliği data ile başlatılmış şekilde MessageEvent arayüzünü kullanarak message adlı bir olay tetikleyin.

WebIDL[Exposed=(Window,DedicatedWorker), Transferable]
                        interface RTCDataChannel : EventTarget {
                          readonly attribute USVString label;
                          readonly attribute boolean ordered;
                          readonly attribute unsigned short? maxPacketLifeTime;
                          readonly attribute unsigned short? maxRetransmits;
                          readonly attribute USVString protocol;
                          readonly attribute boolean negotiated;
                          readonly attribute unsigned short? id;
                          readonly attribute RTCDataChannelState readyState;
                          readonly attribute unsigned long bufferedAmount;
                          [EnforceRange] attribute unsigned long bufferedAmountLowThreshold;
                          attribute EventHandler onopen;
                          attribute EventHandler onbufferedamountlow;
                          attribute EventHandler onerror;
                          attribute EventHandler onclosing;
                          attribute EventHandler onclose;
                          undefined close();
                          attribute EventHandler onmessage;
                          attribute BinaryType binaryType;
                          undefined send(USVString data);
                          undefined send(Blob data);
                          undefined send(ArrayBuffer data);
                          undefined send(ArrayBufferView data);
                        };

Öznitelikler

Yöntemler

close yöntemi çağrıldığında, kullanıcı aracısı aşağıdaki adımları MUST çalıştırmalıdır:

1. Kapatılmak üzere olan RTCDataChannel nesnesi channel olsun.
2. channel.[[ReadyState]] "closing" veya "closed" ise, bu adımları durdur.
3. channel.[[ReadyState]] değerini "closing" olarak ayarla.
4. Kapatma yordamı henüz başlatılmadıysa, başlat.

send() yöntemi, farklı veri argümanı türlerini ele alacak şekilde aşırı yüklenmiştir. Yöntemin herhangi bir sürümü çağrıldığında, kullanıcı aracısı aşağıdaki adımları MUST çalıştırmalıdır:

1. Verinin gönderileceği RTCDataChannel nesnesi channel olsun.
2. channel.[[IsTransferable]] değerini false olarak ayarla.
3. channel.[[ReadyState]] "open" değilse, bir InvalidStateError fırlat.
4. Yöntem argümanının türüne karşılık gelen alt adımı yürüt:

• string nesnesi:

data, yöntem argümanının UTF-8 olarak kodlanmasının sonucu olan bir bayt arabelleği olsun.

• Blob nesnesi:

data, Blob nesnesinin temsil ettiği ham veri olsun.

• ArrayBuffer nesnesi:

data, ArrayBuffer nesnesi tarafından tanımlanan arabellekte saklanan veri olsun.

• ArrayBufferView nesnesi:

data, ArrayBufferView nesnesinin başvurduğu ArrayBuffer nesnesi tarafından tanımlanan arabelleğin bölümünde saklanan veri olsun.

1. data’nın bayt boyutu, channel’ın ilişkili RTCSctpTransport’undaki maxMessageSize değerini aşarsa, bir TypeError fırlat.
2. data’yı channel’ın alttaki veri taşıması üzerinde iletim için kuyruğa al. Yeterli arabellek alanı bulunmadığı için data’yı kuyruğa almak mümkün değilse, bir OperationError fırlat.

1. [[BufferedAmount]] yuvasının değerini data’nın bayt boyutu kadar artır.

WebIDLdictionary RTCDataChannelInit {
                          boolean ordered = true;
                          [EnforceRange] unsigned short maxPacketLifeTime;
                          [EnforceRange] unsigned short maxRetransmits;
                          USVString protocol = "";
                          boolean negotiated = false;
                          [EnforceRange] unsigned short id;
                        };

Sözlük RTCDataChannelInit Üyeleri

id türü unsigned short

negotiated true olduğunda kanal kimliğini ayarlar. negotiated false olduğunda yok sayılır.

WebIDLenum RTCDataChannelState {
                          "connecting",
                          "open",
                          "closing",
                          "closed"
                        };

: RTCDataChannelState Numaralandırmasının açıklaması