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 /// The <code>TCPSocket</code> class provides TCP socket operations.
  19 ///
  20 /// Permissions: Apps permission <code>socket</code> with subrule
  21 /// <code>tcp-connect</code> is required for <code>Connect()</code>.
  22 /// For more details about network communication permissions, please see:
  23 /// http://developer.chrome.com/apps/app_network.html
  24 class TCPSocket : public Resource {
  25  public:
  26   /// Default constructor for creating an is_null() <code>TCPSocket</code>
  27   /// object.
  28   TCPSocket();
  29
  30   /// A constructor used to create a <code>TCPSocket</code> object.
  31   ///
  32   /// @param[in] instance The instance with which this resource will be
  33   /// associated.
  34   explicit TCPSocket(const InstanceHandle& instance);
  35
  36   /// A constructor used when you have received a <code>PP_Resource</code> as a
  37   /// return value that has had 1 ref added for you.
  38   ///
  39   /// @param[in] resource A <code>PPB_TCPSocket</code> resource.
  40   TCPSocket(PassRef, PP_Resource resource);
  41
  42   /// The copy constructor for <code>TCPSocket</code>.
  43   ///
  44   /// @param[in] other A reference to another <code>TCPSocket</code>.
  45   TCPSocket(const TCPSocket& other);
  46
  47   /// The destructor.
  48   virtual ~TCPSocket();
  49
  50   /// The assignment operator for <code>TCPSocket</code>.
  51   ///
  52   /// @param[in] other A reference to another <code>TCPSocket</code>.
  53   ///
  54   /// @return A reference to this <code>TCPSocket</code> object.
  55   TCPSocket& operator=(const TCPSocket& other);
  56
  57   /// Static function for determining whether the browser supports the
  58   /// <code>PPB_TCPSocket</code> interface.
  59   ///
  60   /// @return true if the interface is available, false otherwise.
  61   static bool IsAvailable();
  62
  63   /// Connects the socket to the given address.
  64   ///
  65   /// @param[in] addr A <code>NetAddress</code> object.
  66   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  67   /// completion.
  68   ///
  69   /// @return An int32_t containing an error code from <code>pp_errors.h</code>,
  70   /// including (but not limited to):
  71   /// - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
  72   ///   permissions.
  73   /// - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
  74   ///   unreachable.
  75   /// - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
  76   ///   refused.
  77   /// - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
  78   /// - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
  79   ///   out.
  80   int32_t Connect(const NetAddress& addr,
  81                   const CompletionCallback& callback);
  82
  83   /// Gets the local address of the socket, if it is connected.
  84   ///
  85   /// @return A <code>NetAddress</code> object. The object will be null
  86   /// (i.e., is_null() returns true) on failure.
  87   NetAddress GetLocalAddress() const;
  88
  89   /// Gets the remote address of the socket, if it is connected.
  90   ///
  91   /// @return A <code>NetAddress</code> object. The object will be null
  92   /// (i.e., is_null() returns true) on failure.
  93   NetAddress GetRemoteAddress() const;
  94
  95   /// Reads data from the socket. The socket must be connected. It may perform a
  96   /// partial read.
  97   ///
  98   /// <strong>Caveat:</strong> You should be careful about the lifetime of
  99   /// <code>buffer</code>. Typically you will use a
 100   /// <code>CompletionCallbackFactory</code> to scope callbacks to the lifetime
 101   /// of your class. When your class goes out of scope, the callback factory
 102   /// will not actually cancel the operation, but will rather just skip issuing
 103   /// the callback on your class. This means that if the underlying
 104   /// <code>PPB_TCPSocket</code> resource outlives your class, the browser
 105   /// will still try to write into your buffer when the operation completes.
 106   /// The buffer must be kept valid until then to avoid memory corruption.
 107   /// If you want to release the buffer while the <code>Read()</code> call is
 108   /// still pending, you should call <code>Close()</code> to ensure that the
 109   /// buffer won't be accessed in the future.
 110   ///
 111   /// @param[out] buffer The buffer to store the received data on success. It
 112   /// must be at least as large as <code>bytes_to_read</code>.
 113   /// @param[in] bytes_to_read The number of bytes to read.
 114   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 115   /// completion.
 116   ///
 117   /// @return A non-negative number on success to indicate how many bytes have
 118   /// been read, 0 means that end-of-file was reached; otherwise, an error code
 119   /// from <code>pp_errors.h</code>.
 120   int32_t Read(char* buffer,
 121                int32_t bytes_to_read,
 122                const CompletionCallback& callback);
 123
 124   /// Writes data to the socket. The socket must be connected. It may perform a
 125   /// partial write.
 126   ///
 127   /// @param[in] buffer The buffer containing the data to write.
 128   /// @param[in] bytes_to_write The number of bytes to write.
 129   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 130   /// completion.
 131   ///
 132   /// @return A non-negative number on success to indicate how many bytes have
 133   /// been written; otherwise, an error code from <code>pp_errors.h</code>.
 134   int32_t Write(const char* buffer,
 135                 int32_t bytes_to_write,
 136                 const CompletionCallback& callback);
 137
 138   /// Cancels all pending reads and writes and disconnects the socket. Any
 139   /// pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code>
 140   /// if pending IO was interrupted. After a call to this method, no output
 141   /// buffer pointers passed into previous <code>Read()</code> calls will be
 142   /// accessed. It is not valid to call <code>Connect()</code> again.
 143   ///
 144   /// The socket is implicitly closed if it is destroyed, so you are not
 145   /// required to call this method.
 146   void Close();
 147
 148   /// Sets a socket option on the TCP socket.
 149   /// Please see the <code>PP_TCPSocket_Option</code> description for option
 150   /// names, value types and allowed values.
 151   ///
 152   /// @param[in] name The option to set.
 153   /// @param[in] value The option value to set.
 154   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 155   /// completion.
 156   ///
 157   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 158   ////
 159   int32_t SetOption(PP_TCPSocket_Option name,
 160                     const Var& value,
 161                     const CompletionCallback& callback);
 162 };
 163
 164 }  // namespace pp
 165
 166 #endif  // PPAPI_CPP_TCP_SOCKET_H_