Borrador
Esta p谩gina no est谩 completa.
WebSockets es una tecnolog铆a basada en el protocolo ws, este hace posible establecer una conexi贸n continua full-duplex, entre un cliente y servidor. Un cliente websocket podr铆a ser el navegador del usuario, pero el protocolo es una plataforma independiente.
Disponibilidad de WebSockets
La API de WebSocket esta disponible para el c贸digo JavaScript cuyo alcance DOM sea un objeto Window
o cualquier objeto implementando WorkerUtils
; si es as铆, puedes usarlos desde los Web Workers.
Creando un Objeto WebSocket
Para comunicarse utilizando el protocolo webSocket, necesitar谩s crear un objeto WebSocket; este autom谩ticamente abrir谩 una conexi贸n temporal al servidor.
El constructor WebSocket requiere de un par谩metro obligatorio y otro opcional:
WebSocket WebSocket( in DOMString url, in optional DOMString protocols ); WebSocket WebSocket( in DOMString url, in optional DOMString[] protocols );
url
- La url a la que conectar; esta es la URL a la que el WebSocket responde.
protocols
Optional- Un string o array de strings con el/los protocolos a usar. Estos strings son usados para indicar sub-protocolos, para que el servidor pueda implementar multiples sub-protocolos WebSocket (por ejemplo, puede necesitar usar un servidor para manejar diferentes tipos de interacciones dependiendo del protocolo especificado). Si no se especifica el string como protocolo, se asumir谩 un string vac铆o.
El constructor puede lanzar excepciones:
SECURITY_ERR
- El puerto de la conexi贸n est谩 siendo bloqueado.
Errores de conexi贸n
Si ocurre un error al intentar conectar, lo primero que recibiremos ser谩 un evento con el nombre de "error" en el objeto WebSocket
(de este modo se invoca el manejador onerror
), y luego CloseEvent
es enviado al objeto WebSocket
(de este modo se invoca el manejador onclose
), para indicar la raz贸n del cierre de la conexi贸n.
A partir de Firefox 11, es normal recibir un mensaje de error descriptivo en la consola de la plataforma Mozilla, y un c贸digo de cierre como est谩 definido en el RFC 6455, Section 7.4 a trav茅s de un CloseEvent
.
Ejemplos
En este ejemplo de crea un nuevo WebSocket, conectandose al servidor ws://www.example.com/socketserver
. El nombre del protocolo "protocolOne" es el utilizado para la consulta del socket, aunque puede ser omitido.
var exampleSocket = new WebSocket("ws://www.example.com/socketserver", "protocolOne");
Como respuesta, exampleSocket
.readyState
es CONNECTING
. El readyState
ser谩 OPEN
una vez que la conexi贸n este lista para transferir informaci贸n.
Si se quiere establecer una conexi贸n que soporte varios protocolos, se puede establecer un array de protocolos:
var exampleSocket = new WebSocket("ws://www.example.com/socketserver", ["protocolOne", "protocolTwo"]);
Una vez que la conexi贸n este establecida (readyState
estar谩 OPEN
), exampleSocket.protocol
te dir谩 qu茅 protocolo ha seleccionado el servidor.
En los ejemplos anteriores ws
sustituye http
, y de igual manera wss
sustituye a https
. Al crear un WebSocket se hace uso del mecanismo Upgrade de HTTP, por lo que la petici贸n de actualizaci贸n del protocolo est谩 impl铆cita cuando accedemos al servidor HTTP con ws://www.example.com
o wss://www.example.com
.
Enviando Informaci贸n al servidor
Una vez la conexi贸n esta abierta, se puede comenzar a enviar datos al servidor. Para hacer esto, simplemente se llama al metodo send()
del objeto WebSocket
, cada vez que se desea enviar un mensaje:
exampleSocket.send("Here's some text that the server is urgently awaiting!");
Puedes enviar informaci贸n como un string, Blob
, o en un ArrayBuffer
.
Como la conexi贸n es asincronica y es propensa a fallar, no hay garantia de poder llamar al metodo send()
inmediatamente desp煤es de haber creado el objeto WebSocket de manera exitosa. Para enviar informaci贸n se debe estar seguro de que almenos una conexi贸n ya esta abierta, usando el manejador onopen
:
exampleSocket.onopen = function (event) {
exampleSocket.send("Here's some text that the server is urgently awaiting!");
};
Usando JSON para transferir Objetos
Una forma de enviar informaci贸n compleja al servidor es utilizar JSON. Por ejemplo, un programa para chatear puede interactuar con el servidor usando un protocolo que implementa el uso de paquetes de JSON:
// Envia texto a todos los usuarios atrav茅s del servidor
function sendText() {
// Se construye un Objeto msg que contiene la informaci贸n que el servidor necesita procesar de ese cliente.
var msg = {
type: "message",
text: document.getElementById("text").value,
id: clientID,
date: Date.now()
};
// Send the msg object as a JSON-formatted string.
exampleSocket.send(JSON.stringify(msg));
// Blank the text input element, ready to receive the next line of text from the user.
document.getElementById("text").value = "";
}
Recibiendo mensajes del servidor
WebSockets API es un manejador de eventos; cuando el mensaje es recibido, un "message" el evento es pasado el manejador onmessage
. Para escuchar la entrada de informaci贸n, se puede hacer algo como lo siguiente:
exampleSocket.onmessage = function (event) {
console.log(event.data);
}
Recibiendo e interpretando objetos JSON
Vamos a imaginar una aplicaci贸n de chat, donde el cliente usa JSON para transmitir objetos con informaci贸n. Hay varios tipos de paquetes que el cliente recibir谩:
- Inicio de sesi贸n handshake
- Mensajes de texto
- Actualizaci贸n de Lista de usuarios
El c贸digo que interpretar谩 los mensajes entrantes ser谩 as铆:
exampleSocket.onmessage = function(event) {
var f = document.getElementById("chatbox").contentDocument;
var text = "";
var msg = JSON.parse(event.data);
var time = new Date(msg.date);
var timeStr = time.toLocaleTimeString();
switch(msg.type) {
case "id":
clientID = msg.id;
setUsername();
break;
case "username":
text = "<b>User <em>" + msg.name + "</em> signed in at " + timeStr + "</b><br>";
break;
case "message":
text = "(" + timeStr + ") <b>" + msg.name + "</b>: " + msg.text + "<br>";
break;
case "rejectusername":
text = "<b>Your username has been set to <em>" + msg.name + "</em> because the name you chose is in use.</b><br>"
break;
case "userlist":
var ul = "";
for (i=0; i < msg.users.length; i++) {
ul += msg.users[i] + "<br>";
}
document.getElementById("userlistbox").innerHTML = ul;
break;
}
if (text.length) {
f.write(text);
document.getElementById("chatbox").contentWindow.scrollByPages(1);
}
};
Se usa JSON.parse()
para convertir el objeto JSON de vuelta al original, luego se examina y se realiza la acci贸n pertinente.
Formato de texto de los datos
El texto recibido a trav茅s de la conexi贸n WebSocket est谩 en formato UTF-8.
Antes de Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6), algunos no-caracteres que siguen siendo texto UTF-8 v谩lido podr铆an causar el cierre de la conexi贸n. Ahora Gecko permite esos valores.
Cerrando la conexi贸n
Cuando se ha terminado de usar la conexi贸n WebSocket, se llama el m茅todo close()
del objeto WebSocket
:
exampleSocket.close();
Puede ser de gran ayuda revisar el atributo bufferedAmount
del socket para verificar que toda la informaci贸n ha sido enviada antes de intentar cerrar el socket.
Consideraciones de Seguridad
Los WebSockets no deben ser usados en entornos de contenido mixto; eso es, no debes abrir una conexi贸n de WebSocket no segura desde una p谩gina cargada usando HTTPS o viceversa. De hecho, muchos navegadores solo admiten conexiones WebSocket seguras, y ya no soportan su uso en contextos no seguros.