1// Copyright 2014 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// Use the <code>chrome.sockets.tcp</code> API to send and receive data over the 6// network using TCP connections. This API supersedes the TCP functionality 7// previously found in the <code>chrome.socket</code> API. 8namespace sockets.tcp { 9 // The socket properties specified in the <code>create</code> or 10 // <code>update</code> function. Each property is optional. If a property 11 // value is not specified, a default value is used when calling 12 // <code>create</code>, or the existing value if preserved when calling 13 // <code>update</code>. 14 dictionary SocketProperties { 15 // Flag indicating if the socket is left open when the event page of 16 // the application is unloaded (see 17 // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App 18 // Lifecycle</a>). The default value is "false." When the application is 19 // loaded, any sockets previously opened with persistent=true can be fetched 20 // with <code>getSockets</code>. 21 boolean? persistent; 22 23 // An application-defined string associated with the socket. 24 DOMString? name; 25 26 // The size of the buffer used to receive data. The default value is 4096. 27 long? bufferSize; 28 }; 29 30 // Result of <code>create</code> call. 31 dictionary CreateInfo { 32 // The ID of the newly created socket. Note that socket IDs created from 33 // this API are not compatible with socket IDs created from other APIs, such 34 // as the deprecated <code>$(ref:socket)</code> API. 35 long socketId; 36 }; 37 38 // Callback from the <code>create</code> method. 39 // |createInfo| : The result of the socket creation. 40 callback CreateCallback = void (CreateInfo createInfo); 41 42 // Callback from the <code>connect</code> method. 43 // |result| : The result code returned from the underlying network call. 44 // A negative value indicates an error. 45 callback ConnectCallback = void (long result); 46 47 // Callback from the <code>disconnect</code> method. 48 callback DisconnectCallback = void (); 49 50 // Result of the <code>send</code> method. 51 dictionary SendInfo { 52 // The result code returned from the underlying network call. 53 // A negative value indicates an error. 54 long resultCode; 55 56 // The number of bytes sent (if result == 0) 57 long? bytesSent; 58 }; 59 60 // Callback from the <code>send</code> method. 61 // |sendInfo| : Result of the <code>send</code> method. 62 callback SendCallback = void (SendInfo sendInfo); 63 64 // Callback from the <code>close</code> method. 65 callback CloseCallback = void (); 66 67 // Callback from the <code>update</code> method. 68 callback UpdateCallback = void (); 69 70 // Callback from the <code>setPaused</code> method. 71 callback SetPausedCallback = void (); 72 73 // Callback from the <code>setKeepAliveCallback</code> method. 74 // |result| : The result code returned from the underlying network call. 75 // A negative value indicates an error. 76 callback SetKeepAliveCallback = void (long result); 77 78 // Callback from the <code>setNodeDelay</code> method. 79 // |result| : The result code returned from the underlying network call. 80 // A negative value indicates an error. 81 callback SetNoDelayCallback = void (long result); 82 83 dictionary TLSVersionConstraints { 84 // The minimum and maximum acceptable versions of TLS. These will 85 // be <code>ssl3</code>, <code>tls1</code>, <code>tls1.1</code>, 86 // or <code>tls1.2</code>. 87 DOMString? min; 88 DOMString? max; 89 }; 90 91 dictionary SecureOptions { 92 TLSVersionConstraints? tlsVersion; 93 }; 94 95 callback SecureCallback = void (long result); 96 97 // Result of the <code>getInfo</code> method. 98 dictionary SocketInfo { 99 // The socket identifier. 100 long socketId; 101 102 // Flag indicating whether the socket is left open when the application is 103 // suspended (see <code>SocketProperties.persistent</code>). 104 boolean persistent; 105 106 // Application-defined string associated with the socket. 107 DOMString? name; 108 109 // The size of the buffer used to receive data. If no buffer size has been 110 // specified explictly, the value is not provided. 111 long? bufferSize; 112 113 // Flag indicating whether a connected socket blocks its peer from sending 114 // more data (see <code>setPaused</code>). 115 boolean paused; 116 117 // Flag indicating whether the socket is connected to a remote peer. 118 boolean connected; 119 120 // If the underlying socket is connected, contains its local IPv4/6 address. 121 DOMString? localAddress; 122 123 // If the underlying socket is connected, contains its local port. 124 long? localPort; 125 126 // If the underlying socket is connected, contains the peer/ IPv4/6 address. 127 DOMString? peerAddress; 128 129 // If the underlying socket is connected, contains the peer port. 130 long? peerPort; 131 }; 132 133 // Callback from the <code>getInfo</code> method. 134 // |socketInfo| : Object containing the socket information. 135 callback GetInfoCallback = void (SocketInfo socketInfo); 136 137 // Callback from the <code>getSockets</code> method. 138 // |socketInfos| : Array of object containing socket information. 139 callback GetSocketsCallback = void (SocketInfo[] socketInfos); 140 141 // Data from an <code>onReceive</code> event. 142 dictionary ReceiveInfo { 143 // The socket identifier. 144 long socketId; 145 146 // The data received, with a maxium size of <code>bufferSize</code>. 147 ArrayBuffer data; 148 }; 149 150 // Data from an <code>onReceiveError</code> event. 151 dictionary ReceiveErrorInfo { 152 // The socket identifier. 153 long socketId; 154 155 // The result code returned from the underlying network call. 156 long resultCode; 157 }; 158 159 interface Functions { 160 // Creates a TCP socket. 161 // |properties| : The socket properties (optional). 162 // |callback| : Called when the socket has been created. 163 static void create(optional SocketProperties properties, 164 CreateCallback callback); 165 166 // Updates the socket properties. 167 // |socketId| : The socket identifier. 168 // |properties| : The properties to update. 169 // |callback| : Called when the properties are updated. 170 static void update(long socketId, 171 SocketProperties properties, 172 optional UpdateCallback callback); 173 174 // Enables or disables the application from receiving messages from its 175 // peer. The default value is "false". Pausing a socket is typically used 176 // by an application to throttle data sent by its peer. When a socket is 177 // paused, no <code>onReceive</code> event is raised. When a socket is 178 // connected and un-paused, <code>onReceive</code> events are raised again 179 // when messages are received. 180 static void setPaused(long socketId, 181 boolean paused, 182 optional SetPausedCallback callback); 183 184 // Enables or disables the keep-alive functionality for a TCP connection. 185 // |socketId| : The socket identifier. 186 // |enable| : If true, enable keep-alive functionality. 187 // |delay| : Set the delay seconds between the last data packet received 188 // and the first keepalive probe. Default is 0. 189 // |callback| : Called when the setKeepAlive attempt is complete. 190 static void setKeepAlive(long socketId, 191 boolean enable, 192 optional long delay, 193 SetKeepAliveCallback callback); 194 195 // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's 196 // algorithm will be disabled when <code>TCP_NODELAY</code> is set. 197 // |socketId| : The socket identifier. 198 // |noDelay| : If true, disables Nagle's algorithm. 199 // |callback| : Called when the setNoDelay attempt is complete. 200 static void setNoDelay(long socketId, 201 boolean noDelay, 202 SetNoDelayCallback callback); 203 204 // Connects the socket to a remote machine. When the <code>connect</code> 205 // operation completes successfully, <code>onReceive</code> events are 206 // raised when data is received from the peer. If a network error occurs 207 // while the runtime is receiving packets, a <code>onReceiveError</code> 208 // event is raised, at which point no more <code>onReceive</code> event will 209 // be raised for this socket until the <code>resume</code> method is called. 210 // |socketId| : The socket identifier. 211 // |peerAddress| : The address of the remote machine. DNS name, IPv4 and 212 // IPv6 formats are supported. 213 // |peerPort| : The port of the remote machine. 214 // |callback| : Called when the connect attempt is complete. 215 static void connect(long socketId, 216 DOMString peerAddress, 217 long peerPort, 218 ConnectCallback callback); 219 220 // Disconnects the socket. 221 // |socketId| : The socket identifier. 222 // |callback| : Called when the disconnect attempt is complete. 223 static void disconnect(long socketId, 224 optional DisconnectCallback callback); 225 226 // Start a TLS client connection over the connected TCP client socket. 227 // |socketId| : The existing, connected socket to use. 228 // |options| : Constraints and parameters for the TLS connection. 229 // |callback| : Called when the connection attempt is complete. 230 static void secure(long socketId, 231 optional SecureOptions options, 232 SecureCallback callback); 233 234 // Sends data on the given TCP socket. 235 // |socketId| : The socket identifier. 236 // |data| : The data to send. 237 // |callback| : Called when the <code>send</code> operation completes. 238 static void send(long socketId, 239 ArrayBuffer data, 240 SendCallback callback); 241 242 // Closes the socket and releases the address/port the socket is bound to. 243 // Each socket created should be closed after use. The socket id is no 244 // no longer valid as soon at the function is called. However, the socket is 245 // guaranteed to be closed only when the callback is invoked. 246 // |socketId| : The socket identifier. 247 // |callback| : Called when the <code>close</code> operation completes. 248 static void close(long socketId, 249 optional CloseCallback callback); 250 251 // Retrieves the state of the given socket. 252 // |socketId| : The socket identifier. 253 // |callback| : Called when the socket state is available. 254 static void getInfo(long socketId, 255 GetInfoCallback callback); 256 257 // Retrieves the list of currently opened sockets owned by the application. 258 // |callback| : Called when the list of sockets is available. 259 static void getSockets(GetSocketsCallback callback); 260 }; 261 262 interface Events { 263 // Event raised when data has been received for a given socket. 264 // |info| : The event data. 265 static void onReceive(ReceiveInfo info); 266 267 // Event raised when a network error occured while the runtime was waiting 268 // for data on the socket address and port. Once this event is raised, the 269 // socket is set to <code>paused</code> and no more <code>onReceive</code> 270 // events are raised for this socket. 271 // |info| : The event data. 272 static void onReceiveError(ReceiveErrorInfo info); 273 }; 274}; 275