Added intro to socket API reference docs.

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

Index: chrome/common/extensions/docs/server2/templates/articles/app_network.html
diff --git a/chrome/common/extensions/docs/server2/templates/articles/app_network.html b/chrome/common/extensions/docs/server2/templates/articles/app_network.html
index 7a81cf9659942d1654271b9040694ae741de0c1f..707f62b70524f15f06bd8e1ddc1bc258ab4ba62b 100644
--- a/chrome/common/extensions/docs/server2/templates/articles/app_network.html
+++ b/chrome/common/extensions/docs/server2/templates/articles/app_network.html
@@ -1,6 +1,5 @@
 <h1>Network Communications</h1>
 
-
 <p>
 Packaged apps can act as a network client
 for TCP and UDP connections.
@@ -8,7 +7,7 @@ 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">
@@ -23,17 +22,47 @@ and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/udp"
 
 <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>
@@ -61,7 +90,7 @@ you can later read and write to this socket.
 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.
@@ -96,13 +125,13 @@ over the network using UDP:
 
 <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);
        }
@@ -125,18 +154,18 @@ that will be called when data is available on the port.
 <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);
        }