extensions/common/api/socket.idl

   1 // Copyright 2014 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.socket</code> API to send and receive data over the
   6 // network using TCP and UDP connections. <b>Note:</b> Starting with Chrome 33,
   7 // this API is deprecated in favor of the $(ref:sockets.udp), $(ref:sockets.tcp) and
   8 // $(ref:sockets.tcpServer) APIs.
   9 namespace socket {
  10   enum SocketType {
  11     tcp,
  12     udp
  13   };
  14
  15   // The socket options.
  16   dictionary CreateOptions {
  17   };
  18
  19   dictionary CreateInfo {
  20     // The id of the newly created socket.
  21     long socketId;
  22   };
  23
  24   callback CreateCallback = void (CreateInfo createInfo);
  25
  26   callback ConnectCallback = void (long result);
  27
  28   callback BindCallback = void (long result);
  29
  30   callback ListenCallback = void (long result);
  31
  32   callback SecureCallback = void (long result);
  33
  34   dictionary AcceptInfo {
  35     long resultCode;
  36     // The id of the accepted socket.
  37     long? socketId;
  38   };
  39
  40   callback AcceptCallback = void (AcceptInfo acceptInfo);
  41
  42   dictionary ReadInfo {
  43     // The resultCode returned from the underlying read() call.
  44     long resultCode;
  45
  46     ArrayBuffer data;
  47   };
  48
  49   callback ReadCallback = void (ReadInfo readInfo);
  50
  51   dictionary WriteInfo {
  52     // The number of bytes sent, or a negative error code.
  53     long bytesWritten;
  54   };
  55
  56   callback WriteCallback = void (WriteInfo writeInfo);
  57
  58   dictionary RecvFromInfo {
  59     // The resultCode returned from the underlying recvfrom() call.
  60     long resultCode;
  61
  62     ArrayBuffer data;
  63
  64     // The address of the remote machine.
  65     DOMString address;
  66
  67     long port;
  68   };
  69
  70   dictionary SocketInfo {
  71     // The type of the passed socket. This will be <code>tcp</code> or
  72     // <code>udp</code>.
  73     SocketType socketType;
  74
  75     // Whether or not the underlying socket is connected.
  76     //
  77     // For <code>tcp</code> sockets, this will remain true even if the remote
  78     // peer has disconnected. Reading or writing to the socket may then result
  79     // in an error, hinting that this socket should be disconnected via
  80     // <code>disconnect()</code>.
  81     //
  82     // For <code>udp</code> sockets, this just represents whether a default
  83     // remote address has been specified for reading and writing packets.
  84     boolean connected;
  85
  86     // If the underlying socket is connected, contains the IPv4/6 address of
  87     // the peer.
  88     DOMString? peerAddress;
  89
  90     // If the underlying socket is connected, contains the port of the
  91     // connected peer.
  92     long? peerPort;
  93
  94     // If the underlying socket is bound or connected, contains its local
  95     // IPv4/6 address.
  96     DOMString? localAddress;
  97
  98     // If the underlying socket is bound or connected, contains its local port.
  99     long? localPort;
 100   };
 101
 102   dictionary NetworkInterface {
 103     // The underlying name of the adapter. On *nix, this will typically be
 104     // "eth0", "lo", etc.
 105     DOMString name;
 106
 107     // The available IPv4/6 address.
 108     DOMString address;
 109
 110     // The prefix length
 111     long prefixLength;
 112   };
 113
 114   dictionary TLSVersionConstraints {
 115     // The minimum and maximum acceptable versions of TLS. These will
 116     // be <code>ssl3</code>, <code>tls1</code>, <code>tls1.1</code>,
 117     // or <code>tls1.2</code>.
 118     DOMString? min;
 119     DOMString? max;
 120   };
 121
 122   dictionary SecureOptions {
 123     TLSVersionConstraints? tlsVersion;
 124   };
 125
 126   callback RecvFromCallback = void (RecvFromInfo recvFromInfo);
 127
 128   callback SendToCallback = void (WriteInfo writeInfo);
 129
 130   callback SetKeepAliveCallback = void (boolean result);
 131
 132   callback SetNoDelayCallback = void (boolean result);
 133
 134   callback GetInfoCallback = void (SocketInfo result);
 135
 136   callback GetNetworkCallback = void (NetworkInterface[] result);
 137
 138   callback JoinGroupCallback = void (long result);
 139
 140   callback LeaveGroupCallback = void (long result);
 141
 142   callback SetMulticastTimeToLiveCallback = void (long result);
 143
 144   callback SetMulticastLoopbackModeCallback = void (long result);
 145
 146   callback GetJoinedGroupsCallback = void (DOMString[] groups);
 147
 148   interface Functions {
 149     // Creates a socket of the specified type that will connect to the specified
 150     // remote machine.
 151     // |type| : The type of socket to create. Must be <code>tcp</code> or
 152     // <code>udp</code>.
 153     // |options| : The socket options.
 154     // |callback| : Called when the socket has been created.
 155     static void create(SocketType type,
 156                        optional CreateOptions options,
 157                        CreateCallback callback);
 158
 159     // Destroys the socket. Each socket created should be destroyed after use.
 160     // |socketId| : The socketId.
 161     static void destroy(long socketId);
 162
 163     // Connects the socket to the remote machine (for a <code>tcp</code>
 164     // socket). For a <code>udp</code> socket, this sets the default address
 165     // which packets are sent to and read from for <code>read()</code>
 166     // and <code>write()</code> calls.
 167     // |socketId| : The socketId.
 168     // |hostname| : The hostname or IP address of the remote machine.
 169     // |port| : The port of the remote machine.
 170     // |callback| : Called when the connection attempt is complete.
 171     static void connect(long socketId,
 172                         DOMString hostname,
 173                         long port,
 174                         ConnectCallback callback);
 175
 176     // Binds the local address for socket. Currently, it does not support
 177     // TCP socket.
 178     // |socketId| : The socketId.
 179     // |address| : The address of the local machine.
 180     // |port| : The port of the local machine.
 181     // |callback| : Called when the bind attempt is complete.
 182     static void bind(long socketId,
 183                      DOMString address,
 184                      long port,
 185                      BindCallback callback);
 186
 187     // Disconnects the socket. For UDP sockets, <code>disconnect</code> is a
 188     // non-operation but is safe to call.
 189     // |socketId| : The socketId.
 190     static void disconnect(long socketId);
 191
 192     // Reads data from the given connected socket.
 193     // |socketId| : The socketId.
 194     // |bufferSize| : The read buffer size.
 195     // |callback| : Delivers data that was available to be read without
 196     // blocking.
 197     static void read(long socketId,
 198                      optional long bufferSize,
 199                      ReadCallback callback);
 200
 201     // Writes data on the given connected socket.
 202     // |socketId| : The socketId.
 203     // |data| : The data to write.
 204     // |callback| : Called when the write operation completes without blocking
 205     // or an error occurs.
 206     static void write(long socketId,
 207                       ArrayBuffer data,
 208                       WriteCallback callback);
 209
 210     // Receives data from the given UDP socket.
 211     // |socketId| : The socketId.
 212     // |bufferSize| : The receive buffer size.
 213     // |callback| : Returns result of the recvFrom operation.
 214     static void recvFrom(long socketId,
 215                          optional long bufferSize,
 216                          RecvFromCallback callback);
 217
 218     // Sends data on the given UDP socket to the given address and port.
 219     // |socketId| : The socketId.
 220     // |data| : The data to write.
 221     // |address| : The address of the remote machine.
 222     // |port| : The port of the remote machine.
 223     // |callback| : Called when the send operation completes without blocking
 224     // or an error occurs.
 225     static void sendTo(long socketId,
 226                        ArrayBuffer data,
 227                        DOMString address,
 228                        long port,
 229                        SendToCallback callback);
 230
 231     // This method applies to TCP sockets only.
 232     // Listens for connections on the specified port and address. This
 233     // effectively makes this a server socket, and client socket
 234     // functions (connect, read, write) can no longer be used on this socket.
 235     // |socketId| : The socketId.
 236     // |address| : The address of the local machine.
 237     // |port| : The port of the local machine.
 238     // |backlog| : Length of the socket's listen queue.
 239     // |callback| : Called when listen operation completes.
 240     static void listen(long socketId,
 241                        DOMString address,
 242                        long port,
 243                        optional long backlog,
 244                        ListenCallback callback);
 245
 246     // This method applies to TCP sockets only.
 247     // Registers a callback function to be called when a connection is
 248     // accepted on this listening server socket. Listen must be called first.
 249     // If there is already an active accept callback, this callback will be
 250     // invoked immediately with an error as the resultCode.
 251     // |socketId| : The socketId.
 252     // |callback| : The callback is invoked when a new socket is accepted.
 253     static void accept(long socketId,
 254                        AcceptCallback callback);
 255
 256     // Enables or disables the keep-alive functionality for a TCP connection.
 257     // |socketId| : The socketId.
 258     // |enable| : If true, enable keep-alive functionality.
 259     // |delay| : Set the delay seconds between the last data packet received
 260     // and the first keepalive probe. Default is 0.
 261     // |callback| : Called when the setKeepAlive attempt is complete.
 262     static void setKeepAlive(long socketId,
 263                              boolean enable,
 264                              optional long delay,
 265                              SetKeepAliveCallback callback);
 266
 267     // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
 268     // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
 269     // |socketId| : The socketId.
 270     // |noDelay| : If true, disables Nagle's algorithm.
 271     // |callback| : Called when the setNoDelay attempt is complete.
 272     static void setNoDelay(long socketId,
 273                            boolean noDelay,
 274                            SetNoDelayCallback callback);
 275
 276     // Retrieves the state of the given socket.
 277     // |socketId| : The socketId.
 278     // |callback| : Called when the state is available.
 279     static void getInfo(long socketId,
 280                         GetInfoCallback callback);
 281
 282     // Retrieves information about local adapters on this system.
 283     // |callback| : Called when local adapter information is available.
 284     static void getNetworkList(GetNetworkCallback callback);
 285
 286     // Join the multicast group and start to receive packets from that group.
 287     // The socket must be of UDP type and must be bound to a local port
 288     // before calling this method.
 289     // |socketId| : The socketId.
 290     // |address| : The group address to join. Domain names are not supported.
 291     // |callback| : Called when the join group operation is done with an
 292     // integer parameter indicating the platform-independent error code.
 293     static void joinGroup(long socketId,
 294                           DOMString address,
 295                           JoinGroupCallback callback);
 296
 297     // Leave the multicast group previously joined using <code>joinGroup</code>.
 298     // It's not necessary to leave the multicast group before destroying the
 299     // socket or exiting. This is automatically called by the OS.
 300     //
 301     // Leaving the group will prevent the router from sending multicast
 302     // datagrams to the local host, presuming no other process on the host is
 303     // still joined to the group.
 304     //
 305     // |socketId| : The socketId.
 306     // |address| : The group address to leave. Domain names are not supported.
 307     // |callback| : Called when the leave group operation is done with an
 308     // integer parameter indicating the platform-independent error code.
 309     static void leaveGroup(long socketId, DOMString address,
 310                            LeaveGroupCallback callback);
 311
 312     // Set the time-to-live of multicast packets sent to the multicast group.
 313     //
 314     // Calling this method does not require multicast permissions.
 315     //
 316     // |socketId| : The socketId.
 317     // |ttl| : The time-to-live value.
 318     // |callback| : Called when the configuration operation is done.
 319     static void setMulticastTimeToLive(
 320         long socketId,
 321         long ttl,
 322         SetMulticastTimeToLiveCallback callback);
 323
 324     // Set whether multicast packets sent from the host to the multicast
 325     // group will be looped back to the host.
 326     //
 327     // Note: the behavior of <code>setMulticastLoopbackMode</code> is slightly
 328     // different between Windows and Unix-like systems. The inconsistency
 329     // happens only when there is more than one application on the same host
 330     // joined to the same multicast group while having different settings on
 331     // multicast loopback mode. On Windows, the applications with loopback off
 332     // will not RECEIVE the loopback packets; while on Unix-like systems, the
 333     // applications with loopback off will not SEND the loopback packets to
 334     // other applications on the same host. See MSDN: http://goo.gl/6vqbj
 335     //
 336     // Calling this method does not require multicast permissions.
 337     //
 338     // |socketId| : The socketId.
 339     // |enabled| : Indicate whether to enable loopback mode.
 340     // |callback| : Called when the configuration operation is done.
 341     static void setMulticastLoopbackMode(
 342         long socketId,
 343         boolean enabled,
 344         SetMulticastLoopbackModeCallback callback);
 345
 346     // Get the multicast group addresses the socket is currently joined to.
 347     // |socketId| : The socketId.
 348     // |callback| : Called with an array of strings of the result.
 349     static void getJoinedGroups(long socketId,
 350                                 GetJoinedGroupsCallback callback);
 351
 352     // Start a TLS client connection over a connected TCP client socket.
 353     // |socketId| : The connected socket to use.
 354     // |options| : Constraints and parameters for the TLS connection.
 355     // |callback| : Called when the TLS connection attempt is complete.
 356     static void secure(long socketId,
 357                        optional SecureOptions options,
 358                        SecureCallback callback);
 359   };
 360
 361 };