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);

[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.
     // |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 116 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.
+    // 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);
   };
 
 };