API TCP Socket

Résumé

L'API TCPSocket se propose d'ouvrir et d'utiliser une connexion TCP. Cela permet de mettre en œuvre des protocoles de la couche supérieure à TCP comme IMAP, IRC, POP, HTTP, etc., ou même d'en créer de nouveaux pour des besoins spécifiques.

Permission

Pour utiliser cette API, comme pour toutes les API privilégiées, il est nécessaire de demander l'autorisation de l'utiliser dans l'application app manifeste.

"permissions" : {
  "tcp-socket" : {
    "description" : "Create TCP sockets and communicate over them."
  }
}

Aperçu

Cette API est disponible à travers la propriété mozTCPSocket qui est elle-même un objet TCPSocket.

Ouverture d'un socket

L'ouverture d'un socket est fait avec la méthode TCPSocket.open(). Cette méthode peut avoir jusqu'à trois paramètres:

1. Une chaîne représentant le nom du serveur auquel se connecter (il peut aussi être son adresse IP brute).
2. Un nombre représentant le port TCP à utiliser par la socket (certains protocoles ont un port standard, par exemple 80 pour HTTP, 447 pour SSL, 25 pour SMTP, etc. Les numéros de port au-delà de 1024 ne sont pas assignés à un protocole spécifique et peuvent être utilisés pour d'autres fins.)
3. Un objet optionnel contenant jusqu'à deux paramétres : un booléen nommé useSecureTransport, false par défaut, est nécessaire pour utiliser SSL, ; et une chaîne nommée binaryType permet d'indiquer le type de données récupérées par l'application à travers l'événement data, avec les valeurs attendues string par défaut ou arraybuffer.

var socket = navigator.mozTCPSocket.open('localhost', 80);

Ecoute des connexions

L'écoute des connexions se fait avec les méthodes TCPSocket.listen() et Nécessite FirefoxOS 1.2 . Cette méthode prévoit jusqu'à trois paramètres:

1. Un nombre représentant le port TCP à utiliser pour écouter les connexions.
2. Un objet facultatif spécifiant les détails de la réception. Cet objet attend une propriété appelée binaryType, qui est une chaîne qui peut avoir deux valeurs possibles: "string" ou "ArrayBuffer". Si la valeur est "ArrayBuffer" alors le TCPSocket.send() utilise ArrayBuffer et les données reçues seront également disponible dans ce format.
3. Un nombre représentant la longueur maximale de la file d'attente des connexions en attente.

var socket = navigator.mozTCPSocket.listen(8080);

Envoi de données

L'envoi de données se fait en utilisant la méthode TCPSocket.send(). Les données envoyées peuvent au format chaîne ou Uint8Array; Cependant, rappelez-vous qu'un socket TCP travail avec les données binaires. Pour cette raison, il est beaucoup plus sûr d'utiliser Uint8Array à la place d'une chaîne lors de l'envoi des données.

Pout protocole TCP, il vaut mieux envoyer 64 Ko maximum de données en même temps. Quand moins de 64kb ont été tamponnés, un appel à la méthode send retourne true. Si le tampon est plein, la méthode renverra false pour indiquer que l'application devra faire une pause pour vider le tampon. Chaque fois que le tampon est vidé, un événement drain est déclenché et l'application peut reprendre envoi de données.

Il est possible de connaître exactement la quantité de données en mémoire tampon avec la propriété TCPSocket.bufferedAmount .

function getData() {
  var data;

  // récupérer les données 

  return data;
}

function pushData() {
  var data;

  do {
    data = getData();
  } while (data != null && socket.send(data));
}

// Chaque fois que le tampon est vidé 
// Nous essayons à nouveau d'envoyer des données. 
socket.ondrain = pushData;

// Lancer l'envoi de données. 
pushData();

Recevoir les données

Chaque fois que le socket reçoit des données de l'hôte, il déclenche un événement data. Cet événement donnera accès aux données du socket. Le type de données dépend de l'ensemble des options définies lorsque le socket a été ouvert (voir ci-dessus).

socket.ondata = function (event) {
  if (typeof event.data === 'string') {
    console.log('Get a string: ' + event.data);
  } else {
    console.log('Get a Uint8Array');
  }
}

Comme l'événement data est déclenché autant que nécessaire, il peut parfois être nécessaire d'interrompre le flux de données entrants. À cette fin, l'appel de la méthode TCPSocket.suspend() mettra en pause la lecture des données entrantes et cessera le déclenchement de data. Il est possible de recommencer la lecture des données en appelant la méthode TCPSocket.resume() .

Fermeture d'un socket

La fermeture d'un socket se fait simplement en utilisant TCPSocket.close().

Standard

Ne fait partie d'aucune spécification; Toutefois, cette API est discuté au sein du W3C dans le cadre du groupe de travail Applications Système sous la dénomination de RAW sockets.

Voir aussi

• TCPSocket
• Firefox OS Simple Telnet Sample App