diff options
Diffstat (limited to 'chrome/common/extensions/api/sockets_tcp_server.idl')
| -rw-r--r-- | chrome/common/extensions/api/sockets_tcp_server.idl | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/chrome/common/extensions/api/sockets_tcp_server.idl b/chrome/common/extensions/api/sockets_tcp_server.idl new file mode 100644 index 0000000..60c9b61 --- /dev/null +++ b/chrome/common/extensions/api/sockets_tcp_server.idl @@ -0,0 +1,191 @@ +// 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); + }; +}; |