Multicast socket API

chrome/common/extensions/api/socket.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 namespace socket {
   enum SocketType {
     tcp,
     udp
   };
 
@@ skipping 96 matching lines @@
   callback SendToCallback = void (WriteInfo writeInfo);
 
   callback SetKeepAliveCallback = void (boolean result);
 
   callback SetNoDelayCallback = void (boolean result);
 
   callback GetInfoCallback = void (SocketInfo result);
 
   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.
     // |type| : The type of socket to create. Must be <code>tcp</code> or
     // <code>udp</code>.
     // |options| : The socket options.
     // |callback| : Called when the socket has been created.
     static void create(SocketType type,
                        optional CreateOptions options,
                        CreateCallback callback);
@@ skipping 71 matching lines @@
                        SendToCallback callback);
 
     // This method applies to TCP sockets only.
     // Listens for connections on the specified port and address. This
     // effectively makes this a server socket, and client socket
     // functions (connect, read, write) can no longer be used on this socket.
     // |socketId| : The socketId.
     // |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,
                        optional long backlog,
                        ListenCallback callback);
 
     // This method applies to TCP sockets only.
     // Registers a callback function to be called when a connection is
     // accepted on this listening server socket. Listen must be called first.
     // If there is already an active accept callback, this callback will be
@@ skipping 25 matching lines @@
 
     // Retrieves the state of the given socket.
     // |socketId| : The socketId.
     // |callback| : Called when the state is available.
     static void getInfo(long socketId,
                         GetInfoCallback callback);
 
     // 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);
   };
 
 };