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 6 /** 7 * This file defines the <code>PPB_TCPSocket</code> interface. 8 */ 9 10 label Chrome { 11 M29 = 1.0, 12 M31 = 1.1 13 }; 14 15 /** 16 * Option names used by <code>SetOption()</code>. 17 */ 18 [assert_size(4)] 19 enum PP_TCPSocket_Option { 20 /** 21 * Disables coalescing of small writes to make TCP segments, and instead 22 * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>. 23 * This option can only be set after a successful <code>Connect()</code> call. 24 */ 25 PP_TCPSOCKET_OPTION_NO_DELAY = 0, 26 27 /** 28 * Specifies the total per-socket buffer space reserved for sends. Value's 29 * type should be <code>PP_VARTYPE_INT32</code>. 30 * This option can only be set after a successful <code>Connect()</code> call. 31 * 32 * Note: This is only treated as a hint for the browser to set the buffer 33 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 34 * guarantee it will conform to the size. 35 */ 36 PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1, 37 38 /** 39 * Specifies the total per-socket buffer space reserved for receives. Value's 40 * type should be <code>PP_VARTYPE_INT32</code>. 41 * This option can only be set after a successful <code>Connect()</code> call. 42 * 43 * Note: This is only treated as a hint for the browser to set the buffer 44 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 45 * guarantee it will conform to the size. 46 */ 47 PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2 48 }; 49 50 /** 51 * The <code>PPB_TCPSocket</code> interface provides TCP socket operations. 52 * 53 * Permissions: Apps permission <code>socket</code> with subrule 54 * <code>tcp-connect</code> is required for <code>Connect()</code>; subrule 55 * <code>tcp-listen</code> is required for <code>Listen()</code>. 56 * For more details about network communication permissions, please see: 57 * http://developer.chrome.com/apps/app_network.html 58 */ 59 interface PPB_TCPSocket { 60 /** 61 * Creates a TCP socket resource. 62 * 63 * @param[in] instance A <code>PP_Instance</code> identifying one instance of 64 * a module. 65 * 66 * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0 67 * on failure. 68 */ 69 PP_Resource Create([in] PP_Instance instance); 70 71 /** 72 * Determines if a given resource is a TCP socket. 73 * 74 * @param[in] resource A <code>PP_Resource</code> to check. 75 * 76 * @return <code>PP_TRUE</code> if the input is a 77 * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise. 78 */ 79 PP_Bool IsTCPSocket([in] PP_Resource resource); 80 81 /** 82 * Binds the socket to the given address. The socket must not be bound. 83 * 84 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 85 * socket. 86 * @param[in] addr A <code>PPB_NetAddress</code> resource. 87 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 88 * completion. 89 * 90 * @return An int32_t containing an error code from <code>pp_errors.h</code>, 91 * including (but not limited to): 92 * - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use. 93 * - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid. 94 */ 95 [version=1.1] 96 int32_t Bind([in] PP_Resource tcp_socket, 97 [in] PP_Resource addr, 98 [in] PP_CompletionCallback callback); 99 100 /** 101 * Connects the socket to the given address. The socket must not be listening. 102 * Binding the socket beforehand is optional. 103 * 104 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 105 * socket. 106 * @param[in] addr A <code>PPB_NetAddress</code> resource. 107 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 108 * completion. 109 * 110 * @return An int32_t containing an error code from <code>pp_errors.h</code>, 111 * including (but not limited to): 112 * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required 113 * permissions. 114 * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is 115 * unreachable. 116 * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was 117 * refused. 118 * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed. 119 * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed 120 * out. 121 * 122 * Since version 1.1, if the socket is listening/connected or has a pending 123 * listen/connect request, <code>Connect()</code> will fail without starting a 124 * connection attempt; otherwise, any failure during the connection attempt 125 * will cause the socket to be closed. 126 */ 127 int32_t Connect([in] PP_Resource tcp_socket, 128 [in] PP_Resource addr, 129 [in] PP_CompletionCallback callback); 130 131 /** 132 * Gets the local address of the socket, if it is bound. 133 * 134 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 135 * socket. 136 * 137 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 138 */ 139 PP_Resource GetLocalAddress([in] PP_Resource tcp_socket); 140 141 /** 142 * Gets the remote address of the socket, if it is connected. 143 * 144 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 145 * socket. 146 * 147 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 148 */ 149 PP_Resource GetRemoteAddress([in] PP_Resource tcp_socket); 150 151 /** 152 * Reads data from the socket. The socket must be connected. It may perform a 153 * partial read. 154 * 155 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 156 * socket. 157 * @param[out] buffer The buffer to store the received data on success. It 158 * must be at least as large as <code>bytes_to_read</code>. 159 * @param[in] bytes_to_read The number of bytes to read. 160 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 161 * completion. 162 * 163 * @return A non-negative number on success to indicate how many bytes have 164 * been read, 0 means that end-of-file was reached; otherwise, an error code 165 * from <code>pp_errors.h</code>. 166 */ 167 int32_t Read([in] PP_Resource tcp_socket, 168 [out] str_t buffer, 169 [in] int32_t bytes_to_read, 170 [in] PP_CompletionCallback callback); 171 172 /** 173 * Writes data to the socket. The socket must be connected. It may perform a 174 * partial write. 175 * 176 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 177 * socket. 178 * @param[in] buffer The buffer containing the data to write. 179 * @param[in] bytes_to_write The number of bytes to write. 180 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 181 * completion. 182 * 183 * @return A non-negative number on success to indicate how many bytes have 184 * been written; otherwise, an error code from <code>pp_errors.h</code>. 185 */ 186 int32_t Write([in] PP_Resource tcp_socket, 187 [in] str_t buffer, 188 [in] int32_t bytes_to_write, 189 [in] PP_CompletionCallback callback); 190 /** 191 * Starts listening. The socket must be bound and not connected. 192 * 193 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 194 * socket. 195 * @param[in] backlog A hint to determine the maximum length to which the 196 * queue of pending connections may grow. 197 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 198 * completion. 199 * 200 * @return An int32_t containing an error code from <code>pp_errors.h</code>, 201 * including (but not limited to): 202 * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required 203 * permissions. 204 * - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already listening 205 * on the same port. 206 */ 207 [version=1.1] 208 int32_t Listen([in] PP_Resource tcp_socket, 209 [in] int32_t backlog, 210 [in] PP_CompletionCallback callback); 211 212 /** 213 * Accepts a connection. The socket must be listening. 214 * 215 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 216 * socket. 217 * @param[out] accepted_tcp_socket Stores the accepted TCP socket on success. 218 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 219 * completion. 220 * 221 * @return An int32_t containing an error code from <code>pp_errors.h</code>, 222 * including (but not limited to): 223 * - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted. 224 */ 225 [version=1.1] 226 int32_t Accept([in] PP_Resource tcp_socket, 227 [out] PP_Resource accepted_tcp_socket, 228 [in] PP_CompletionCallback callback); 229 230 /** 231 * Cancels all pending operations and closes the socket. Any pending callbacks 232 * will still run, reporting <code>PP_ERROR_ABORTED</code> if pending IO was 233 * interrupted. After a call to this method, no output buffer pointers passed 234 * into previous <code>Read()</code> or <code>Accept()</code> calls will be 235 * accessed. It is not valid to call <code>Connect()</code> or 236 * <code>Listen()</code> again. 237 * 238 * The socket is implicitly closed if it is destroyed, so you are not required 239 * to call this method. 240 * 241 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 242 * socket. 243 */ 244 void Close([in] PP_Resource tcp_socket); 245 246 /** 247 * Sets a socket option on the TCP socket. 248 * Please see the <code>PP_TCPSocket_Option</code> description for option 249 * names, value types and allowed values. 250 * 251 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 252 * socket. 253 * @param[in] name The option to set. 254 * @param[in] value The option value to set. 255 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 256 * completion. 257 * 258 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 259 */ 260 int32_t SetOption([in] PP_Resource tcp_socket, 261 [in] PP_TCPSocket_Option name, 262 [in] PP_Var value, 263 [in] PP_CompletionCallback callback); 264 }; 265
