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

   1 <h1>Network Communications</h1>
   2
   3 <p>
   4 Chrome Apps can act as a network client
   5 for TCP and UDP connections.
   6 This doc shows you how to use TCP and UDP
   7 to send and receive data over the network.
   8 For more information,
   9 see the
  10 <a href="sockets_udp">Sockets UDP</a>,
  11 <a href="sockets_tcp">Sockets TCP</a> and
  12 <a href="sockets_tcp_server">Sockets TCP Server</a> APIs.
  13 </p>
  14
  15 <p class="note">
  16 <b>Note: </b>The previous version of the networking APIs ($(ref:socket)) has been
  17 deprecated.
  18 </p>
  19 <p></p>
  20 <p class="note">
  21 <b>API Samples: </b>
  22 Want to play with the code?
  23 Check out the
  24 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/telnet">telnet</a>
  25 and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/udp">udp</a> samples.
  26 </p>
  27
  28 <h2 id="manifest">Manifest requirements</h2>
  29
  30 <p>
  31 For Chrome Apps that use TCP or UDP,
  32 add the <a href="manifest/sockets">sockets</a> entry to the manifest
  33 and specify the IP end point permission rules.
  34 For example:
  35 </p>
  36
  37 <pre data-filename="manifest.json">
  38 "sockets": {
  39     "udp": {
  40       "send": ["host-pattern1", ...],
  41       "bind": ["host-pattern2", ...],
  42       ...
  43     },
  44     "tcp" : {
  45       "connect": ["host-pattern1", ...],
  46       ...
  47     },
  48     "tcpServer" : {
  49       "listen": ["host-pattern1", ...],
  50       ...
  51     }
  52   }
  53 </pre>
  54
  55 <p>
  56 The syntax of socket "host-pattern" entries follows these rules:
  57 </p>
  58
  59 <pre>
  60 &lt;host-pattern> := &lt;host> | ':' &lt;port> | &lt;host> ':' &lt;port>
  61 &lt;host> := '*' | '*.' &lt;anychar except '/' and '*'>+
  62 &lt;port> := '*' | &lt;port number between 1 and 65535>)
  63 </pre>
  64
  65 <p>
  66 See <a href="manifest/sockets">Sockets Manifest Key</a> for detailed
  67 description of the syntax.
  68 </p>
  69
  70 <p>
  71 Examples of socket manifest entries:
  72 </p>
  73
  74 <ul>
  75   <li><code>{ "tcp": { "connect" : "*:23" } }</code> &ndash; connecting on
  76    port 23 of any hosts</li>
  77   <li><code>{ "tcp": { "connect" : ["*:23", "*:80"] } }</code> &ndash;
  78    connecting on port 23 or 80 of any hosts</li>
  79   <li><code>{ "tcp": { "connect" : "www.example.com:23" } }</code> &ndash;
  80    connecting port 23 of <em>www.example.com</em></li>
  81   <li><code>{ "tcp": { "connect" : "" } }</code> &ndash; connecting any ports
  82    of any hosts</li>
  83   <li><code>{ "udp": { "send" : ":99" } }</code> &ndash; sending UDP packet
  84    to port 99 of any hosts</li>
  85   <li><code>{ "udp": { "bind" : ":8899" } }</code> &ndash; binding local port
  86    8899 to receive UDP packets</li>
  87   <li><code>{ "tcpServer": { "listen" : ":8080" } }</code> &ndash; TCP
  88    listening on local port 8080</li>
  89 </ul>
  90
  91 <h2 id="tcp">Using TCP</h2>
  92
  93 <p>
  94 Chrome Apps can make connections to any service that supports TCP.
  95 </p>
  96
  97 <h3 id="connecting">Connecting to a socket</h3>
  98
  99 <p>
 100 Here's a sample showing how to connect
 101 ($(ref:sockets.tcp.connect)) to a socket:
 102 </p>
 103
 104 <pre>
 105 chrome.sockets.tcp.create({}, function(createInfo) {
 106   chrome.sockets.tcp.connect(createInfo.socketId,
 107     IP, PORT, onConnectedCallback);
 108 });
 109 </pre>
 110
 111 <p>
 112 Keep a handle to the <code>socketId</code> so that
 113 you can later received and send data
 114 ($(ref:sockets.tcp.send)) to this socket.
 115 </p>
 116
 117 <h3 id="reading">Receiving from and sending to a socket</h3>
 118
 119 <p>
 120 Receiving from ($(ref:sockets.tcp.onReceive)) and sending to a socket uses
 121 ArrayBuffer objects. To learn about ArrayBuffers, check out the overview,
 122 <a href="https://developer.mozilla.org/en-US/docs/JavaScript_typed_arrays">JavaScript typed arrays</a>,
 123 and the tutorial,
 124 <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>.
 125 </p>
 126
 127 <pre>
 128 chrome.sockets.tcp.send(socketId, arrayBuffer, onSentCallback);
 129 </pre>
 130
 131 <pre>
 132 chrome.sockets.tcp.onReceive.addListener(function(info) {
 133   if (info.socketId != socketId)
 134     return;
 135   // info.data is an arrayBuffer.
 136 });
 137 </pre>
 138
 139 <h3 id="disconnecting">Disconnecting from a socket</h3>
 140
 141 <p>Here's how to disconnect ($(ref:sockets.tcp.disconnect)):</p>
 142
 143 <pre>chrome.sockets.tcp.disconnect(socketId);</pre>
 144
 145 <h2 id="udp">Using UDP</h2>
 146
 147 <p>
 148 Chrome Apps can make connections to any service that supports UDP.
 149 </p>
 150
 151 <h3 id="sending">Sending data</h3>
 152
 153 <p>
 154 Here's a sample showing how to send data ($(ref:sockets.udp.send))
 155 over the network using UDP:
 156 </p>
 157
 158 <pre>
 159 // Create the Socket
 160 chrome.sockets.udp.create({}, function(socketInfo) {
 161   // The socket is created, now we can send some data
 162   var socketId = socketInfo.socketId;
 163   chrome.sockets.udp.send(socketId, arrayBuffer,
 164     '127.0.0.1', 1337, function(sendInfo) {
 165       console.log("sent " + sendInfo.bytesSent);
 166   });
 167 });
 168 </pre>
 169
 170 <h3 id="receiving">Receiving data</h3>
 171
 172 <p>
 173 This example is very similar to the 'Sending data' example, except we
 174 setup an event handler for receiving data.
 175 </p>
 176
 177 <pre>
 178 var socketId;
 179
 180 // Handle the "onReceive" event.
 181 var onReceive = function(info) {
 182   if (info.socketId !== socketId)
 183     return;
 184   console.log(info.data);
 185 };
 186
 187 // Create the Socket
 188 chrome.sockets.udp.create({}, function(socketInfo) {
 189   socketId = socketInfo.socketId;
 190   // Setup event handler and bind socket.
 191   chrome.sockets.udp.onReceive.addListener(onReceive);
 192   chrome.sockets.udp.bind(socketId,
 193     "0.0.0.0", 0, function(result) {
 194       if (result < 0) {
 195         console.log("Error binding socket.");
 196         return;
 197       }
 198       chrome.sockets.udp.send(socketId, arrayBuffer,
 199         '127.0.0.1', 1337, function(sendInfo) {
 200           console.log("sent " + sendInfo.bytesSent);
 201       });
 202   });
 203 });
 204 </pre>
 205
 206 <h2 id="tcpServer">Using TCP Server</h2>
 207
 208 <p>
 209 Chrome Apps can act as TCP servers using the $(ref:sockets.tcpServer) API.
 210 </p>
 211
 212 <h3 id="creating-server">Creating a TCP server socket</h3>
 213
 214 <p>
 215 Create a TCP server socket with $(ref:sockets.tcpServer.create).
 216 </p>
 217
 218 <pre>
 219 chrome.sockets.tcpServer.create({}, function(createInfo) {
 220   listenAndAccept(createInfo.socketId);
 221 });
 222 </pre>
 223
 224 <h3 id="accepting">Accepting client connections</h3>
 225
 226 <p>
 227 Here's a sample showing how to accept connections
 228 ($(ref:sockets.tcpServer.listen)) on a TCP server socket:
 229 </p>
 230
 231 <pre>
 232 function listenAndAccept(socketId) {
 233   chrome.sockets.tcp.listen(socketId,
 234     IP, PORT, function(resultCode) {
 235       onListenCallback(socketId, resultCode)
 236   });
 237 }
 238 </pre>
 239
 240 <p>
 241 Keep a handle to the <code>socketId</code> so that
 242 you can later accept new connections
 243 ($(ref:sockets.tcpServer.onAccept)) .
 244 </p>
 245
 246 <pre>
 247 var serverSocketId;
 248 function onListenCallback(socketId, resultCode) {
 249   if (resultCode < 0) {
 250     console.log("Error listening:" +
 251       chrome.runtime.lastError.message);
 252     return;
 253   }
 254   serverSocketId = socketId;
 255   chrome.sockets.tcpServer.onAccept.addListener(onAccept)
 256 }
 257 </pre>
 258
 259 <p>
 260 When a new connection is established, <code>onAccept</code> is invoked with
 261 the <code>clientSocketId</code> of the new TCP connection. The client socket ID
 262 must be used with the $(ref:sockets.tcp) API.
 263 The socket of the new connection is paused by default. Un-pause it with
 264 $(ref:sockets.tcp.setPaused) to start receiving data.
 265 </p>
 266
 267 <pre>
 268 function onAccept(info) {
 269   if (info.socketId != serverSocketId)
 270     return;
 271
 272   // A new TCP connection has been established.
 273   chrome.sockets.tcp.send(info.clientSocketId, data,
 274     function(resultCode) {
 275       console.log("Data sent to new TCP client connection.")
 276   });
 277   // Start receiving data.
 278   chrome.sockets.tcp.onReceive(info.clientSocketId, onReceive);
 279   chrome.sockets.tco.setPaused(false);
 280 }
 281 </pre>
 282
 283 <h3 id="stop-accepting">Stop accepting client connections</h3>
 284
 285 <p>
 286 Call $(ref:sockets.tcp.disconnect) on the server socket ID to stop accepting
 287 new connections.
 288 </p>
 289
 290 <pre>
 291 chrome.sockets.tcpServer.onAccept.removeListener(onAccept);
 292 chrome.sockets.tcpServer.disconnect(serverSocketId);</pre>
 293
 294
 295 <p class="backtotop"><a href="#top">Back to top</a></p>