blob: 5bf0e783187c1e1117afcf9989c994e202870691 [file] [log] [blame]
// Copyright 2013 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.tcpServer</code> API to create server
// applications using TCP connections. This API supersedes the TCP functionality
// previously found in the <code>chrome.socket</code> API. Note that the socket
// ids created from this namespace are not compatible with ids created in other
// namespaces.
namespace sockets.tcpServer {
// 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 remains 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;
};
// Result of <code>create</code> call.
dictionary CreateInfo {
// The ID of the newly created server socket.
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>listen</code> method.
// |result| : The result code returned from the underlying network call.
// A negative value indicates an error.
callback ListenCallback = void (long result);
// Callback from the <code>disconnect</code> method.
callback DisconnectCallback = void ();
// 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 ();
// Result of the <code>getInfo</code> method.
dictionary SocketInfo {
// The socket identifier.
long socketId;
// Flag indicating if the socket remains open when the event page of the
// application is unloaded (see <code>SocketProperties.persistent</code>).
// The default value is "false".
boolean persistent;
// Application-defined string associated with the socket.
DOMString? name;
// Flag indicating whether connection requests on a listening socket are
// dispatched through the <code>onAccept<code> event or queued up in the
// listen queue backlog.
// See <code>setPaused<code>. The default value is "false".
boolean paused;
// If the socket is listening, contains its local IPv4/6 address.
DOMString? localAddress;
// If the socket is listening, contains its local port.
long? localPort;
};
// 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>onAccept</code> event.
dictionary AcceptInfo {
// The server socket identifier.
long socketId;
// The client socket identifier, i.e. the socket identifier of the newly
// established connection. This socket identifier should be used only with
// functions from the <code>chrome.sockets.tcp<code> namespace.
long clientSocketId;
};
// Data from an <code>onAcceptError</code> event.
dictionary AcceptErrorInfo {
// The server socket identifier.
long socketId;
// The result code returned from the underlying network call.
long resultCode;
};
interface Functions {
// Creates a TCP server 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 a listening socket from accepting new connections.
// When paused, a listening socket accepts new connections until its backlog
// (see <code>listen<code> function) is full then refuses additional
// connection requests. <code>onAccept<code> events are raised only when
// the socket is un-paused.
static void setPaused(long socketId,
boolean paused,
optional SetPausedCallback callback);
// Listens for connections on the specified port and address.
// If the port/address is in use, the callback indicates a failure.
// |socketId| : The socket identifier.
// |address| : The address of the local machine.
// |port| : The port of the local machine.
// |backlog| : Length of the socket's listen queue. The default value
// depends on the Operating System (SOMAXCONN), which ensures a reasonable
// queue length for most applications.
// |callback| : Called when listen operation completes.
static void listen(long socketId,
DOMString address,
long port,
optional long backlog,
ListenCallback callback);
// Disconnects the listening socket, i.e. stops accepting new connections
// and releases the address/port the socket is bound to. The socket
// identifier remains valid, e.g. it can be used with <code>listen<code> to
// accept connections on a new port and address.
// |socketId| : The socket identifier.
// |callback| : Called when the disconnect attempt is complete.
static void disconnect(long socketId,
optional DisconnectCallback callback);
// Disconnects and destroys the socket. Each socket created should be
// closed after use. The socket id is 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 a connection has been made to the server socket.
// |info| : The event data.
static void onAccept(AcceptInfo info);
// Event raised when a network error occured while the runtime was waiting
// for new connections on the socket address and port. Once this event is
// raised, the socket is set to <code>paused</code> and no more
// <code>onAccept</code> events are raised for this socket until the socket
// is resumed.
// |info| : The event data.
static void onAcceptError(AcceptErrorInfo info);
};
};