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 [generate_thunk] 11 12 label Chrome { 13 M29 = 1.0 14 }; 15 16 /** 17 * Option names used by <code>SetOption()</code>. 18 */ 19 [assert_size(4)] 20 enum PP_TCPSocket_Option { 21 /** 22 * Disables coalescing of small writes to make TCP segments, and instead 23 * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>. 24 * This option can only be set after a successful <code>Connect()</code> call. 25 */ 26 PP_TCPSOCKET_OPTION_NO_DELAY = 0, 27 28 /** 29 * Specifies the total per-socket buffer space reserved for sends. Value's 30 * type should be <code>PP_VARTYPE_INT32</code>. 31 * This option can only be set after a successful <code>Connect()</code> call. 32 * 33 * Note: This is only treated as a hint for the browser to set the buffer 34 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 35 * guarantee it will conform to the size. 36 */ 37 PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1, 38 39 /** 40 * Specifies the total per-socket buffer space reserved for receives. Value's 41 * type should be <code>PP_VARTYPE_INT32</code>. 42 * This option can only be set after a successful <code>Connect()</code> call. 43 * 44 * Note: This is only treated as a hint for the browser to set the buffer 45 * size. Even if <code>SetOption()</code> succeeds, the browser doesn't 46 * guarantee it will conform to the size. 47 */ 48 PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2 49 }; 50 51 /** 52 * The <code>PPB_TCPSocket</code> interface provides TCP socket operations. 53 * 54 * Permissions: Apps permission <code>socket</code> with subrule 55 * <code>tcp-connect</code> is required for <code>Connect()</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 * Connects the socket to the given address. 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_NOACCESS</code>: the caller doesn't have required 93 * permissions. 94 * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is 95 * unreachable. 96 * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was 97 * refused. 98 * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed. 99 * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed 100 * out. 101 */ 102 int32_t Connect([in] PP_Resource tcp_socket, 103 [in] PP_Resource addr, 104 [in] PP_CompletionCallback callback); 105 106 /** 107 * Gets the local address of the socket, if it is connected. 108 * 109 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 110 * socket. 111 * 112 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 113 */ 114 PP_Resource GetLocalAddress([in] PP_Resource tcp_socket); 115 116 /** 117 * Gets the remote address of the socket, if it is connected. 118 * 119 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 120 * socket. 121 * 122 * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure. 123 */ 124 PP_Resource GetRemoteAddress([in] PP_Resource tcp_socket); 125 126 /** 127 * Reads data from the socket. The socket must be connected. It may perform a 128 * partial read. 129 * 130 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 131 * socket. 132 * @param[out] buffer The buffer to store the received data on success. It 133 * must be at least as large as <code>bytes_to_read</code>. 134 * @param[in] bytes_to_read The number of bytes to read. 135 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 136 * completion. 137 * 138 * @return A non-negative number on success to indicate how many bytes have 139 * been read, 0 means that end-of-file was reached; otherwise, an error code 140 * from <code>pp_errors.h</code>. 141 */ 142 int32_t Read([in] PP_Resource tcp_socket, 143 [out] str_t buffer, 144 [in] int32_t bytes_to_read, 145 [in] PP_CompletionCallback callback); 146 147 /** 148 * Writes data to the socket. The socket must be connected. It may perform a 149 * partial write. 150 * 151 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 152 * socket. 153 * @param[in] buffer The buffer containing the data to write. 154 * @param[in] bytes_to_write The number of bytes to write. 155 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 156 * completion. 157 * 158 * @return A non-negative number on success to indicate how many bytes have 159 * been written; otherwise, an error code from <code>pp_errors.h</code>. 160 */ 161 int32_t Write([in] PP_Resource tcp_socket, 162 [in] str_t buffer, 163 [in] int32_t bytes_to_write, 164 [in] PP_CompletionCallback callback); 165 166 /** 167 * Cancels all pending reads and writes and disconnects the socket. Any 168 * pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> 169 * if pending IO was interrupted. After a call to this method, no output 170 * buffer pointers passed into previous <code>Read()</code> calls will be 171 * accessed. It is not valid to call <code>Connect()</code> again. 172 * 173 * The socket is implicitly closed if it is destroyed, so you are not required 174 * to call this method. 175 * 176 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 177 * socket. 178 */ 179 void Close([in] PP_Resource tcp_socket); 180 181 /** 182 * Sets a socket option on the TCP socket. 183 * Please see the <code>PP_TCPSocket_Option</code> description for option 184 * names, value types and allowed values. 185 * 186 * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP 187 * socket. 188 * @param[in] name The option to set. 189 * @param[in] value The option value to set. 190 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 191 * completion. 192 * 193 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 194 */ 195 int32_t SetOption([in] PP_Resource tcp_socket, 196 [in] PP_TCPSocket_Option name, 197 [in] PP_Var value, 198 [in] PP_CompletionCallback callback); 199 }; 200
