From 5731e121244fb91b97b37daefc1b59b27387b050 Mon Sep 17 00:00:00 2001 From: "mkearney@google.com" Date: Sat, 1 Sep 2012 00:54:39 +0000 Subject: [PATCH] Added intro to socket API reference docs. Also improved Network Communications documentation: * removed experimental references * enhanced permissions to include new socket permission rules. I don't have a staged version of the docs up and running yet for new server. I've checked the docs locally though. local commit BUG= Review URL: https://chromiumcodereview.appspot.com/10908045 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@154553 0039d316-1c4b-4281-b951-d872f2087c98 --- .../server2/templates/articles/app_network.html | 59 ++++++++++++++++------ .../docs/server2/templates/intros/socket.html | 10 ++++ .../docs/server2/templates/public/apps/socket.html | 2 +- 3 files changed, 55 insertions(+), 16 deletions(-) create mode 100644 chrome/common/extensions/docs/server2/templates/intros/socket.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 7a81cf965994..707f62b70524 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 @@

Network Communications

-

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 -Sockets API. +Sockets API.

@@ -23,17 +22,47 @@ and 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: 

 "permissions": [
-   "experimental",
-   "socket"
- ]
+    {"socket": [
+      "rule1",
+      "rule2",
+      ...
+    ]}
+  ]
+

+The syntax of socket permission rules follows these patterns: +

+ +
+<socket-permission-rule>
+     := <op> | <op> ':' <host> | <op> ':' ':' <port> |
+        <op> ':' <host> ':' <port>
+ <op> := 'tcp-connect' | 'tcp-listen' | 'udp-bind' | 'udp-send-to'
+ <host> := '*' | '*.' <anychar except '/' and '*'>+
+ <port> := '*' | <port number between 1 and 65535>)
+
+ +

+Examples of socket permission rules: +

+ + +

Using TCP

@@ -61,7 +90,7 @@ you can later read and write to this socket. chrome.socket.write(socketId, arrayBuffer, onWriteCompleteCallback); -

Reading to and writing from a socket

+

Reading to & writing from a socket

Reading and writing from a socket uses ArrayBuffer objects. @@ -96,13 +125,13 @@ over the network using UDP: 

 // 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);
        }
@@ -125,18 +154,18 @@ that will be called when data is available on the port.
 
 // 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);
        }
diff --git a/chrome/common/extensions/docs/server2/templates/intros/socket.html b/chrome/common/extensions/docs/server2/templates/intros/socket.html
new file mode 100644
index 000000000000..10b59a451425
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/intros/socket.html
@@ -0,0 +1,10 @@
+

+Use the chrome.socket module
+to send and receive data over the network
+using TCP and UDP connections.
+

+
+

+Read the Network Communications documentation
+to find out how to use this API.
+

\ No newline at end of file
diff --git a/chrome/common/extensions/docs/server2/templates/public/apps/socket.html b/chrome/common/extensions/docs/server2/templates/public/apps/socket.html
index d5602e8dfcbf..d9e480996382 100644
--- a/chrome/common/extensions/docs/server2/templates/public/apps/socket.html
+++ b/chrome/common/extensions/docs/server2/templates/public/apps/socket.html
@@ -1 +1 @@
-{{+partials.standard_apps_api api:apis.socket}}
+{{+partials.standard_apps_api api:apis.socket intro:intros.socket}}
\ No newline at end of file
-- 
2.11.4.GIT