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>.
 </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 '*'>+
+ &lt;port> := '*' | &lt;port number between 1 and 65535>)
+</pre>
+
+<p>
+Examples of socket permission rules:
+</p>
+
+<ul>
+  <li>"tcp-connect:*:23" &ndash; For connecting port 23 of any hosts</li>

[miket_OOO, 2012/08/31 22:33:59]

connecting to (or maybe on)

[mkearney1, 2012/08/31 23:32:12]

Done.

+  <li>"tcp-connect:www.example.com:23" &ndash;
+    For connecting port 23 of <em>www.example.com</em></li>

[miket_OOO, 2012/08/31 22:33:59]

Overall I'd eliminate the "for" from each of these, as it doesn't sound quite
idiomatic. "Connect to www.example.com on port 23" is the right pattern.

[mkearney1, 2012/08/31 23:32:12]

Done.

+  <li>"tcp-connect" &ndash; For connecting any ports of any hosts</li>
+  <li>"udp-send-to::99" &ndash; For sending UDP package to port 99 of any hosts</li>

[miket_OOO, 2012/08/31 22:33:59]

packet, not package, and I'd say "sending UDP packets" (plural)

[mkearney1, 2012/08/31 23:32:12]

Done.

+  <li>"udp-bind::8899" &ndash; For binding local port 8899 to receive UDP package</li>
+  <li>"tcp-listen::8080" &ndash; For tcp listening on local port 8080</li>

[miket_OOO, 2012/08/31 22:33:59]

TCP

[mkearney1, 2012/08/31 23:32:12]

Done.

+</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 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, {},
  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>
 
 <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);
   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 },
  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>