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..ecf3088c397efd8cbdcddbfe579ddfc40072bdd5 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);
+
+  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.
@@ -205,6 +215,7 @@ namespace socket {
     // |address| : The address of the local machine.
     // |port| : The port of the local machine.
     // |backlog| : Length of the socket's listen queue.
+    // |callback| : Called when listen operation completes.
     static void listen(long socketId,
                        DOMString address,
                        long port,
@@ -250,6 +261,72 @@ 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.

[miket_OOO, 2013/04/25 21:52:12]

"diagrams" is probably not the right word.

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    // 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 with an 
+    // integer parameter indicating the platform-independent error code.
+    static void joinGroup(long socketId,
+                          DOMString address,
+                          JoinGroupCallback callback);
+
+    // Leave the multicast group previously joined using <code>joinGroup</code>.
+    // It's not nessesary to leave the multicast group before destroying the 

[miket_OOO, 2013/04/25 21:52:12]

spelling: necessary

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    // socket or exiting. This is automatically called by the OS.
+    //
+    // Leaving the group will prevent the router from sending multicast 
+    // datagrams to the local host, presuming no other process on the host is 
+    // still joined to the group.
+    //
+    // |socketId| : The socketId.
+    // |address| : The group address to leave. Domain names are not supported.
+    // |callback| : Called when the leave group operation is done with an
+    // integer parameter indicating the platform-independent error code.
+    static void leaveGroup(long socketId, DOMString address,
+                           LeaveGroupCallback callback);
+
+    // Set the time-to-live of multicast diagrams sent to the multicast group.
+    //
+    // Calling this method does not require multicast permissions.
+    //
+    // |socketId| : The socketId.
+    // |ttl| : The time-to-live value.
+    // |callback| : Called when the configuretion operation is done.

[miket_OOO, 2013/04/25 21:52:12]

spelling: configuration

[Bei Zhang, 2013/04/25 23:56:21]

Done.

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    static void setMulticastTimeToLive(
+        long socketId,
+        long ttl,
+        SetMulticastTimeToLiveCallback callback);
+
+    // Set the whether multicast diagrams sent from the host to the multicast 

[miket_OOO, 2013/04/25 21:52:12]

remove the first "the"

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    // group will be looped back to the host.
+    //
+    // Note: the behavior of <code>setMulticastLoopbackMode</code> is slightly
+    // different between Windows and Unix-like systems. The inconsistency only

[miket_OOO, 2013/04/25 21:52:12]

happens only (not only happens)

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    // happens when there are more than one applications on the same host 

[miket_OOO, 2013/04/25 21:52:12]

fix pluralization of "applications"

[miket_OOO, 2013/04/25 21:52:12]

there is, not there are ("there is ... one application") -- see
http://english.stackexchange.com/a/35998

[Bei Zhang, 2013/04/25 23:56:21]

Wow thanks! this is really helpful!
Done.

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    // joined to the same multicast group while having different settings on
+    // multicast loopback mode. On Windows, the applications with loopback off
+    // will not RECEIVE the loopback packets; while on Unix-like systems, the
+    // applications with loopback off will not SEND the loopback packets to
+    // other applications on the same host. See MSDN: http://goo.gl/6vqbj

[miket_OOO, 2013/04/25 21:52:12]

Hmmmm. This is a problem. The app writer will never ever ever know whether the
app is running on a specific OS. So what good is this documentation?

[Bei Zhang, 2013/04/25 23:56:21]

wtc concerned that we may not be able to make this behavior consistent ever. So
instead of making developers pull their hairs off finding bugs, at least we
should give them a hint. If this really makes a problem, they should start to
consider a way to workaround, for example, filter the packets manually.

On 2013/04/25 21:52:12, miket wrote:

+    //
+    // Calling this method does not require multicast permissions.
+    //
+    // |socketId| : The socketId.
+    // |enabled| : Indicate whether to enable loop back mode.

[miket_OOO, 2013/04/25 21:52:12]

Be consistent: either "loop back" or "loopback" (preferred)

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    // |callback| : Called when the configuretion operation is done.

[miket_OOO, 2013/04/25 21:52:12]

spelling

[Bei Zhang, 2013/04/25 23:56:21]

Done.

+    static void setMulticastLoopbackMode(
+        long socketId,
+        boolean enabled,
+        SetMulticastLoopbackModeCallback callback);
+
+    // Get the multicast group addresses the socket is currently joined to.
+    // |socketId| : The socketId.
+    // |callback| : Called with an array of strings of the result.
+    static void getJoinedGroups(long socketId,
+                                GetJoinedGroupsCallback callback);
   };
 
 };