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

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module mojo;
   6
   7 import "mojo/services/public/interfaces/network/net_address.mojom";
   8 import "mojo/services/public/interfaces/network/network_error.mojom";
   9
  10 // UDPSocket and UDPSocketClient represent a UDP socket and its client. The
  11 // typical flow of using the interfaces is:
  12 // - Acquire a UDPSocket interface pointer and set a UDPSocketClient instance.
  13 // - (optional) Set options which are allowed prior to Bind().
  14 // - Bind the socket.
  15 // - (optional) Set options which are allowed after Bind().
  16 // - Send / request to receive datagrams. Received datagrams will be delivered
  17 //   to UDPSocketClient.OnReceived().
  18
  19 [Client=UDPSocketClient]
  20 interface UDPSocket {
  21   // Allows the socket to share the local address to which it will be bound with
  22   // other processes. Should be called before Bind().
  23   // (This is equivalent to SO_REUSEADDR of the POSIX socket API.)
  24   AllowAddressReuse() => (NetworkError result);
  25
  26   // Binds the socket to the given address.
  27   // |bound_addr| is non-NULL on success. It might not be the same as |addr|.
  28   // For example, if port 0 is used in |addr|, an available port is picked and
  29   // returned in |bound_addr|.
  30   Bind(NetAddress addr) => (NetworkError result, NetAddress? bound_addr);
  31
  32   // Sets the OS send buffer size (in bytes) for the socket. The socket must be
  33   // bound.
  34   SetSendBufferSize(uint32 size) => (NetworkError result);
  35
  36   // Sets the OS receive buffer size (in bytes) for the socket. The socket must
  37   // be bound.
  38   SetReceiveBufferSize(uint32 size) => (NetworkError result);
  39
  40   // Negotiates the maximum number of pending SendTo() requests. If
  41   // |requested_size| is set to 0, this method queries the current settings.
  42   //
  43   // The service stores SendTo() requests in a queue while they are waiting to
  44   // be executed (i.e., while they are waiting to be placed in the OS send
  45   // buffer and sent out). This method negotiates how many requests (not bytes)
  46   // this queue is able to store. If the queue is full, the service fails new
  47   // requests directly with error code ERR_INSUFFICIENT_RESOURCES and discards
  48   // those datagrams. If the client wants to avoid such failures, it needs to
  49   // keep track of how many SendTo() calls are pending and make sure the number
  50   // doesn't exceed the result of this method.
  51   NegotiateMaxPendingSendRequests(uint32 requested_size)
  52       => (uint32 actual_size);
  53
  54   // Notifies that the client is ready to accept |number| of datagrams.
  55   // Correspondingly, OnReceived() of the UDPSocketClient interface will be
  56   // called |number| times (errors also count), unless the connection is closed
  57   // before that.
  58   //
  59   // It is allowed to call this method again before the previous request is
  60   // completely satisfied. For example:
  61   //   service->ReceiveMore(3);
  62   //   ...
  63   //   // OnReceived() is called.
  64   //   // OnReceived() is called.
  65   //   ...
  66   //   service->ReceiveMore(3);
  67   //   // The client expects 4 more calls to OnReceived().
  68   //
  69   // Please note that how ReceiveMore() is used will affect performance
  70   // significantly. For example:
  71   //   // Approach 1:
  72   //   service->ReceiveMore(3);
  73   //   // OnReceived() is called.
  74   //   // OnReceived() is called.
  75   //   // OnReceived() is called.
  76   //
  77   //   // Approach 2:
  78   //   service->ReceiveMore(1);
  79   //   // OnReceived() is called.
  80   //   service->ReceiveMore(1);
  81   //   // OnReceived() is called.
  82   //   service->ReceiveMore(1);
  83   //   // OnReceived() is called.
  84   //
  85   // It is very likely that approach 1 will perform better than approach 2,
  86   // because in approach 2 getting every datagram takes at least the time of a
  87   // round trip to the service side.
  88   ReceiveMore(uint32 datagram_number);
  89
  90   // Sends data to the specified destination. The socket must be bound.
  91   // On success, |result.code| is a non-negative number indicating how many
  92   // bytes have been written. Otherwise, it is a network error code, including
  93   // (but not limited to):
  94   // - ERR_INSUFFICIENT_RESOURCES (-12): The service doesn't have sufficient
  95   //   resource to complete the operation. One possible cause is that the client
  96   //   tries to send too many datagrams in a short period of time.
  97   // TODO(yzshen): Formalize Mojo networking error codes.
  98   SendTo(NetAddress dest_addr, array<uint8> data) => (NetworkError result);
  99 };
 100
 101 interface UDPSocketClient {
 102   // On success, |src_addr| and |data| are non-NULL, and |result.code| is a
 103   // non-negative number indicating how many bytes have been received. On
 104   // failure, |result.code| is a network error code.
 105   OnReceived(NetworkError result, NetAddress? src_addr, array<uint8>? data);
 106 };