De-Clientize UDPSocket service

mojo/services/network/public/interfaces/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.
 
 module mojo;
 
 import "network/public/interfaces/net_address.mojom";
 import "network/public/interfaces/network_error.mojom";
 
-// UDPSocket and UDPSocketClient represent a UDP socket and its client. The
+// UDPSocket and UDPSocketReceiver represent a UDP socket and its client. The
 // typical flow of using the interfaces is:
-// - Acquire a UDPSocket interface pointer and set a UDPSocketClient instance.
+// - Acquire a UDPSocket interface pointer.
 // - (optional) Set options which are allowed prior to Bind()/Connect().
 // - Bind or connect the socket.
+// - (optional) Bind the UDPSocketReceiver request returned by Bind()/Connect()
 // - (optional) Set options which are allowed after Bind()/Connect().
 // - Send / request to receive datagrams. Received datagrams will be delivered
-//   to UDPSocketClient.OnReceived().
-
-// TODO(yzshen): Get rid of [Client] annotation.
-[Client=UDPSocketClient]
+//   to the bound receiver's OnReceived() call.
 interface UDPSocket {
   // Allows the socket to share the local address to which it will be bound with
   // other processes. Should be called before Bind().
   // (This is equivalent to SO_REUSEADDR of the POSIX socket API.)
   AllowAddressReuse() => (NetworkError result);
 
   // Binds the socket to the given address. The socket must not be bound or
   // connected.
   // |bound_addr| is non-null on success. It might not be the same as |addr|.
   // For example, if port 0 is used in |addr|, an available port is picked and
-  // returned in |bound_addr|.
-  Bind(NetAddress addr) => (NetworkError result, NetAddress? bound_addr);
-
+  // returned in |bound_addr|. The caller may provide an implementation of
+  // |receiver| to receive datagrams read from the socket. |receiver| is null
+  // on failure.
+  Bind(NetAddress addr) => (NetworkError result, NetAddress? bound_addr,
+                            UDPSocketReceiver&? receiver);
 
   // Connects the socket to the remote address. The socket must not be bound or
   // connected.
   // |local_addr| is non-null on success.
+  // The caller may provide an implementation of |receiver| to receive datagrams
+  // read from the socket. |receiver| is null on failure.
   Connect(NetAddress remote_addr) => (NetworkError result,
-                                      NetAddress? local_addr);
+                                      NetAddress? local_addr,
+                                      UDPSocketReceiver&? receiver);
 
   // Sets the OS send buffer size (in bytes) for the socket. The socket must be
   // bound or connected.
   SetSendBufferSize(uint32 size) => (NetworkError result);
 
   // Sets the OS receive buffer size (in bytes) for the socket. The socket must
   // be bound or connected.
   SetReceiveBufferSize(uint32 size) => (NetworkError result);
 
   // Negotiates the maximum number of pending SendTo() requests. If
   // |requested_size| is set to 0, this method queries the current settings.
   //
   // The service stores SendTo() requests in a queue while they are waiting to
   // be executed (i.e., while they are waiting to be placed in the OS send
   // buffer and sent out). This method negotiates how many requests (not bytes)
   // this queue is able to store. If the queue is full, the service fails new
   // requests directly with error code ERR_INSUFFICIENT_RESOURCES and discards
   // those datagrams. If the client wants to avoid such failures, it needs to
   // keep track of how many SendTo() calls are pending and make sure the number
   // doesn't exceed the result of this method.
   NegotiateMaxPendingSendRequests(uint32 requested_size)
       => (uint32 actual_size);
 
-  // Notifies that the client is ready to accept |number| of datagrams.
-  // Correspondingly, OnReceived() of the UDPSocketClient interface will be
+  // Notifies that the receiver is ready to accept |number| of datagrams.
+  // Correspondingly, OnReceived() of the UDPSocketReceiver interface will be
   // called |number| times (errors also count), unless the connection is closed
   // before that.
   //
   // It is allowed to call this method again before the previous request is
   // completely satisfied. For example:
   //   service->ReceiveMore(3);
   //   ...
   //   // OnReceived() is called.
   //   // OnReceived() is called.
   //   ...
@@ skipping 26 matching lines @@
   // On success, |result.code| is a non-negative number indicating how many
   // bytes have been written. Otherwise, it is a network error code, including
   // (but not limited to):
   // - ERR_INSUFFICIENT_RESOURCES (-12): The service doesn't have sufficient
   //   resource to complete the operation. One possible cause is that the client
   //   tries to send too many datagrams in a short period of time.
   // TODO(yzshen): Formalize Mojo networking error codes.
   SendTo(NetAddress? dest_addr, array<uint8> data) => (NetworkError result);
 };
 
-interface UDPSocketClient {
+interface UDPSocketReceiver {
   // On success, |data| is non-null, |src_addr| is non-null if the socket is
   // not connected, |result.code| is a non-negative number indicating how many
   // bytes have been received. On failure, |result.code| is a network error
   // code.
   OnReceived(NetworkError result, NetAddress? src_addr, array<uint8>? data);
 };