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="socket.html">Sockets API</a>.
  11 </p>
  12
  13 <p class="note">
  14 <b>API Samples: </b>
  15 Want to play with the code?
  16 Check out the
  17 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/telnet">telnet</a>
  18 and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/udp">udp</a> samples.
  19 </p>
  20
  21 <h2 id="manifest">Manifest requirements</h2>
  22
  23 <p>
  24 For Chrome Apps that use TCP or UDP,
  25 add the "socket" permission to the manifest
  26 and specify the IP end point permission rules.
  27 For example:
  28 </p>
  29
  30 <pre data-filename="manifest.json">
  31 "permissions": [
  32     {"socket": [
  33       "rule1",
  34       "rule2",
  35       ...
  36     ]}
  37   ]
  38 </pre>
  39
  40 <p>
  41 The syntax of socket permission rules follows these patterns:
  42 </p>
  43
  44 <pre>
  45 &lt;socket-permission-rule>
  46      := &lt;op> | &lt;op> ':' &lt;host> | &lt;op> ':' ':' &lt;port> |
  47         &lt;op> ':' &lt;host> ':' &lt;port>
  48  &lt;op> := 'tcp-connect' | 'tcp-listen' | 'udp-bind' | 'udp-send-to'
  49  &lt;host> := '*' | '*.' &lt;anychar except '/' and '*'>+
  50  &lt;port> := '*' | &lt;port number between 1 and 65535>)
  51 </pre>
  52
  53 <p>
  54 Examples of socket permission rules:
  55 </p>
  56
  57 <ul>
  58   <li>"tcp-connect:*:23" &ndash; connecting on port 23 of any hosts</li>
  59   <li>"tcp-connect:www.example.com:23" &ndash; connecting port 23 of <em>www.example.com</em></li>
  60   <li>"tcp-connect" &ndash; connecting any ports of any hosts</li>
  61   <li>"udp-send-to::99" &ndash; sending UDP packet to port 99 of any hosts</li>
  62   <li>"udp-bind::8899" &ndash; binding local port 8899 to receive UDP package</li>
  63   <li>"tcp-listen::8080" &ndash; TCP listening on local port 8080</li>
  64 </ul>
  65
  66 <h2 id="tcp">Using TCP</h2>
  67
  68 <p>
  69 Chrome Apps can make connections to any service that supports TCP.
  70 </p>
  71
  72 <h3 id="connecting">Connecting to a socket</h3>
  73
  74 <p>
  75 Here's a sample showing how to connect
  76 ($ref:socket.connect) to a socket:
  77 </p>
  78
  79 <pre>
  80 chrome.socket.create('tcp', {}, function(createInfo) {
  81   chrome.socket.connect(createInfo.socketId, IP, PORT, onConnectedCallback);
  82 });
  83 </pre>
  84
  85 <p>
  86 Keep a handle to the socketId so that
  87 you can later read and write
  88 ($ref:socket.write) to this socket.
  89 </p>
  90
  91 <pre>
  92 chrome.socket.write(socketId, arrayBuffer, onWriteCompleteCallback);
  93 </pre>
  94
  95 <h3 id="reading">Reading to & writing from a socket</h3>
  96
  97 <p>
  98 Reading ($ref:socket.read) and writing from a socket uses ArrayBuffer objects.
  99 To learn about ArrayBuffers,
 100 check out the overview,
 101 <a href="https://developer.mozilla.org/en-US/docs/JavaScript_typed_arrays">JavaScript typed arrays</a>,
 102 and the tutorial,
 103 <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>.
 104 </p>
 105
 106 <pre>
 107 chrome.socket.read(socketId, null, function(readInfo) {
 108   if (readInfo.resultCode > 0) {
 109     // readInfo.data is an arrayBuffer.
 110   }
 111 });
 112 </pre>
 113
 114 <h3 id="disconnecting">Disconnecting from a socket</h3>
 115
 116 <p>Here's how to disconnect ($ref:socket.disconnect):</p>
 117
 118 <pre>chrome.socket.disconnect(socketId);</pre>
 119
 120 <h2 id="udp">Using UDP</h2>
 121
 122 <p>
 123 Chrome Apps can make connections to any service that supports UDP.
 124 </p>
 125
 126 <h3 id="sending">Sending data</h3>
 127
 128 <p>
 129 Here's a sample showing how to send data
 130 over the network using UDP:
 131 </p>
 132
 133 <pre>
 134 // Create the Socket
 135 chrome.socket.create('udp', '127.0.0.1', 1337, {},
 136  function(socketInfo) {
 137    // The socket is created, now we want to connect to the service
 138    var socketId = socketInfo.socketId;
 139    chrome.socket.connect(socketId, function(result) {
 140      // We are now connected to the socket so send it some data
 141      chrome.socket.write(socketId, arrayBuffer,
 142        function(sendInfo) {
 143          console.log("wrote " + sendInfo.bytesWritten);
 144        }
 145      );
 146    });
 147  }
 148 );
 149 </pre>
 150
 151 <h3 id="receiving">Receiving data</h3>
 152
 153 <p>
 154 This example is very similar to the 'Sending data' example
 155 with the addition of a special handler in the 'create' method.
 156 The parameter is an object with one value 'onEvent'
 157 that is a function reference to the method
 158 that will be called when data is available on the port.
 159 </p>
 160
 161 <pre>
 162 // Handle the data response
 163 var handleDataEvent = function(d) {
 164   var data = chrome.socket.read(d.socketId);
 165   console.log(data);
 166 };
 167
 168 // Create the Socket
 169 chrome.socket.create('udp', '127.0.0.1', 1337, { onEvent: handleDataEvent },
 170  function(socketInfo) {
 171    // The socket is created, now we want to connect to the service
 172    var socketId = socketInfo.socketId;
 173    chrome.socket.connect(socketId, function(result) {
 174      // We are now connected to the socket so send it some data
 175      chrome.socket.write(socketId, arrayBuffer,
 176        function(sendInfo) {
 177          console.log("wrote " + sendInfo.bytesWritten);
 178        }
 179      );
 180    });
 181  }
 182 );
 183 </pre>
 184
 185 <p class="backtotop"><a href="#top">Back to top</a></p>