Added intro to socket API reference docs.

chrome/common/extensions/docs/server2/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="experimental.socket.html">Sockets API</a>.
+<a href="socket.html">Sockets API</a>.

[battre, 2012/09/03 13:35:37]

Socket API (without s)

 </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 "experimental" and "socket" permissions
-to the manifest:
+add the "socket" permission to the manifest
+and specify the IP end point permission rules.
+For example:
 </p>
 
 <pre>
 "permissions": [
-   "experimental",
-   "socket"
- ]
+    {"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 '*'>+

[battre, 2012/09/03 13:35:37]

Is this precise? www.example.com would not comply to '*.' <anychar except '/'
and '*'>+

+ <port> := '*' | <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>

[battre, 2012/09/03 13:35:37]

Add an example how you check for errors in onConnectedCallback? Do you use
chrome.extension.lastError?

 
 <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 and writing from a socket</h3>
+<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.
   }
@@ skipping 14 matching lines @@
 
 <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.experimental.socket.create('udp', '127.0.0.1', 1337, {},
+chrome.socket.create('udp', '127.0.0.1', 1337, {},

[battre, 2012/09/03 13:35:37]

Does this open a socket for incoming traffic *from the net*? Or does it only
bind to the loopback device, which is not accessible from anywhere but my
computer?

[battre, 2012/09/03 13:35:37]

This is incorrect. create does not take the IP address and port as separate
parameters.

[battre, 2012/09/03 13:35:37]

socket.create() takes a CreateOptions parameter but there is no place that
describes the content of this dictionary.

  function(socketInfo) {

[battre, 2012/09/03 13:35:37]

Error handling?

    // The socket is created, now we want to connect to the service
    var socketId = socketInfo.socketId;
-   chrome.experimental.socket.connect(socketId, function(result) {
+   chrome.socket.connect(socketId, function(result) {

[battre, 2012/09/03 13:35:37]

This is wrong: connect takes an IP address and port as paramters.

      // We are now connected to the socket so send it some data
-     chrome.experimental.socket.write(socketId, arrayBuffer,
+     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.experimental.socket.read(d.socketId);
+  var data = chrome.socket.read(d.socketId);

[battre, 2012/09/03 13:35:37]

This is incorrect: Read uses a callback function.

   console.log(data);
 };
 
 // Create the Socket
-chrome.experimental.socket.create('udp', '127.0.0.1', 1337, { onEvent: handleDataEvent },
+chrome.socket.create('udp', '127.0.0.1', 1337, { onEvent: handleDataEvent },

[battre, 2012/09/03 13:35:37]

This is incorrect. create does not take the IP address and port as separate
parameters.

[battre, 2012/09/03 13:35:37]

Don't you need to bind() the socket for incoming data? The API documentation
states at the moment that bind() does not support UDP.

  function(socketInfo) {
    // The socket is created, now we want to connect to the service
    var socketId = socketInfo.socketId;
-   chrome.experimental.socket.connect(socketId, function(result) {
+   chrome.socket.connect(socketId, function(result) {
      // We are now connected to the socket so send it some data
-     chrome.experimental.socket.write(socketId, arrayBuffer,
+     chrome.socket.write(socketId, arrayBuffer,
        function(sendInfo) {
          console.log("wrote " + sendInfo.bytesWritten);
        }
      );
    });
  }
 );
 </pre>
 
 <p class="backtotop"><a href="#top">Back to top</a></p>