chrome/common/extensions/docs/templates/articles/app_network.html

<h1>Network Communications</h1>

<p>
Chrome Apps can act as a network client
for TCP and UDP connections.
This doc shows you how to use TCP and UDP
to send and receive data over the network.
For more information,
see the
<a href="sockets_udp.html">Sockets UDP</a>,
<a href="sockets_tcp.html">Sockets TCP</a> and
<a href="sockets_tcp_server.html">Sockets TCP Server</a> APIs.
</p>

<p class="note">
<b>Note: </b>The previous version of the networking APIs ($ref:socket) has been
deprecated.
</p>
<p></p>
<p class="note">
<b>API Samples: </b>
Want to play with the code?
Check out the
<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/telnet">telnet</a>
and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/udp">udp</a> samples.
</p>

<h2 id="manifest">Manifest requirements</h2>

<p>
For Chrome Apps that use TCP or UDP,
add the <a href="manifest/sockets.html">sockets</a> entry to the manifest
and specify the IP end point permission rules.
For example:
</p>

<pre data-filename="manifest.json">
"sockets": {
    "udp": {
      "send": ["host-pattern1", ...],
      "bind": ["host-pattern2", ...],
      ...
    },
    "tcp" : {
      "connect": ["host-pattern1", ...],
      ...
    },
    "tcpServer" : {
      "listen": ["host-pattern1", ...],
      ...
    }
  }
</pre>

<p>
The syntax of socket "host-pattern" entries follows these rules:
</p>

<pre>
&lt;host-pattern> := &lt;host> | ':' &lt;port> | &lt;host> ':' &lt;port>
&lt;host> := '*' | '*.' &lt;anychar except '/' and '*'>+
&lt;port> := '*' | &lt;port number between 1 and 65535>)
</pre>

<p>
See <a href="manifest/sockets.html">Sockets Manifest Key</a> for detailed
description of the syntax.
</p>

<p>
Examples of socket manifest entries:
</p>

<ul>
  <li><code>{ "tcp": { "connect" : "*:23" } }</code> &ndash; connecting on
   port 23 of any hosts</li>
  <li><code>{ "tcp": { "connect" : ["*:23", "*:80"] } }</code> &ndash;
   connecting on port 23 or 80 of any hosts</li>
  <li><code>{ "tcp": { "connect" : "www.example.com:23" } }</code> &ndash;
   connecting port 23 of <em>www.example.com</em></li>
  <li><code>{ "tcp": { "connect" : "" } }</code> &ndash; connecting any ports
   of any hosts</li>
  <li><code>{ "udp": { "send" : ":99" } }</code> &ndash; sending UDP packet
   to port 99 of any hosts</li>
  <li><code>{ "udp": { "bind" : ":8899" } }</code> &ndash; binding local port
   8899 to receive UDP packets</li>
  <li><code>{ "tcpServer": { "listen" : ":8080" } }</code> &ndash; TCP
   listening on local port 8080</li>
</ul>

<h2 id="tcp">Using TCP</h2>

<p>
Chrome Apps can make connections to any service that supports TCP.
</p>

<h3 id="connecting">Connecting to a socket</h3>

<p>
Here's a sample showing how to connect
($ref:sockets.tcp.connect) to a socket:
</p>

<pre>
chrome.sockets.tcp.create({}, function(createInfo) {
  chrome.sockets.tcp.connect(createInfo.socketId,
    IP, PORT, onConnectedCallback);
});
</pre>

<p>
Keep a handle to the <code>socketId</code> so that
you can later received and send data
($ref:sockets.tcp.send) to this socket.
</p>

<h3 id="reading">Receiving from and sending to a socket</h3>

<p>
Receiving from ($ref:sockets.tcp.onReceive) and sending to a socket uses
ArrayBuffer objects. To learn about ArrayBuffers, check out the overview,
<a href="https://developer.mozilla.org/en-US/docs/JavaScript_typed_arrays">JavaScript typed arrays</a>,
and the tutorial,
<a href="http://updates.html5rocks.com/2012/06/How-to-convert-ArrayBuffer-to-and-from-String">How to convert ArrayBuffer to and from String</a>.
</p>

<pre>
chrome.sockets.tcp.send(socketId, arrayBuffer, onSentCallback);
</pre>

<pre>
chrome.sockets.tcp.onReceive.addListener(function(info) {
  if (info.socketId != socketId)
    return;
  // info.data is an arrayBuffer.
});
</pre>

