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