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_ 213