<h3 id="disconnecting">Disconnecting from a socket</h3>

<p>Here's how to disconnect ($ref:sockets.tcp.disconnect):</p>

<pre>chrome.sockets.tcp.disconnect(socketId);</pre>

<h2 id="udp">Using UDP</h2>

<p>
Chrome Apps can make connections to any service that supports UDP.
</p>

<h3 id="sending">Sending data</h3>

<p>
Here's a sample showing how to send data ($ref:sockets.udp.send)
over the network using UDP:
</p>

<pre>
// Create the Socket
chrome.sockets.udp.create({}, function(socketInfo) {
  // The socket is created, now we can send some data
  var socketId = socketInfo.socketId;
  chrome.sockets.udp.send(socketId, arrayBuffer,
    '127.0.0.1', 1337, function(sendInfo) {
      console.log("sent " + sendInfo.bytesSent);
  });
});
</pre>

<h3 id="receiving">Receiving data</h3>

<p>
This example is very similar to the 'Sending data' example, except we
setup an event handler for receiving data.
</p>

<pre>
var socketId;

// Handle the "onReceive" event.
var onReceive = function(info) {
  if (info.socketId !== socketId)
    return;
  console.log(info.data);
};

// Create the Socket
chrome.sockets.udp.create({}, function(socketInfo) {
  socketId = socketInfo.socketId;
  // Setup event handler and bind socket.
  chrome.sockets.udp.onReceive.addListener(onReceive);
  chrome.sockets.udp.bind(socketId,
    "0.0.0.0", 0, function(result) {
      if (result < 0) {
        console.log("Error binding socket.");
        return;
      }
      chrome.sockets.udp.send(socketId, arrayBuffer,
        '127.0.0.1', 1337, function(sendInfo) {
          console.log("sent " + sendInfo.bytesSent);
      });
  });
});
</pre>

<h2 id="tcpServer">Using TCP Server</h2>

<p>
Chrome Apps can act as TCP servers using the $ref:sockets.tcpServer API.
</p>

<h3 id="creating-server">Creating a TCP server socket</h3>

<p>
Create a TCP server socket with $ref:sockets.tcpServer.create.
</p>

<pre>
chrome.sockets.tcpServer.create({}, function(createInfo) {
  listenAndAccept(createInfo.socketId);
});
</pre>

<h3 id="accepting">Accepting client connections</h3>

<p>
Here's a sample showing how to accept connections
($ref:sockets.tcpServer.listen) on a TCP server socket:
</p>

<pre>
function listenAndAccept(socketId) {
  chrome.sockets.tcp.listen(socketId,
    IP, PORT, function(resultCode) {
      onListenCallback(socketId, resultCode)
  });
}
</pre>

<p>
Keep a handle to the <code>socketId</code> so that
you can later accept new connections
($ref:sockets.tcpServer.onAccept) .
</p>

<pre>
var serverSocketId;
function onListenCallback(socketId, resultCode) {
  if (resultCode < 0) {
    console.log("Error listening:" +
      chrome.runtime.lastError.message);
    return;
  }
  serverSocketId = socketId;
  chrome.sockets.tcpServer.onAccept.addListener(onAccept)
}
</pre>

<p>
When a new connection is established, <code>onAccept</code> is invoked with
the <code>clientSocketId</code> of the new TCP connection. The client socket ID
must be used with the $ref:sockets.tcp API.
The socket of the new connection is paused by default. Un-pause it with
$ref:sockets.tcp.setPaused to start receiving data.
</p>

<pre>
function onAccept(info) {
  if (info.socketId != serverSocketId)
    return;

  // A new TCP connection has been established.
  chrome.sockets.tcp.send(info.clientSocketId, data,
    function(resultCode) {
      console.log("Data sent to new TCP client connection.")
  });
  // Start receiving data.
  chrome.sockets.tcp.onReceive(info.clientSocketId, onReceive);
  chrome.sockets.tco.setPaused(false);
}
</pre>

<h3 id="stop-accepting">Stop accepting client connections</h3>

<p>
Call $ref:sockets.tcp.disconnect on the server socket ID to stop accepting
new connections.
</p>

<pre>
chrome.sockets.tcpServer.onAccept.removeListener(onAccept);
chrome.sockets.tcpServer.disconnect(serverSocketId);</pre>


<p class="backtotop"><a href="#top">Back to top</a></p>