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

<h1>Network Communications</h1>

<p>
Packaged 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="socket.html">Sockets API</a>.
</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 packaged apps that use TCP or UDP,
add the "socket" permission to the manifest
and specify the IP end point permission rules.
For example:
</p>

<pre>
"permissions": [
    {"socket": [
      "rule1",
      "rule2",
      ...
    ]}
  ]
</pre>

<p>
The syntax of socket permission rules follows these patterns:
</p>

<pre>
&lt;socket-permission-rule>
     := &lt;op> | &lt;op> ':' &lt;host> | &lt;op> ':' ':' &lt;port> |
        &lt;op> ':' &lt;host> ':' &lt;port>
 &lt;op> := 'tcp-connect' | 'tcp-listen' | 'udp-bind' | 'udp-send-to'
 &lt;host> := '*' | '*.' &lt;anychar except '/' and '*'>+
 &lt;port> := '*' | &lt;port number between 1 and 65535>)
</pre>

<p>
Examples of socket permission rules:
</p>

<ul>
  <li>"tcp-connect:*:23" &ndash; connecting on port 23 of any hosts</li>
  <li>"tcp-connect:www.example.com:23" &ndash; connecting port 23 of <em>www.example.com</em></li>
  <li>"tcp-connect" &ndash; connecting any ports of any hosts</li>
  <li>"udp-send-to::99" &ndash; sending UDP packet to port 99 of any hosts</li>
  <li>"udp-bind::8899" &ndash; binding local port 8899 to receive UDP package</li>
  <li>"tcp-listen::8080" &ndash; TCP listening on local port 8080</li>
</ul>

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

<p>
Packaged apps can make connections to any service that supports TCP.
</p>

<h3>Connecting to a socket</h3>

<p>
Here's a sample showing how to connect to a socket:
</p>

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

<p>
Keep a handle to the socketId so that
you can later read and write to this socket.
</p>

<pre>
chrome.socket.write(socketId, arrayBuffer, onWriteCompleteCallback);
</pre>

<h3>Reading to & writing from a socket</h3>

<p>
Reading and writing from a socket uses ArrayBuffer objects.
</p>

<pre>
chrome.socket.read(socketId, null, function(readInfo) {
  if (readInfo.resultCode > 0) {
    // readInfo.data is an arrayBuffer.
  }
});
</pre>

<h3>Disconnecting from a socket</h3>

<p>Here's how to disconnect:</p>

<pre>chrome.socket.disconnect(socketId);</pre>

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

<p>
Packaged apps can make connections to any service that supports UDP.
</p>

<h3>Sending data</h3>

<p>
Here's a sample showing how to send data
over the network using UDP:
</p>

<pre>
// Create the Socket
chrome.socket.create('udp', '127.0.0.1', 1337, {},
 function(socketInfo) {
   // The socket is created, now we want to connect to the service
   var socketId = socketInfo.socketId;
   chrome.socket.connect(socketId, function(result) {
     // We are now connected to the socket so send it some data
     chrome.socket.write(socketId, arrayBuffer,
       function(sendInfo) {
         console.log("wrote " + sendInfo.bytesWritten);
       }
     );
   });
 }
);
</pre>

<h3>Receiving data</h3>

<p>
This example is very similar to the 'Sending data' example
with the addition of a special handler in the 'create' method.
The parameter is an object with one value 'onEvent'
that is a function reference to the method
that will be called when data is available on the port.
</p>

<pre>
// Handle the data response
var handleDataEvent = function(d) {
  var data = chrome.socket.read(d.socketId);
  console.log(data);
};

// Create the Socket
chrome.socket.create('udp', '127.0.0.1', 1337, { onEvent: handleDataEvent },
 function(socketInfo) {
   // The socket is created, now we want to connect to the service
   var socketId = socketInfo.socketId;
   chrome.socket.connect(socketId, function(result) {
     // We are now connected to the socket so send it some data
     chrome.socket.write(socketId, arrayBuffer,
       function(sendInfo) {
         console.log("wrote " + sendInfo.bytesWritten);
       }
     );
   });
 }
);
</pre>

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