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