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