1 // Copyright 2013 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.tcpServer</code> API to create server 6 // applications using TCP connections. This API supersedes the TCP functionality 7 // previously found in the <code>chrome.socket</code> API. Note that the socket 8 // ids created from this namespace are not compatible with ids created in other 9 // namespaces. 10 namespace sockets.tcpServer { 11 // The socket properties specified in the <code>create</code> or 12 // <code>update</code> function. Each property is optional. If a property 13 // value is not specified, a default value is used when calling 14 // <code>create</code>, or the existing value if preserved when calling 15 // <code>update</code>. 16 dictionary SocketProperties { 17 // Flag indicating if the socket remains open when the event page of the 18 // application is unloaded (see 19 // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App 20 // Lifecycle</a>). The default value is "false." When the application is 21 // loaded, any sockets previously opened with persistent=true can be fetched 22 // with <code>getSockets</code>. 23 boolean? persistent; 24 25 // An application-defined string associated with the socket. 26 DOMString? name; 27 }; 28 29 // Result of <code>create</code> call. 30 dictionary CreateInfo { 31 // The ID of the newly created server socket. 32 long socketId; 33 }; 34 35 // Callback from the <code>create</code> method. 36 // |createInfo| : The result of the socket creation. 37 callback CreateCallback = void (CreateInfo createInfo); 38 39 // Callback from the <code>listen</code> method. 40 // |result| : The result code returned from the underlying network call. 41 // A negative value indicates an error. 42 callback ListenCallback = void (long result); 43 44 // Callback from the <code>disconnect</code> method. 45 callback DisconnectCallback = void (); 46 47 // Callback from the <code>close<code> method. 48 callback CloseCallback = void (); 49 50 // Callback from the <code>update</code> method. 51 callback UpdateCallback = void (); 52 53 // Callback from the <code>setPaused<code> method. 54 callback SetPausedCallback = void (); 55 56 // Result of the <code>getInfo</code> method. 57 dictionary SocketInfo { 58 // The socket identifier. 59 long socketId; 60 61 // Flag indicating if the socket remains open when the event page of the 62 // application is unloaded (see <code>SocketProperties.persistent</code>). 63 // The default value is "false". 64 boolean persistent; 65 66 // Application-defined string associated with the socket. 67 DOMString? name; 68 69 // Flag indicating whether connection requests on a listening socket are 70 // dispatched through the <code>onAccept<code> event or queued up in the 71 // listen queue backlog. 72 // See <code>setPaused<code>. The default value is "false". 73 boolean paused; 74 75 // If the socket is listening, contains its local IPv4/6 address. 76 DOMString? localAddress; 77 78 // If the socket is listening, contains its local port. 79 long? localPort; 80 }; 81 82 // Callback from the <code>getInfo</code> method. 83 // |socketInfo| : Object containing the socket information. 84 callback GetInfoCallback = void (SocketInfo socketInfo); 85 86 // Callback from the <code>getSockets</code> method. 87 // |socketInfos| : Array of object containing socket information. 88 callback GetSocketsCallback = void (SocketInfo[] socketInfos); 89 90 // Data from an <code>onAccept</code> event. 91 dictionary AcceptInfo { 92 // The server socket identifier. 93 long socketId; 94 95 // The client socket identifier, i.e. the socket identifier of the newly 96 // established connection. This socket identifier should be used only with 97 // functions from the <code>chrome.sockets.tcp<code> namespace. Note the 98 // client socket is initially paused and must be explictly un-paused by the 99 // application to start receiving data. 100 long clientSocketId; 101 }; 102 103 // Data from an <code>onAcceptError</code> event. 104 dictionary AcceptErrorInfo { 105 // The server socket identifier. 106 long socketId; 107 108 // The result code returned from the underlying network call. 109 long resultCode; 110 }; 111 112 interface Functions { 113 // Creates a TCP server socket. 114 // |properties| : The socket properties (optional). 115 // |callback| : Called when the socket has been created. 116 static void create(optional SocketProperties properties, 117 CreateCallback callback); 118 119 // Updates the socket properties. 120 // |socketId| : The socket identifier. 121 // |properties| : The properties to update. 122 // |callback| : Called when the properties are updated. 123 static void update(long socketId, 124 SocketProperties properties, 125 optional UpdateCallback callback); 126 127 // Enables or disables a listening socket from accepting new connections. 128 // When paused, a listening socket accepts new connections until its backlog 129 // (see <code>listen<code> function) is full then refuses additional 130 // connection requests. <code>onAccept<code> events are raised only when 131 // the socket is un-paused. 132 static void setPaused(long socketId, 133 boolean paused, 134 optional SetPausedCallback callback); 135 136 // Listens for connections on the specified port and address. 137 // If the port/address is in use, the callback indicates a failure. 138 // |socketId| : The socket identifier. 139 // |address| : The address of the local machine. 140 // |port| : The port of the local machine. 141 // |backlog| : Length of the socket's listen queue. The default value 142 // depends on the Operating System (SOMAXCONN), which ensures a reasonable 143 // queue length for most applications. 144 // |callback| : Called when listen operation completes. 145 static void listen(long socketId, 146 DOMString address, 147 long port, 148 optional long backlog, 149 ListenCallback callback); 150 151 // Disconnects the listening socket, i.e. stops accepting new connections 152 // and releases the address/port the socket is bound to. The socket 153 // identifier remains valid, e.g. it can be used with <code>listen<code> to 154 // accept connections on a new port and address. 155 // |socketId| : The socket identifier. 156 // |callback| : Called when the disconnect attempt is complete. 157 static void disconnect(long socketId, 158 optional DisconnectCallback callback); 159 160 // Disconnects and destroys the socket. Each socket created should be 161 // closed after use. The socket id is no longer valid as soon at the 162 // function is called. However, the socket is guaranteed to be closed only 163 // when the callback is invoked. 164 // |socketId| : The socket identifier. 165 // |callback| : Called when the <code>close</code> operation completes. 166 static void close(long socketId, 167 optional CloseCallback callback); 168 169 // Retrieves the state of the given socket. 170 // |socketId| : The socket identifier. 171 // |callback| : Called when the socket state is available. 172 static void getInfo(long socketId, 173 GetInfoCallback callback); 174 175 // Retrieves the list of currently opened sockets owned by the application. 176 // |callback| : Called when the list of sockets is available. 177 static void getSockets(GetSocketsCallback callback); 178 }; 179 180 interface Events { 181 // Event raised when a connection has been made to the server socket. 182 // |info| : The event data. 183 static void onAccept(AcceptInfo info); 184 185 // Event raised when a network error occured while the runtime was waiting 186 // for new connections on the socket address and port. Once this event is 187 // raised, the socket is set to <code>paused</code> and no more 188 // <code>onAccept</code> events are raised for this socket until the socket 189 // is resumed. 190 // |info| : The event data. 191 static void onAcceptError(AcceptErrorInfo info); 192 }; 193 }; 194
