Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 18 | template <typename T> class CompletionCallbackWithOutput; |
| 19 | |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 20 | /// The <code>TCPSocket</code> class provides TCP socket operations. |
| 21 | /// |
| 22 | /// Permissions: Apps permission <code>socket</code> with subrule |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 23 | /// <code>tcp-connect</code> is required for <code>Connect()</code>; subrule |
| 24 | /// <code>tcp-listen</code> is required for <code>Listen()</code>. |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 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. |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 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); |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 102 | |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 103 | /// Gets the local address of the socket, if it is bound. |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | 68043e1 | 2013-09-26 13:24:57 +0100 | [diff] [blame] | 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. |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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>. |
Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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_ |