// 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.

[DartPackage="mojo_services"]
module mojo;

import "mojo/public/interfaces/network/network_error.mojom";
import "network/interfaces/net_address.mojom";

// UDPSocket and UDPSocketReceiver represent a UDP socket and its client. The
// typical flow of using the interfaces is:
// - 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 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|. 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,
          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 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.
  //   ...
  //   service->ReceiveMore(3);
  //   // The client expects 4 more calls to OnReceived().
  //
  // Please note that how ReceiveMore() is used will affect performance
  // significantly. For example:
  //   // Approach 1:
  //   service->ReceiveMore(3);
  //   // OnReceived() is called.
  //   // OnReceived() is called.
  //   // OnReceived() is called.
  //
  //   // Approach 2:
  //   service->ReceiveMore(1);
  //   // OnReceived() is called.
  //   service->ReceiveMore(1);
  //   // OnReceived() is called.
  //   service->ReceiveMore(1);
  //   // OnReceived() is called.
  //
  // It is very likely that approach 1 will perform better than approach 2,
  // because in approach 2 getting every datagram takes at least the time of a
  // round trip to the service side.
  ReceiveMore(uint32 datagram_number);

  // Sends data to the specified destination. The socket must be bound or
  // connected. |dest_addr| is allowed to be null if the socket is connected.
  // 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 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);
};