chrome/common/extensions/api/socket.idl

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