ppapi/cpp/tcp_socket.h

   1 // Copyright 2013 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 #ifndef PPAPI_CPP_TCP_SOCKET_H_
   6 #define PPAPI_CPP_TCP_SOCKET_H_
   7
   8 #include "ppapi/c/ppb_tcp_socket.h"
   9 #include "ppapi/cpp/net_address.h"
  10 #include "ppapi/cpp/pass_ref.h"
  11 #include "ppapi/cpp/resource.h"
  12
  13 namespace pp {
  14
  15 class CompletionCallback;
  16 class InstanceHandle;
  17
  18 template <typename T> class CompletionCallbackWithOutput;
  19
  20 /// The <code>TCPSocket</code> class provides TCP socket operations.
  21 ///
  22 /// Permissions: Apps permission <code>socket</code> with subrule
  23 /// <code>tcp-connect</code> is required for <code>Connect()</code>; subrule
  24 /// <code>tcp-listen</code> is required for <code>Listen()</code>.
  25 /// For more details about network communication permissions, please see:
  26 /// http://developer.chrome.com/apps/app_network.html
  27 class TCPSocket : public Resource {
  28  public:
  29   /// Default constructor for creating an is_null() <code>TCPSocket</code>
  30   /// object.
  31   TCPSocket();
  32
  33   /// A constructor used to create a <code>TCPSocket</code> object.
  34   ///
  35   /// @param[in] instance The instance with which this resource will be
  36   /// associated.
  37   explicit TCPSocket(const InstanceHandle& instance);
  38
  39   /// A constructor used when you have received a <code>PP_Resource</code> as a
  40   /// return value that has had 1 ref added for you.
  41   ///
  42   /// @param[in] resource A <code>PPB_TCPSocket</code> resource.
  43   TCPSocket(PassRef, PP_Resource resource);
  44
  45   /// The copy constructor for <code>TCPSocket</code>.
  46   ///
  47   /// @param[in] other A reference to another <code>TCPSocket</code>.
  48   TCPSocket(const TCPSocket& other);
  49
  50   /// The destructor.
  51   virtual ~TCPSocket();
  52
  53   /// The assignment operator for <code>TCPSocket</code>.
  54   ///
  55   /// @param[in] other A reference to another <code>TCPSocket</code>.
  56   ///
  57   /// @return A reference to this <code>TCPSocket</code> object.
  58   TCPSocket& operator=(const TCPSocket& other);
  59
  60   /// Static function for determining whether the browser supports the
  61   /// <code>PPB_TCPSocket</code> interface.
  62   ///
  63   /// @return true if the interface is available, false otherwise.
  64   static bool IsAvailable();
  65
  66   /// Binds the socket to the given address. The socket must not be bound.
  67   ///
  68   /// @param[in] addr A <code>NetAddress</code> object.
  69   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  70   /// completion.
  71   ///
  72   /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
  73   /// including (but not limited to):
  74   /// - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use.
  75   /// - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid.
  76   int32_t Bind(const NetAddress& addr, const CompletionCallback& callback);
  77
  78   /// Connects the socket to the given address. The socket must not be
  79   /// listening. Binding the socket beforehand is optional.
  80   ///
  81   /// @param[in] addr A <code>NetAddress</code> object.
  82   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  83   /// completion.
  84   ///
  85   /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
  86   /// including (but not limited to):
  87   /// - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
  88   ///   permissions.
  89   /// - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
  90   ///   unreachable.
  91   /// - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
  92   ///   refused.
  93   /// - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
  94   /// - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
  95   ///   out.
  96   ///
  97   /// Since version 1.1, if the socket is listening/connected or has a pending
  98   /// listen/connect request, <code>Connect()</code> will fail without starting
  99   /// a connection attempt. Otherwise, any failure during the connection attempt
 100   /// will cause the socket to be closed.
 101   int32_t Connect(const NetAddress& addr, const CompletionCallback& callback);
 102
 103   /// Gets the local address of the socket, if it is bound.
 104   ///
 105   /// @return A <code>NetAddress</code> object. The object will be null
 106   /// (i.e., is_null() returns true) on failure.
 107   NetAddress GetLocalAddress() const;
 108
 109   /// Gets the remote address of the socket, if it is connected.
 110   ///
 111   /// @return A <code>NetAddress</code> object. The object will be null
 112   /// (i.e., is_null() returns true) on failure.
 113   NetAddress GetRemoteAddress() const;
 114
 115   /// Reads data from the socket. The socket must be connected. It may perform a
 116   /// partial read.
 117   ///
 118   /// <strong>Caveat:</strong> You should be careful about the lifetime of
 119   /// <code>buffer</code>. Typically you will use a
 120   /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime
 121   /// of your class. When your class goes out of scope, the callback factory
 122   /// will not actually cancel the operation, but will rather just skip issuing
 123   /// the callback on your class. This means that if the underlying
 124   /// <code>PPB_TCPSocket</code> resource outlives your class, the browser
 125   /// will still try to write into your buffer when the operation completes.
 126   /// The buffer must be kept valid until then to avoid memory corruption.
 127   /// If you want to release the buffer while the <code>Read()</code> call is
 128   /// still pending, you should call <code>Close()</code> to ensure that the
 129   /// buffer won't be accessed in the future.
 130   ///
 131   /// @param[out] buffer The buffer to store the received data on success. It
 132   /// must be at least as large as <code>bytes_to_read</code>.
 133   /// @param[in] bytes_to_read The number of bytes to read.
 134   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 135   /// completion.
 136   ///
 137   /// @return A non-negative number on success to indicate how many bytes have
 138   /// been read, 0 means that end-of-file was reached; otherwise, an error code
 139   /// from <code>pp_errors.h</code>.
 140   int32_t Read(char* buffer,
 141                int32_t bytes_to_read,
 142                const CompletionCallback& callback);
 143
 144   /// Writes data to the socket. The socket must be connected. It may perform a
 145   /// partial write.
 146   ///
 147   /// @param[in] buffer The buffer containing the data to write.
 148   /// @param[in] bytes_to_write The number of bytes to write.
 149   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 150   /// completion.
 151   ///
 152   /// @return A non-negative number on success to indicate how many bytes have
 153   /// been written; otherwise, an error code from <code>pp_errors.h</code>.
 154   int32_t Write(const char* buffer,
 155                 int32_t bytes_to_write,
 156                 const CompletionCallback& callback);
 157
 158   /// Starts listening. The socket must be bound and not connected.
 159   ///
 160   /// @param[in] backlog A hint to determine the maximum length to which the
 161   /// queue of pending connections may grow.
 162   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 163   /// completion.
 164   ///
 165   /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
 166   /// including (but not limited to):
 167   /// - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
 168   ///   permissions.
 169   /// - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already
 170   ///   listening on the same port.
 171   int32_t Listen(int32_t backlog,
 172                  const CompletionCallback& callback);
 173
 174   /// Accepts a connection. The socket must be listening.
 175   ///
 176   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 177   /// called upon completion.
 178   ///
 179   /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
 180   /// including (but not limited to):
 181   /// - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted.
 182   int32_t Accept(const CompletionCallbackWithOutput<TCPSocket>& callback);
 183
 184   /// Cancels all pending operations and closes the socket. Any pending
 185   /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if
 186   /// pending IO was interrupted. After a call to this method, no output buffer
 187   /// pointers passed into previous <code>Read()</code> or <code>Accept()</code>
 188   /// calls will be accessed. It is not valid to call <code>Connect()</code> or
 189   /// <code>Listen()</code> again.
 190   ///
 191   /// The socket is implicitly closed if it is destroyed, so you are not
 192   /// required to call this method.
 193   void Close();
 194
 195   /// Sets a socket option on the TCP socket.
 196   /// Please see the <code>PP_TCPSocket_Option</code> description for option
 197   /// names, value types and allowed values.
 198   ///
 199   /// @param[in] name The option to set.
 200   /// @param[in] value The option value to set.
 201   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 202   /// completion.
 203   ///
 204   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 205   int32_t SetOption(PP_TCPSocket_Option name,
 206                     const Var& value,
 207                     const CompletionCallback& callback);
 208 };
 209
 210 }  // namespace pp
 211
 212 #endif  // PPAPI_CPP_TCP_SOCKET_H_