Mojo UDP socket API definition.

mojo/services/public/interfaces/network/udp_socket.mojom

+// Copyright 2014 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.
+
+import "mojo/services/public/interfaces/network/net_address.mojom"
+import "mojo/services/public/interfaces/network/network_error.mojom"
+
+module mojo {
+
+[Client=UDPSocketClient]
+interface UDPSocket {
+  // Sets the send buffer size (in bytes) for the socket.

[brettw, 2014/09/29 17:41:22]

Does this need to be called before bind or can it be any time? Should be
documented Same for the other ones.

[yzshen1, 2014/09/29 19:32:36]

Right. Thanks!

+  //
+  // Note: This is only treated as a hint. Even if it succeeds, the service
+  // doesn't guarantee it will conform to the size.
+  SetSendBufferSize(uint32 size) => (NetworkError result);
+
+  // Sets the receive buffer size (in bytes) for the socket.
+  //
+  // Note: This is only treated as a hint. Even if it succeeds, the service
+  // doesn't guarantee it will conform to the size.
+  SetReceiveBufferSize(uint32 size) => (NetworkError result);
+
+  // Allows the socket to share the local address to which it will be bound with
+  // other processes. Should be called before Bind().

[brettw, 2014/09/29 17:41:22]

I don't really understand what this means or what the implications are for using
this.

[yzshen1, 2014/09/29 19:32:35]

Pepper UDP socket users don't seem to have problem with the same comment.

It is basically SO_REUSEADDR. I decided to not comment more than the /net UDP
socket API documentation, otherwise I may need to go into the details like
http://stackoverflow.com/questions/14388706/socket-options-so-reuseaddr-and-s...

Or do you think it is okay to refer to SO_REUSEADDR directly?


On 2014/09/29 17:41:22, brettw wrote:

[brettw, 2014/09/29 19:55:33]

I think mentioning that this is equivalent to SO_REUSEADDR is good, since then
it's something I can look up on Google and get all the background I need.

[yzshen1, 2014/09/29 21:08:42]

Done.

+  AllowAddressReuse() => (NetworkError result);
+
+  // Binds the socket to the given address.
+  // |bound_addr| is non-NULL on success.
+  Bind(NetAddress addr) => (NetworkError result, NetAddress? bound_addr);

[brettw, 2014/09/29 17:41:22]

It's not quite clear to me how I use this class. Is it possible to write a
class-level comment and have it appear in the generated files? I'm looking for
an overall flow, like "create, set buffer sizes, bind, send/receive".

[yzshen1, 2014/09/29 19:32:36]

Done. Please let me know whether it looks okay. Thanks!

+
+  // Notifies that the client is ready to accept |number| of packets.
+  // Correspondingly, OnReceived() of the UDPSocketClient interface will be
+  // called |number| times (errors also count), unless the connection is closed
+  // before that. The socket must be bound.
+  //
+  // It is allowed to call this method again before the previous request is
+  // completely satisfied. For example:
+  //   service->ReceiveMorePackets(3);
+  //   ...
+  //   // OnReceived() is called.
+  //   // OnReceived() is called.
+  //   ...
+  //   service->ReceiveMorePackets(3);
+  //   // The client expects 4 more calls to OnReceived().
+  ReceiveMorePackets(uint32 number);
+
+  // Sends data to the specified destination. The socket must be bound.
+  // The method doesn't report the result of the operation.
+  SendToAndForget(NetAddress addr, uint8[] data);
+
+  // Sends data to the specified destination. The socket must be bound.
+  SendTo(NetAddress addr, uint8[] data) => (NetworkError result);

[yzshen1, 2014/09/23 06:50:45]

NetworkError here seems to be consistent with other network APIs.
However, it is probably a waste: I don't think users need the description string
in most cases. I prefer to just return an error code.
If we need to map error code to a string, we could consider a utility
function/class in a client library, or a method on the NetworkService interface.

What do you think?

[brettw, 2014/09/29 17:41:22]

I like the network error.

+};
+
+interface UDPSocketClient {
+  // |addr| and |data| are non-NULL on success.
+  OnReceived(NetworkError result, NetAddress? addr, uint8[]? data);
+};
+
+}