Multicast socket API

chrome/common/extensions/api/socket.idl

Index: chrome/common/extensions/api/socket.idl
diff --git a/chrome/common/extensions/api/socket.idl b/chrome/common/extensions/api/socket.idl
index 3cb999c6248b45c11792c763c70b385be4514f8d..ac3b0d8d9d82e42005f3435610b4b67d6e701172 100644
--- a/chrome/common/extensions/api/socket.idl
+++ b/chrome/common/extensions/api/socket.idl
@@ -114,6 +114,16 @@ namespace socket {
 
   callback GetNetworkCallback = void (NetworkInterface[] result);
 
+  callback JoinGroupCallback = void (long result);

[scheib, 2013/04/02 18:25:17]

Document what the result values mean, and that -1 will be returned in error
cases. Etc. for other callbacks.

[Bei Zhang, 2013/04/05 00:38:59]

I checked other files and found out that callbacks are not typically documented
here. They are sometimes documented in the functions accepting them. In this
case, as we have a lot of callbacks, it might be a little bit different though.
On 2013/04/02 18:25:17, scheib wrote:

[scheib, 2013/04/05 17:41:04]

In at least some place, document what the return values mean.

+
+  callback LeaveGroupCallback = void (long result);
+
+  callback SetMulticastTimeToLiveCallback = void (long result);
+
+  callback SetMulticastLoopbackModeCallback = void (long result);
+
+  callback GetJoinedGroupsCallback = void (DOMString[] groups);
+
   interface Functions {
     // Creates a socket of the specified type that will connect to the specified
     // remote machine.
@@ -250,6 +260,54 @@ namespace socket {
     // Retrieves information about local adapters on this system.
     // |callback| : Called when local adapter information is available.
     static void getNetworkList(GetNetworkCallback callback);
+
+    // Join the multicast group and start to receive diagrams from that group.
+    // The socket must be of UDP type and must be bound to a local port
+    // before calling this method.
+    // |socketId| : The socketId.
+    // |address| : The group address to join. Domain names are not supported.
+    // |callback| : Called when the join group operation is done.
+    static void joinGroup(long socketId,
+                          DOMString address,
+                          JoinGroupCallback callback);
+
+    // Leave the multicast group previously joined using <code>joinGroup</code>

[scheib, 2013/04/02 18:25:17]

Period at end of line.

[Bei Zhang, 2013/04/05 00:38:59]

Done.

+    // It's not nessesary to leave the multicast group before destroying the 
+    // socket or exiting. This is automatically called by the OS.
+    // 
+    // To leave group before destroy the socket can prevent the router from
+    // sending muticast diagrams to the local host if none of the processes on 
+    // the host is joined to the group.

[scheib, 2013/04/02 18:25:17]

Wording is a bit awkward. Perhaps:
"Leaving the group before destroying the socket will prevent the router from
sending multicast [[?datagrams, or packets?]] to the local host, presuming no
other process on the host is still joined to the group."

[Bei Zhang, 2013/04/05 00:38:59]

Done.

+    // |socketId| : The socketId.
+    // |address| : The group address to leave. Domain names are not supported.
+    // |callback| : Called when the leave group operation is done.
+    static void leaveGroup(long socketId, DOMString address,
+                           LeaveGroupCallback callback);
+
+    // Set the time-to-live of multicast diagrams sent to the multicast group.
+    // |socketId| : The socketId.
+    // |ttl| : The time-to-live value.
+    // |callback| : Called when the configuretion operation is done.
+    static void setMulticastTimeToLive(
+        long socketId,
+        long ttl,
+        SetMulticastTimeToLiveCallback callback);
+
+    // Set the whether multicast diagrams sent from the host to the multicast 
+    // group will be looped back to the host.
+    // |socketId| : The socketId.
+    // |enabled| : Indicate whether to enable loop back mode.
+    // |callback| : Called when the configuretion operation is done.
+    static void setMulticastLoopbackMode(
+        long socketId,
+        boolean enabled,
+        SetMulticastLoopbackModeCallback callback);
+
+    // Get the multicast group adrresses the socket currently joining.

[scheib, 2013/04/02 18:25:17]

addresses the socket is currently joined to.

[Bei Zhang, 2013/04/05 00:38:59]

Done.

+    // |socketId| : The socketId.
+    // |callback| : Called with an array of strings of the result.
+    static void getJoinedGroups(long socketId,
+                                GetJoinedGroupsCallback callback);
   };
 
 };