Add documentation for

the chrome.sockets API and manifest key.

BUG=293756

Review URL: https://codereview.chromium.org/94093013

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@243728 0039d316-1c4b-4281-b951-d872f2087c98

chrome/common/extensions/api/sockets_tcp.idl

@@ -4,9 +4,7 @@
 
 // Use the <code>chrome.sockets.tcp</code> API to send and receive data over the
 // network using TCP connections. This API supersedes the TCP functionality
-// previously found in the <code>chrome.socket</code> API. Note that the socket
-// ids created from this namespace are not compatible with ids created in other
-// namespaces.
+// previously found in the <code>chrome.socket</code> API.
 namespace sockets.tcp {
   // The socket properties specified in the <code>create</code> or
   // <code>update</code> function. Each property is optional. If a property
@@ -31,7 +29,9 @@ namespace sockets.tcp {
 
   // Result of <code>create</code> call.
   dictionary CreateInfo {
-    // The ID of the newly created socket.
+    // The ID of the newly created socket. Note that socket IDs created from
+    // this API are not compatible with socket IDs created from other APIs, such
+    // as the deprecated <code>$ref:socket</code> API.
     long socketId;
   };
 

chrome/common/extensions/api/sockets_tcp_server.idl

@@ -4,9 +4,7 @@
 
 // Use the <code>chrome.sockets.tcpServer</code> API to create server
 // applications using TCP connections. This API supersedes the TCP functionality
-// previously found in the <code>chrome.socket</code> API. Note that the socket
-// ids created from this namespace are not compatible with ids created in other
-// namespaces.
+// previously found in the <code>chrome.socket</code> API.
 namespace sockets.tcpServer {
   // The socket properties specified in the <code>create</code> or
   // <code>update</code> function. Each property is optional. If a property
@@ -28,7 +26,9 @@ namespace sockets.tcpServer {
 
   // Result of <code>create</code> call.
   dictionary CreateInfo {
-    // The ID of the newly created server socket.
+    // The ID of the newly created server socket. Note that socket IDs created
+    // from this API are not compatible with socket IDs created from other APIs,
+    // such as the deprecated <code>$ref:socket</code> API.
     long socketId;
   };
 

chrome/common/extensions/api/sockets_udp.idl

@@ -4,8 +4,7 @@
 
 // Use the <code>chrome.sockets.udp</code> API to send and receive data over the
 // network using UDP connections. This API supersedes the UDP functionality
-// previously found in the "socket" API. Note that the socket ids created from
-// this namespace are not compatible with ids created in other namespaces.
+// previously found in the "socket" API.
 namespace sockets.udp {
   // The socket properties specified in the <code>create</code> or
   // <code>update</code> function. Each property is optional. If a property
@@ -31,7 +30,9 @@ namespace sockets.udp {
 
   // Result of <code>create</code> call.
   dictionary CreateInfo {
-    // The ID of the newly created socket.
+    // The ID of the newly created socket. Note that socket IDs created from
+    // this API are not compatible with socket IDs created from other APIs, such
+    // as the deprecated <code>$ref:socket</code> API.
     long socketId;
   };
 

chrome/common/extensions/docs/templates/articles/manifest/sockets.html

+<h1>sockets</h1>
+
+<p>
+The <code>sockets</code> manifest property declares which permissions are
+available for the $ref:sockets.udp, $ref:sockets.tcp and
+$ref:sockets.tcpServer APIs.
+</p>
+
+<h2 id="manifest">Sample manifest.json</h2>
+<pre data-filename="manifest.json">
+{
+  "name": "My Sockets {{platform}}",
+  "sockets": {
+    "udp": {
+      // Permission for chrome.sockets.udp.send:
+      // The application is allowed to send udp packets
+      // to any host:port combination.
+      "send": "*"
+    },
+    "tcp": {
+      // Permission for chrome.sockets.tcp.connect:
+      // The application is allowed to connect only to the
+      // tcp server on 127.0.0.1 port 80.
+      "connect": "127.0.0.1:80"
+    },
+    "tcpServer": {
+      // Permission for chrome.sockets.tcpServer.listen:
+      // The application is allowed to accept new client
+      // connections on the local address at port 80.
+      "listen": "127.0.0.1:80"
+    }
+  },
+  ...
+}
+</pre>
+
+<section>
+<h2 id="reference">Reference</h2>
+<p class="api_reference">
+{{+partials.type type:apis.manifestTypes.byName.sockets/}}
+</p>
+</section>
\ No newline at end of file

chrome/common/extensions/docs/templates/json/manifest.json

@@ -139,6 +139,12 @@
     "documentation": "manifest/name.html#short_name",
     "example": "Short Name"
   },
+  "sockets": {
+    "documentation": "manifest/sockets.html",
+    "example": {
+      "tcp": { "connect": "*" }, "udp": { "send": "*" }
+    }
+  },
   "storage": {
     "documentation": "manifest/storage.html",
     "example": {

chrome/common/extensions/docs/templates/public/apps/manifest/sockets.html

+{{+partials.standard_apps_article article:intros.manifest/sockets/}}

chrome/common/extensions/docs/templates/public/apps/sockets_tcp.html

+{{+partials.standard_apps_api api:apis.sockets_tcp/}}

chrome/common/extensions/docs/templates/public/apps/sockets_tcpServer.html

+{{+partials.standard_apps_api api:apis.sockets_tcp_server/}}

chrome/common/extensions/docs/templates/public/apps/sockets_udp.html

+{{+partials.standard_apps_api api:apis.sockets_udp/}}

chrome/common/extensions/docs/templates/public/apps/system_network.html

+{{+partials.standard_apps_api api:apis.system_network/}}