API - Genel Bakış

Daha fazla ilerlemeden önce, Socket.IO tarafından sağlanan API'nin kısa bir turunu yapalım:

Ortak API

Aşağıdaki yöntemler, hem istemci hem de sunucu için kullanılabilir.

Temel emit

adım #4'te gördüğümüz gibi, socket.emit() ile diğer tarafa herhangi bir veriyi gönderebilirsiniz:

İstemci

socket.emit('hello', 'world');

Sunucu

io.on('connection', (socket) => {
  socket.on('hello', (arg) => {
    console.log(arg); // 'world'
  });
});

Sunucu

io.on('connection', (socket) => {
  socket.emit('hello', 'world');
});

İstemci

socket.on('hello', (arg) => {
  console.log(arg); // 'world'
});

Herhangi bir sayıdaki argümanları gönderebilirsiniz ve tüm seri hale getirilebilir veri yapıları desteklenmektedir, bunlar arasında ArrayBuffer, TypedArray veya Buffer (sadece Node.js):

İstemci

socket.emit('hello', 1, '2', { 3: '4', 5: Uint8Array.from([6]) });

Sunucu

io.on('connection', (socket) => {
  socket.on('hello', (arg1, arg2, arg3) => {
    console.log(arg1); // 1
    console.log(arg2); // '2'
    console.log(arg3); // { 3: '4', 5: <Buffer 06> }
  });
});

Sunucu

io.on('connection', (socket) => {
  socket.emit('hello', 1, '2', { 3: '4', 5: Buffer.from([6]) });
});

İstemci

socket.on('hello', (arg1, arg2, arg3) => {
  console.log(arg1); // 1
  console.log(arg2); // '2'
  console.log(arg3); // { 3: '4', 5: ArrayBuffer (1) [ 6 ] }
});

ipucu

Nesneler üzerinde JSON.stringify() çağrısı yapmak gerekmez:

// KÖTÜ
socket.emit('hello', JSON.stringify({ name: 'John' }));

// İYİ
socket.emit('hello', { name: 'John' });

Onaylar

Olaylar harika, ancak bazı durumlarda daha klasik bir istek-yanıt API'si isteyebilirsiniz. Socket.IO'da, bu özellik "onaylar" olarak adlandırılır.

İki versiyonu vardır:

Bir geri çağırma işlevi ile

Son argüman olarak emit() fonksiyonuna bir geri çağırma ekleyebilirsiniz ve bu geri çağırma, diğer taraf etkinliği onayladığında çağrılacaktır:

İstemci

socket.timeout(5000).emit('request', { foo: 'bar' }, 'baz', (err, response) => {
  if (err) {
    // sunucu belirlenen süre içinde olayı onaylamadı
  } else {
    console.log(response.status); // 'ok'
  }
});

Sunucu

io.on('connection', (socket) => {
  socket.on('request', (arg1, arg2, callback) => {
    console.log(arg1); // { foo: 'bar' }
    console.log(arg2); // 'baz'
    callback({
      status: 'ok'
    });
  });
});

Sunucu

io.on('connection', (socket) => {
  socket.timeout(5000).emit('request', { foo: 'bar' }, 'baz', (err, response) => {
    if (err) {
      // istemci belirlenen süre içinde olayı onaylamadı
    } else {
      console.log(response.status); // 'ok'
    }
  });
});

İstemci

socket.on('request', (arg1, arg2, callback) => {
  console.log(arg1); // { foo: 'bar' }
  console.log(arg2); // 'baz'
  callback({
    status: 'ok'
  });
});

Bir Promise ile

emitWithAck() yöntemi aynı işlevselliği sağlar, ancak diğer taraf olayı onayladığında çözülecek bir Promise döner:

İstemci

try {
  const response = await socket.timeout(5000).emitWithAck('request', { foo: 'bar' }, 'baz');
  console.log(response.status); // 'ok'
} catch (e) {
  // sunucu belirlenen süre içinde olayı onaylamadı
}

Sunucu

io.on('connection', (socket) => {
  socket.on('request', (arg1, arg2, callback) => {
    console.log(arg1); // { foo: 'bar' }
    console.log(arg2); // 'baz'
    callback({
      status: 'ok'
    });
  });
});

Sunucu

io.on('connection', async (socket) => {
  try {
    const response = await socket.timeout(5000).emitWithAck('request', { foo: 'bar' }, 'baz');
    console.log(response.status); // 'ok'
  } catch (e) {
    // istemci belirlenen süre içinde olayı onaylamadı
  }
});

İstemci

socket.on('request', (arg1, arg2, callback) => {
  console.log(arg1); // { foo: 'bar' }
  console.log(arg2); // 'baz'
  callback({
    status: 'ok'
  });
});

uyarı

Promise'leri desteklemeyen ortamlarda (örneğin Internet Explorer) bir polyfill eklenmesi veya bu özelliği kullanmak için babel gibi bir derleyici kullanılması gerekecektir (ancak bu, bu eğitimin kapsamının dışında).

Tüm olayları dinleyen dinleyiciler

Bir tüm olayları dinleyen dinleyici, gelen her olay için çağrılan bir dinleyicidir. Bu, uygulamanızı debug etmek için kullanışlıdır:

Gönderici

socket.emit('hello', 1, '2', { 3: '4', 5: Uint8Array.from([6]) });

Alıcı

socket.onAny((eventName, ...args) => {
  console.log(eventName); // 'hello'
  console.log(args); // [ 1, '2', { 3: '4', 5: ArrayBuffer (1) [ 6 ] } ]
});

Benzer şekilde, giden paketler için:

socket.onAnyOutgoing((eventName, ...args) => {
  console.log(eventName); // 'hello'
  console.log(args); // [ 1, '2', { 3: '4', 5: ArrayBuffer (1) [ 6 ] } ]
});

Sunucu API'si

Yayınlama

adım #5'te gördüğümüz gibi, io.emit() ile tüm bağlı istemcilere bir olayı yayınlayabilirsiniz:

io.emit('hello', 'world');

Odalar

Socket.IO terminolojisinde, bir oda soketlerin katılabileceği ve çıkabileceği keyfi bir kanaldır. Bağlı istemcilerin bir alt kümesine olay yayınlamak için kullanılabilir:

io.on('connection', (socket) => {
  // 'some room' adlı odaya katıl
  socket.join('some room');
  
  // odaya bağlı tüm istemcilere yayın yap
  io.to('some room').emit('hello', 'world');

  // odaya bağlı olanlar hariç tüm istemcilere yayın yap
  io.except('some room').emit('hello', 'world');

  // odadan çık
  socket.leave('some room');
});

Temel olarak bu kadar! Gelecek için referans olarak, tüm API burada (sunucu) ve burada (istemci) bulunmaktadır.