Como conectar-se com um StreamWebSocket (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Este tópico mostrará como enviar e receber fluxos de dados usando StreamWebSocket em um aplicativo do Tempo de Execução do Windows.

A classe StreamWebSocket fornece uma abstração com base no fluxo do protocolo WebSocket baseado na mensagem. Isso é útil para cenários em que grandes arquivos (como fotos ou filmes) precisam ser transferidos entre um cliente e o servidor. O servidor deve oferecer suporte para o protocolo WebSocket. O uso de StreamWebSocket permite que seções de uma mensagem sejam lidas com cada operação de leitura, em vez de ser necessário uma única operação para ler a mensagem inteira (assim como com MessageWebSocket).

A classe StreamWebSocket oferece suporte para mensagens binárias somente. Para mensagens UTF-8, o MessageWebSocket deve ser usado.

Pré-requisitos

Os exemplos a seguir usam JavaScript e são baseados no exemplo de WebSocket. Para obter instruções sobre a criação de um aplicativo do Tempo de Execução do Windows em JavaScript, veja Criar seu primeiro aplicativo do Tempo de Execução do Windows em JavaScript. Além disso, as promessas de JavaScript são usadas neste tópico para concluir as operações assíncronas. Para obter mais informações sobre esse padrão de programação, consulte Programação assíncrona em JavaScript usando promessas.

Para garantir que o aplicativo do Tempo de Execução do Windows esteja pronto para a rede, defina alguns recursos de rede no arquivo Package.appxmanifest do projeto. Se o aplicativo precisa ser capaz de se conectar como um cliente aos serviços remotos na Internet, a capacidade de Internet (Cliente) é necessária. Se o aplicativo precisa ser capaz de se conectar como cliente aos serviços remotos na rede doméstica ou na rede comercial, então a capacidade Rede Doméstica/Comercial é necessária.

Observação No Windows Phone, há somente um recurso de rede (Internet (Cliente e Servidor)) que habilita todo o acesso de rede para o aplicativo.

Para obter mais informações, veja Como definir recursos de rede.

Instruções

1. Criar um objeto StreamWebSocket para enviar e receber dados

O código nesta seção cria um novo StreamWebSocket, conecta-se a um servidor WebSocket, envia dados para o servidor e escuta respostas.

Primeiro validamos se o URI do servidor usado é válido. Em seguida, conectamos ao servidor WebSocket, usando o URI e aguardamos para receber a resposta do servidor.

Primeiro, o endereço de URI de entrada é verificado para garantir que o usuário tenha passado um endereço de URI válido. Esta etapa não é necessária se o aplicativo já conhecer o URI do servidor WebSocket.

Uma exceção é gerada quando uma cadeia de caracteres inválida do URI (Uniform Resource Identifier) é passada ao construtor para o objeto Windows.Foundation.Uri.

No JavaScript, não há nenhum método para tentar analisar uma cadeia de caracteres para um URI. Para pegar essa exceção nesse caso, use um bloco try/catch em torno do código onde o URI foi construído.

O exemplo também verifica se o esquema HTTP no URI é WS ou WSS, pois esses são os únicos esquemas com suporte em um StreamWebSocket.

Se tivermos um URI válido da entrada do usuário, o aplicativo conecta-se ao servidor WebSocket e pode enviar e receber dados.

Exceções devido a erros de rede (perda de conectividade, falhas de conexão e falhas do servidor HTTP, por exemplo) podem acontecer a qualquer momento. Esses erros geram as exceções. Quando não é resolvida pelo aplicativo, a exceção pode fazer seu aplicativo inteiro ser terminado pelo tempo de execução. É necessário escrever um código para tratar exceções quando você chama a maioria dos métodos de rede assíncronos. Às vezes, quando acontece uma exceção, um método de rede pode ser repetido para tentar resolver o problema. Outras vezes, o aplicativo tem de se planejar para continuar sem conectividade de rede, usando os dados que já foram armazenados em cache. Para saber mais sobre como tratar exceções de rede, veja Resolvendo exceções em aplicativos de rede.

Observação Você pode querer exibir mensagens para o usuário ou escrever para registrar que determinados eventos ocorreram (por exemplo, quando uma conexão é efetuada ou quando um erro ocorre). O exemplo chama uma função displayStatus que você precisaria implementar em seu aplicativo.

Observação As funções writeOutgoing() e readIncoming() para realizar operações de gravação e leitura serão definidas em etapas subsequentes.

Abra a pasta js. Abra o arquivo .js que você está usando e adicione o código a seguir.


// Define some variables we will use
var streamWebSocket;
var dataWriter;
var dataReader;
// The data to send
var data = "Hello World";
var countOfDataSent;
var countOfDataReceived;

function start() {
   if (streamWebSocket) {
      // The WebSocket is already running. Go ahead and immediately return,  
      // or display a message that indicates that it is running.
      return;
   }

   var webSocket = new Windows.Networking.Sockets.StreamWebSocket();
   webSocket.onclosed = onClosed;

   // WebSocket server to test connections
   // If the scheme is wss:, then the server will
   // echo back what it receives
   var uriString = "wss://echo.websocket.org";

   // We might get the uriString from the user so
   // we need to check that we have a valid URI
   var serverUri;
   try {
      serverUri = new Windows.Foundation.Uri(uriString);
      }
   catch (Exception) {
      displayStatus("Invalid URI, please re-enter a valid URI.");
      return;
   }

   if (serverUri.schemeName != "ws" && serverUri.schemeName != "wss") {
      displayStatus("Only 'ws' and 'wss' schemes supported. Please re-enter URI");
      return;
   }

   // Asynchronous networking methods can throw execptions
   webSocket.connectAsync(uri).done(function () {
      diaplayStatus("Connected");

      streamWebSocket = webSocket;
      dataWriter = new Windows.Storage.Streams.DataWriter(webSocket.outputStream);
      dataReader = new Windows.Storage.Streams.DataReader(webSocket.inputStream);
      // When buffering, return as soon as any data is available.
      dataReader.inputStreamOptions = Windows.Storage.Streams.InputStreamOptions.partial;
      countOfDataSent = 0;
      countOfDataReceived = 0;

      // Continuously send data to the server
      writeOutgoing();

      // Continuously listen for a response
      readIncoming();

   }, function (error) {
      var errorStatus = Windows.Networking.Sockets.WebSocketError.getStatus(error.number);
      if (errorStatus === Windows.Web.WebErrorStatus.cannotConnect ||
         errorStatus === Windows.Web.WebErrorStatus.notFound ||
         errorStatus === Windows.Web.WebErrorStatus.requestTimeout) {
         displayStatus("Cannot connect to the server");
      } else {
         displayStatus("Failed to connect: " + getError(error));
      }
   });
}

2. Enviar dados de saída

O código nesta seção permite que seu objeto WebSocket envie dados para um servidor.

Observação A função writeError() será definida em uma etapa subsequente.

Adicione o código a seguir ao seu arquivo .js para definir a função writeOutgoing().

function writeOutgoing() {
   try {
      var size = dataWriter.measureString(data);
      countOfDataSent += size;

      dataWriter.writeString(data);
      dataWriter.storeAsync().done(function () {
         // Add a 1 second delay so the user can see what's going on.
         setTimeout(writeOutgoing, 1000);
      }, writeError);
   }
   catch (error) {
      displayStatus("Sync write error: " + getError(error));
   }
}

3. Ler dados de entrada

O código nesta seção permite que seu objeto WebSocket leia dados de um servidor.

Observação A função readError() será definida em uma etapa subsequente.

Adicione o código a seguir ao seu arquivo .js para definir a função readIncoming().


function readIncoming(args) {
   // Buffer as much data as you require for your protocol.
   dataReader.loadAsync(100).done(function (sizeBytesRead) {
      countOfDataReceived += sizeBytesRead;

      var incomingBytes = new Array(sizeBytesRead);
      dataReader.readBytes(incomingBytes);

      // Do something with the data.
      // Alternatively you can use DataReader to read out individual booleans,
      // ints, strings, etc.

      // Start another read.
      readIncoming();
   }, readError);
}

4. Adicionar o código de tratamento de erros

É necessário escrever um código para tratar exceções quando você chama a maioria dos métodos de rede assíncronos. Seu manipulador de exceção recupera informações mais detalhadas sobre a causa da exceção para entender melhor a falha e tomar as medidas adequadas. Para saber mais, veja Como manipular exceções em aplicativos de rede.

Adicione o código ao seu arquivo .js para definir as funções writeError() e readError() para registrar erros de escrita e leitura (ou tomar outras ações), respectivamente. A implementação específica que você usa pode variar.
```
function writeError(error) {
   // Add your code to handle write errors.
}

function readError(error) {
   // Add your code to handle read errors.
}
```

5. Registrar o seu retorno de chamada para o evento StreamWebSocket.Closed

Quando o evento StreamWebSocket.Closed ocorre, o retorno de chamada registrado é chamado e recebe dados de WebSocketClosedEventArgs para fechar a conexão.

Adicione o código a seguir ao seu arquivo .js.

function onClosed(args) {
   // You can add code to log or display the code and reason
   // for the closure (stored in args.code and args.reason)
   if (streamWebSocket) {
      streamWebSocket.close();
   }
   streamWebSocket = null;
}