extensions/common/api/sockets_tcp.idl - chromium/src - Git at Google

 // Copyright 2014 The Chromium Authors
 // 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);

   // DNS resolution preferences. The default is <code>any</code> and uses the
   // current OS config which may return IPv4 or IPv6. <code>ipv4</code> forces
   // IPv4, and <code>ipv6</code> forces IPv6.
   enum DnsQueryType { any, ipv4, ipv6 };

   // 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. Supported values are
     // <code>tls1.2</code> or <code>tls1.3</code>.
     //
     // The values <code>tls1</code> and <code>tls1.1</code> are no longer
     // supported. If |min| is set to one of these values, it will be silently
     // clamped to <code>tls1.2</code>. If |max| is set to one of those values,
     // or any other unrecognized value, it will be silently ignored.
     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.
     [doesNotSupportPromises=
         "Sets error along with callback arguments crbug.com/1504372"]
     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.
     [doesNotSupportPromises=
         "Sets error along with callback arguments crbug.com/1504372"]
     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.
     // |dnsQueryType| : The address resolution preference.
     // |callback| : Called when the connect attempt is complete.
     [doesNotSupportPromises=
         "Sets error along with callback arguments crbug.com/1504372"]
     static void connect(long socketId,
                         DOMString peerAddress,
                         long peerPort,
                         optional DnsQueryType dnsQueryType,
                         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.
     [doesNotSupportPromises=
         "Sets error along with callback arguments crbug.com/1504372"]
     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.
     [doesNotSupportPromises=
         "Sets error along with callback arguments crbug.com/1504372"]
     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);
   };
 };
	// Copyright 2014 The Chromium Authors
	// 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);

	// DNS resolution preferences. The default is <code>any</code> and uses the
	// current OS config which may return IPv4 or IPv6. <code>ipv4</code> forces
	// IPv4, and <code>ipv6</code> forces IPv6.
	enum DnsQueryType { any, ipv4, ipv6 };

	// 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. Supported values are
	// <code>tls1.2</code> or <code>tls1.3</code>.
	//
	// The values <code>tls1</code> and <code>tls1.1</code> are no longer
	// supported. If \|min\| is set to one of these values, it will be silently
	// clamped to <code>tls1.2</code>. If \|max\| is set to one of those values,
	// or any other unrecognized value, it will be silently ignored.
	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.
	[doesNotSupportPromises=
	"Sets error along with callback arguments crbug.com/1504372"]
	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.
	[doesNotSupportPromises=
	"Sets error along with callback arguments crbug.com/1504372"]
	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.
	// \|dnsQueryType\| : The address resolution preference.
	// \|callback\| : Called when the connect attempt is complete.
	[doesNotSupportPromises=
	"Sets error along with callback arguments crbug.com/1504372"]
	static void connect(long socketId,
	DOMString peerAddress,
	long peerPort,
	optional DnsQueryType dnsQueryType,
	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.
	[doesNotSupportPromises=
	"Sets error along with callback arguments crbug.com/1504372"]
	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.
	[doesNotSupportPromises=
	"Sets error along with callback arguments crbug.com/1504372"]
	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);
	};
	};