PPB_TCPSocket: add support for TCP server socket operations.

ppapi/api/ppb_tcp_socket.idl

 /* Copyright 2013 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.
  */
 
 /**
  * This file defines the <code>PPB_TCPSocket</code> interface.
  */
 
-[generate_thunk]
-
 label Chrome {
-  M29 = 1.0
+  M29 = 1.0,
+  M31 = 1.1
 };
 
 /**
  * Option names used by <code>SetOption()</code>.
  */
 [assert_size(4)]
 enum PP_TCPSocket_Option {
   /**
    * Disables coalescing of small writes to make TCP segments, and instead
    * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
@@ skipping 14 matching lines @@
 
   /**
    * Specifies the total per-socket buffer space reserved for receives. Value's
    * type should be <code>PP_VARTYPE_INT32</code>.
    * This option can only be set after a successful <code>Connect()</code> call.
    *
    * Note: This is only treated as a hint for the browser to set the buffer
    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
    * guarantee it will conform to the size.
    */
-  PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
+  PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2,
+
+  /**
+   * Allows the socket to share the local address to which it will be bound.
+   * Value's type should be <code>PP_VARTYPE_BOOL</code>.
+   * This option can only be set before calling <code>Bind()</code>.
+   * Supported since version 1.1.
+   */
+  PP_TCPSOCKET_OPTION_ADDRESS_REUSE = 3
 };
 
 /**
  * The <code>PPB_TCPSocket</code> interface provides TCP socket operations.
  *
  * Permissions: Apps permission <code>socket</code> with subrule
- * <code>tcp-connect</code> is required for <code>Connect()</code>.
+ * <code>tcp-connect</code> is required for <code>Connect()</code>; subrule
+ * <code>tcp-listen</code> is required for <code>Listen()</code>.
  * For more details about network communication permissions, please see:
  * http://developer.chrome.com/apps/app_network.html
  */
 interface PPB_TCPSocket {
   /**
    * Creates a TCP socket resource.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
    * a module.
    *
    * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
    * on failure.
    */
   PP_Resource Create([in] PP_Instance instance);
 
   /**
    * Determines if a given resource is a TCP socket.
    *
    * @param[in] resource A <code>PP_Resource</code> to check.
    *
    * @return <code>PP_TRUE</code> if the input is a
    * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise.
    */
   PP_Bool IsTCPSocket([in] PP_Resource resource);
 
   /**
-   * Connects the socket to the given address.
+   * Binds the socket to the given address. The socket must not be bound.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
+   * @param[in] addr A <code>PPB_NetAddress</code> resource.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use.
+   * - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid.
+   */
+  [version=1.1]
+  int32_t Bind([in] PP_Resource tcp_socket,
+               [in] PP_Resource addr,
+               [in] PP_CompletionCallback callback);
+
+  /**
+   * Connects the socket to the given address. The socket must not be listening.

[bbudge, 2013/09/19 19:41:47]

It's not clear to me when or if the socket must be bound.

[yzshen1, 2013/09/19 21:12:15]

Done.

+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
    * @param[in] addr A <code>PPB_NetAddress</code> resource.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion.
    *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>,
    * including (but not limited to):
    * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
    *   permissions.
    * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
    *   unreachable.
    * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
    *   refused.
    * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
    * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
    *   out.
+   *
+   * If the socket is listening/connected or has a pending listen/connect
+   * request, <code>Connect()</code> will fail without starting a connection
+   * attempt. Otherwise, any failure during the connection attempt will cause
+   * the socket to be closed.
    */
   int32_t Connect([in] PP_Resource tcp_socket,
                   [in] PP_Resource addr,
                   [in] PP_CompletionCallback callback);
 
   /**
-   * Gets the local address of the socket, if it is connected.
+   * Gets the local address of the socket, if it is bound.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
    *
    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
    */
   PP_Resource GetLocalAddress([in] PP_Resource tcp_socket);
 
   /**
    * Gets the remote address of the socket, if it is connected.
@@ skipping 37 matching lines @@
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion.
    *
    * @return A non-negative number on success to indicate how many bytes have
    * been written; otherwise, an error code from <code>pp_errors.h</code>.
    */
   int32_t Write([in] PP_Resource tcp_socket,
                 [in] str_t buffer,
                 [in] int32_t bytes_to_write,
                 [in] PP_CompletionCallback callback);
+  /**
+   * Starts listening. The socket must be bound and not connected.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[in] backlog A hint to determine the maximum length to which the
+   * queue of pending connections may grow.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
+   *   permissions.
+   * - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already listening
+   *   on the same port.
+   */
+  [version=1.1]
+  int32_t Listen([in] PP_Resource tcp_socket,
+                 [in] int32_t backlog,
+                 [in] PP_CompletionCallback callback);
 
   /**
-   * Cancels all pending reads and writes and disconnects the socket. Any
-   * pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code>
-   * if pending IO was interrupted. After a call to this method, no output
-   * buffer pointers passed into previous <code>Read()</code> calls will be
-   * accessed. It is not valid to call <code>Connect()</code> again.
+   * Accepts a connection. The socket must be listening.
+   *
+   * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
+   * socket.
+   * @param[out] accepted_tcp_socket Stores the accepted TCP socket on success.

[bbudge, 2013/09/19 19:41:47]

Is the returned socket bound and connected?

[yzshen1, 2013/09/19 21:12:15]

Accepted socket is connected.

+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>,
+   * including (but not limited to):
+   * - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted.
+   */
+  [version=1.1]
+  int32_t Accept([in] PP_Resource tcp_socket,
+                 [out] PP_Resource accepted_tcp_socket,
+                 [in] PP_CompletionCallback callback);
+
+  /**
+   * Cancels all pending operations and closes the socket. Any pending callbacks
+   * will still run, reporting <code>PP_ERROR_ABORTED</code> if pending IO was
+   * interrupted. After a call to this method, no output buffer pointers passed
+   * into previous <code>Read()</code> or <code>Accept()</code> calls will be
+   * accessed. It is not valid to call <code>Connect()</code> or
+   * <code>Listen()</code> again.
    *
    * The socket is implicitly closed if it is destroyed, so you are not required
    * to call this method.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
    */
   void Close([in] PP_Resource tcp_socket);
 
   /**
    * Sets a socket option on the TCP socket.
    * Please see the <code>PP_TCPSocket_Option</code> description for option
    * names, value types and allowed values.
    *
    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
    * socket.
    * @param[in] name The option to set.
    * @param[in] value The option value to set.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion.
    *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    */
   int32_t SetOption([in] PP_Resource tcp_socket,
                     [in] PP_TCPSocket_Option name,
                     [in] PP_Var value,
                     [in] PP_CompletionCallback callback);
 };