PPB_TCPSocket: add support for TCP server socket operations.

ppapi/cpp/tcp_socket.h

 // 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.
 
 #ifndef PPAPI_CPP_TCP_SOCKET_H_
 #define PPAPI_CPP_TCP_SOCKET_H_
 
 #include "ppapi/c/ppb_tcp_socket.h"
 #include "ppapi/cpp/net_address.h"
 #include "ppapi/cpp/pass_ref.h"
 #include "ppapi/cpp/resource.h"
 
 namespace pp {
 
 class CompletionCallback;
 class InstanceHandle;
 
+template <typename T> class CompletionCallbackWithOutput;
+
 /// The <code>TCPSocket</code> class 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
 class TCPSocket : public Resource {
  public:
   /// Default constructor for creating an is_null() <code>TCPSocket</code>
   /// object.
   TCPSocket();
 
   /// A constructor used to create a <code>TCPSocket</code> object.
   ///
@@ skipping 21 matching lines @@
   ///
   /// @return A reference to this <code>TCPSocket</code> object.
   TCPSocket& operator=(const TCPSocket& other);
 
   /// Static function for determining whether the browser supports the
   /// <code>PPB_TCPSocket</code> interface.
   ///
   /// @return true if the interface is available, false otherwise.
   static bool IsAvailable();
 
-  /// Connects the socket to the given address.
+  /// Binds the socket to the given address. The socket must not be bound.
   ///
   /// @param[in] addr A <code>NetAddress</code> object.
   /// @param[in] callback A <code>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.
+  int32_t Bind(const NetAddress& addr, const CompletionCallback& callback);
+
+  /// Connects the socket to the given address. The socket must not be
+  /// listening. Binding the socket beforehand is optional.
+  ///
+  /// @param[in] addr A <code>NetAddress</code> object.
+  /// @param[in] callback A <code>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.
-  int32_t Connect(const NetAddress& addr,
-                  const CompletionCallback& callback);
+  ///
+  /// 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(const NetAddress& addr, const CompletionCallback& callback);
 
-  /// Gets the local address of the socket, if it is connected.
+  /// Gets the local address of the socket, if it is bound.
   ///
   /// @return A <code>NetAddress</code> object. The object will be null
   /// (i.e., is_null() returns true) on failure.
   NetAddress GetLocalAddress() const;
 
   /// Gets the remote address of the socket, if it is connected.
   ///
   /// @return A <code>NetAddress</code> object. The object will be null
   /// (i.e., is_null() returns true) on failure.
   NetAddress GetRemoteAddress() const;
@@ skipping 34 matching lines @@
   /// @param[in] bytes_to_write The number of bytes to write.
   /// @param[in] callback A <code>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(const char* buffer,
                 int32_t bytes_to_write,
                 const 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.
+  /// Starts listening. The socket must be bound and not connected.
+  ///
+  /// @param[in] backlog A hint to determine the maximum length to which the
+  /// queue of pending connections may grow.
+  /// @param[in] callback A <code>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.
+  int32_t Listen(int32_t backlog,
+                 const CompletionCallback& callback);
+
+  /// Accepts a connection. The socket must be listening.
+  ///
+  /// @param[in] callback A <code>CompletionCallbackWithOutput</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.
+  int32_t Accept(const CompletionCallbackWithOutput<TCPSocket>& 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.
   void Close();
 
   /// 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] name The option to set.
   /// @param[in] value The option value to set.
   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
   /// completion.
   ///
   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
-  ////
   int32_t SetOption(PP_TCPSocket_Option name,
                     const Var& value,
                     const CompletionCallback& callback);
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_TCP_SOCKET_H_