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 Sat Jun 22 11:17:34 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 PPB_TCPSOCKET_INTERFACE_1_0 21 22 /** 23 * @file 24 * This file defines the <code>PPB_TCPSocket</code> interface. 25 */ 26 27 28 /** 29 * @addtogroup Enums 30 * @{ 31 */ 32 /** 33 * Option names used by <code>SetOption()</code>. 34 */ 35 typedef enum { 36 /** 37 * Disables coalescing of small writes to make TCP segments, and instead 38 * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>. 39 * This option can only be set after a successful <code>Connect()</code> call. 40 */ 41 PP_TCPSOCKET_OPTION_NO_DELAY = 0, 42 /** 43 * Specifies the total per-socket buffer space reserved for sends. Value's 44 * type should be <code>PP_VARTYPE_INT32</code>. 45 * This option can only be set after a successful <code>Connect()</code> call. 46 * 47 * Note: This is only treated as a hint for the browser to set the buffer 48 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 49 * guarantee it will conform to the size. 50 */ 51 PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1, 52 /** 53 * Specifies the total per-socket buffer space reserved for receives. Value's 54 * type should be <code>PP_VARTYPE_INT32</code>. 55 * This option can only be set after a successful <code>Connect()</code> call. 56 * 57 * Note: This is only treated as a hint for the browser to set the buffer 58 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 59 * guarantee it will conform to the size. 60 */ 61 PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2 62 } PP_TCPSocket_Option; 63 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TCPSocket_Option, 4); 64 /** 65 * @} 66 */ 67 68 /** 69 * @addtogroup Interfaces 70 * @{ 71 */ 72 /** 73 * The <code>PPB_TCPSocket</code> interface provides TCP socket operations. 74 * 75 * Permissions: Apps permission <code>socket</code> with subrule 76 * <code>tcp-connect</code> is required for <code>Connect()</code>. 77 * For more details about network communication permissions, please see: 78 * http://developer.chrome.com/apps/app_network.html 79 */ 80 struct PPB_TCPSocket_1_0 { 81 /** 82 * Creates a TCP socket resource. 83 * 84 * @param[in] instance A <code>PP_Instance</code> identifying one instance of 85 * a module. 86 * 87 * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0 88 * on failure. 89 */ 90 PP_Resource (*Create)(PP_Instance instance); 91 /** 92 * Determines if a given resource is a TCP socket. 93 * 94 * @param[in] resource A <code>PP_Resource</code> to check. 95 * 96 * @return <code>PP_TRUE</code> if the input is a 97 * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise. 98 */ 99 PP_Bool (*IsTCPSocket)(PP_Resource resource); 100 /** 101 * Connects the socket to the given address. 102 * 103 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 104 * socket. 105 * @param[in] addr A <code>PPB_NetAddress</code> resource. 106 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 107 * completion. 108 * 109 * @return An int32_t containing an error code from <code>pp_errors.h</code>, 110 * including (but not limited to): 111 * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required 112 * permissions. 113 * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is 114 * unreachable. 115 * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was 116 * refused. 117 * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed. 118 * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed 119 * out. 120 */ 121 int32_t (*Connect)(PP_Resource tcp_socket, 122 PP_Resource addr, 123 struct PP_CompletionCallback callback); 124 /** 125 * Gets the local address of the socket, if it is connected. 126 * 127 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 128 * socket. 129 * 130 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 131 */ 132 PP_Resource (*GetLocalAddress)(PP_Resource tcp_socket); 133 /** 134 * Gets the remote address of the socket, if it is connected. 135 * 136 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 137 * socket. 138 * 139 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 140 */ 141 PP_Resource (*GetRemoteAddress)(PP_Resource tcp_socket); 142 /** 143 * Reads data from the socket. The socket must be connected. It may perform a 144 * partial read. 145 * 146 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 147 * socket. 148 * @param[out] buffer The buffer to store the received data on success. It 149 * must be at least as large as <code>bytes_to_read</code>. 150 * @param[in] bytes_to_read The number of bytes to read. 151 * @param[in] callback A <code>PP_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 read, 0 means that end-of-file was reached; otherwise, an error code 156 * from <code>pp_errors.h</code>. 157 */ 158 int32_t (*Read)(PP_Resource tcp_socket, 159 char* buffer, 160 int32_t bytes_to_read, 161 struct PP_CompletionCallback callback); 162 /** 163 * Writes data to the socket. The socket must be connected. It may perform a 164 * partial write. 165 * 166 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 167 * socket. 168 * @param[in] buffer The buffer containing the data to write. 169 * @param[in] bytes_to_write The number of bytes to write. 170 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 171 * completion. 172 * 173 * @return A non-negative number on success to indicate how many bytes have 174 * been written; otherwise, an error code from <code>pp_errors.h</code>. 175 */ 176 int32_t (*Write)(PP_Resource tcp_socket, 177 const char* buffer, 178 int32_t bytes_to_write, 179 struct PP_CompletionCallback callback); 180 /** 181 * Cancels all pending reads and writes and disconnects the socket. Any 182 * pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> 183 * if pending IO was interrupted. After a call to this method, no output 184 * buffer pointers passed into previous <code>Read()</code> calls will be 185 * accessed. It is not valid to call <code>Connect()</code> again. 186 * 187 * The socket is implicitly closed if it is destroyed, so you are not required 188 * to call this method. 189 * 190 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 191 * socket. 192 */ 193 void (*Close)(PP_Resource tcp_socket); 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] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 200 * socket. 201 * @param[in] name The option to set. 202 * @param[in] value The option value to set. 203 * @param[in] callback A <code>PP_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 */ 208 int32_t (*SetOption)(PP_Resource tcp_socket, 209 PP_TCPSocket_Option name, 210 struct PP_Var value, 211 struct PP_CompletionCallback callback); 212 }; 213 214 typedef struct PPB_TCPSocket_1_0 PPB_TCPSocket; 215 /** 216 * @} 217 */ 218 219 #endif /* PPAPI_C_PPB_TCP_SOCKET_H_ */ 220 221
