diff options
Diffstat (limited to 'chromium/extensions/common/api/sockets_tcp.idl')
| -rw-r--r-- | chromium/extensions/common/api/sockets_tcp.idl | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/chromium/extensions/common/api/sockets_tcp.idl b/chromium/extensions/common/api/sockets_tcp.idl new file mode 100644 index 00000000000..2dffa1729b1 --- /dev/null +++ b/chromium/extensions/common/api/sockets_tcp.idl @@ -0,0 +1,273 @@ +// Copyright 2014 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +// Use the <code>chrome.sockets.tcp</code> API to send and receive data over the +// network using TCP connections. This API supersedes the TCP functionality +// previously found in the <code>chrome.socket</code> API. +namespace sockets.tcp { + // The socket properties specified in the <code>create</code> or + // <code>update</code> function. Each property is optional. If a property + // value is not specified, a default value is used when calling + // <code>create</code>, or the existing value if preserved when calling + // <code>update</code>. + dictionary SocketProperties { + // Flag indicating if the socket is left open when the event page of + // the application is unloaded (see + // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App + // Lifecycle</a>). The default value is "false." When the application is + // loaded, any sockets previously opened with persistent=true can be fetched + // with <code>getSockets</code>. + boolean? persistent; + + // An application-defined string associated with the socket. + DOMString? name; + + // The size of the buffer used to receive data. The default value is 4096. + long? bufferSize; + }; + + // Result of <code>create</code> call. + dictionary CreateInfo { + // The ID of the newly created socket. Note that socket IDs created from + // this API are not compatible with socket IDs created from other APIs, such + // as the deprecated <code>$(ref:socket)</code> API. + long socketId; + }; + + // Callback from the <code>create</code> method. + // |createInfo| : The result of the socket creation. + callback CreateCallback = void (CreateInfo createInfo); + + // Callback from the <code>connect</code> method. + // |result| : The result code returned from the underlying network call. + // A negative value indicates an error. + callback ConnectCallback = void (long result); + + // Callback from the <code>disconnect</code> method. + callback DisconnectCallback = void (); + + // Result of the <code>send</code> method. + dictionary SendInfo { + // The result code returned from the underlying network call. + // A negative value indicates an error. + long resultCode; + + // The number of bytes sent (if result == 0) + long? bytesSent; + }; + + // Callback from the <code>send</code> method. + // |sendInfo| : Result of the <code>send</code> method. + callback SendCallback = void (SendInfo sendInfo); + + // Callback from the <code>close</code> method. + callback CloseCallback = void (); + + // Callback from the <code>update</code> method. + callback UpdateCallback = void (); + + // Callback from the <code>setPaused</code> method. + callback SetPausedCallback = void (); + + // Callback from the <code>setKeepAliveCallback</code> method. + // |result| : The result code returned from the underlying network call. + // A negative value indicates an error. + callback SetKeepAliveCallback = void (long result); + + // Callback from the <code>setNodeDelay</code> method. + // |result| : The result code returned from the underlying network call. + // A negative value indicates an error. + callback SetNoDelayCallback = void (long result); + + dictionary TLSVersionConstraints { + // The minimum and maximum acceptable versions of TLS. These will + // be <code>tls1</code>, <code>tls1.1</code>, or <code>tls1.2</code>. + DOMString? min; + DOMString? max; + }; + + dictionary SecureOptions { + TLSVersionConstraints? tlsVersion; + }; + + callback SecureCallback = void (long result); + + // Result of the <code>getInfo</code> method. + dictionary SocketInfo { + // The socket identifier. + long socketId; + + // Flag indicating whether the socket is left open when the application is + // suspended (see <code>SocketProperties.persistent</code>). + boolean persistent; + + // Application-defined string associated with the socket. + DOMString? name; + + // The size of the buffer used to receive data. If no buffer size has been + // specified explictly, the value is not provided. + long? bufferSize; + + // Flag indicating whether a connected socket blocks its peer from sending + // more data (see <code>setPaused</code>). + boolean paused; + + // Flag indicating whether the socket is connected to a remote peer. + boolean connected; + + // If the underlying socket is connected, contains its local IPv4/6 address. + DOMString? localAddress; + + // If the underlying socket is connected, contains its local port. + long? localPort; + + // If the underlying socket is connected, contains the peer/ IPv4/6 address. + DOMString? peerAddress; + + // If the underlying socket is connected, contains the peer port. + long? peerPort; + }; + + // Callback from the <code>getInfo</code> method. + // |socketInfo| : Object containing the socket information. + callback GetInfoCallback = void (SocketInfo socketInfo); + + // Callback from the <code>getSockets</code> method. + // |socketInfos| : Array of object containing socket information. + callback GetSocketsCallback = void (SocketInfo[] socketInfos); + + // Data from an <code>onReceive</code> event. + dictionary ReceiveInfo { + // The socket identifier. + long socketId; + + // The data received, with a maxium size of <code>bufferSize</code>. + ArrayBuffer data; + }; + + // Data from an <code>onReceiveError</code> event. + dictionary ReceiveErrorInfo { + // The socket identifier. + long socketId; + + // The result code returned from the underlying network call. + long resultCode; + }; + + interface Functions { + // Creates a TCP socket. + // |properties| : The socket properties (optional). + // |callback| : Called when the socket has been created. + static void create(optional SocketProperties properties, + CreateCallback callback); + + // Updates the socket properties. + // |socketId| : The socket identifier. + // |properties| : The properties to update. + // |callback| : Called when the properties are updated. + static void update(long socketId, + SocketProperties properties, + optional UpdateCallback callback); + + // Enables or disables the application from receiving messages from its + // peer. The default value is "false". Pausing a socket is typically used + // by an application to throttle data sent by its peer. When a socket is + // paused, no <code>onReceive</code> event is raised. When a socket is + // connected and un-paused, <code>onReceive</code> events are raised again + // when messages are received. + static void setPaused(long socketId, + boolean paused, + optional SetPausedCallback callback); + + // Enables or disables the keep-alive functionality for a TCP connection. + // |socketId| : The socket identifier. + // |enable| : If true, enable keep-alive functionality. + // |delay| : Set the delay seconds between the last data packet received + // and the first keepalive probe. Default is 0. + // |callback| : Called when the setKeepAlive attempt is complete. + static void setKeepAlive(long socketId, + boolean enable, + optional long delay, + SetKeepAliveCallback callback); + + // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's + // algorithm will be disabled when <code>TCP_NODELAY</code> is set. + // |socketId| : The socket identifier. + // |noDelay| : If true, disables Nagle's algorithm. + // |callback| : Called when the setNoDelay attempt is complete. + static void setNoDelay(long socketId, + boolean noDelay, + SetNoDelayCallback callback); + + // Connects the socket to a remote machine. When the <code>connect</code> + // operation completes successfully, <code>onReceive</code> events are + // raised when data is received from the peer. If a network error occurs + // while the runtime is receiving packets, a <code>onReceiveError</code> + // event is raised, at which point no more <code>onReceive</code> event will + // be raised for this socket until the <code>resume</code> method is called. + // |socketId| : The socket identifier. + // |peerAddress| : The address of the remote machine. DNS name, IPv4 and + // IPv6 formats are supported. + // |peerPort| : The port of the remote machine. + // |callback| : Called when the connect attempt is complete. + static void connect(long socketId, + DOMString peerAddress, + long peerPort, + ConnectCallback callback); + + // Disconnects the socket. + // |socketId| : The socket identifier. + // |callback| : Called when the disconnect attempt is complete. + static void disconnect(long socketId, + optional DisconnectCallback callback); + + // Start a TLS client connection over the connected TCP client socket. + // |socketId| : The existing, connected socket to use. + // |options| : Constraints and parameters for the TLS connection. + // |callback| : Called when the connection attempt is complete. + static void secure(long socketId, + optional SecureOptions options, + SecureCallback callback); + + // Sends data on the given TCP socket. + // |socketId| : The socket identifier. + // |data| : The data to send. + // |callback| : Called when the <code>send</code> operation completes. + static void send(long socketId, + ArrayBuffer data, + SendCallback callback); + + // Closes the socket and releases the address/port the socket is bound to. + // Each socket created should be closed after use. The socket id is no + // no longer valid as soon at the function is called. However, the socket is + // guaranteed to be closed only when the callback is invoked. + // |socketId| : The socket identifier. + // |callback| : Called when the <code>close</code> operation completes. + static void close(long socketId, + optional CloseCallback callback); + + // Retrieves the state of the given socket. + // |socketId| : The socket identifier. + // |callback| : Called when the socket state is available. + static void getInfo(long socketId, + GetInfoCallback callback); + + // Retrieves the list of currently opened sockets owned by the application. + // |callback| : Called when the list of sockets is available. + static void getSockets(GetSocketsCallback callback); + }; + + interface Events { + // Event raised when data has been received for a given socket. + // |info| : The event data. + static void onReceive(ReceiveInfo info); + + // Event raised when a network error occured while the runtime was waiting + // for data on the socket address and port. Once this event is raised, the + // socket is set to <code>paused</code> and no more <code>onReceive</code> + // events are raised for this socket. + // |info| : The event data. + static void onReceiveError(ReceiveErrorInfo info); + }; +}; |