netwerk/base/nsIUDPSocket.idl

   1 /* vim:set ts=4 sw=4 et cindent: */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsINetAddr;
   9 interface nsIUDPSocketListener;
  10 interface nsIUDPMessage;
  11 interface nsISocketTransport;
  12 interface nsIOutputStream;
  13 interface nsIInputStream;
  14 interface nsIPrincipal;
  15
  16 %{ C++
  17 #include "nsTArrayForwardDeclare.h"
  18 namespace mozilla {
  19 namespace net {
  20 union NetAddr;
  21 }
  22 }
  23 %}
  24 native NetAddr(mozilla::net::NetAddr);
  25 [ptr] native NetAddrPtr(mozilla::net::NetAddr);
  26 [ref] native Uint8TArrayRef(FallibleTArray<uint8_t>);
  27
  28 /**
  29  * nsIUDPSocket
  30  *
  31  * An interface to a UDP socket that can accept incoming connections.
  32  */
  33 [scriptable, uuid(d423bf4e-4499-40cf-bc03-153e2bf206d1)]
  34 interface nsIUDPSocket : nsISupports
  35 {
  36     /**
  37      * init
  38      *
  39      * This method initializes a UDP socket.
  40      *
  41      * @param aPort
  42      *        The port of the UDP socket.  Pass -1 to indicate no preference,
  43      *        and a port will be selected automatically.
  44      * @param aLoopbackOnly
  45      *        If true, the UDP socket will only respond to connections on the
  46      *        local loopback interface.  Otherwise, it will accept connections
  47      *        from any interface.  To specify a particular network interface,
  48      *        use initWithAddress.
  49      * @param aPrincipal
  50      *        The principal connected to this socket.
  51      * @param aAddressReuse
  52      *        If true, the socket is allowed to be bound to an address that is
  53      *        already in use. Default is true.
  54      */
  55     [optional_argc] void init(in long aPort,
  56                               in boolean aLoopbackOnly,
  57                               in nsIPrincipal aPrincipal,
  58                               [optional] in boolean aAddressReuse);
  59
  60     [optional_argc] void init2(in AUTF8String aAddr,
  61                                in long aPort,
  62                                in nsIPrincipal aPrincipal,
  63                                [optional] in boolean aAddressReuse);
  64
  65     /**
  66      * initWithAddress
  67      *
  68      * This method initializes a UDP socket, and binds it to a particular
  69      * local address (and hence a particular local network interface).
  70      *
  71      * @param aAddr
  72      *        The address to which this UDP socket should be bound.
  73      * @param aPrincipal
  74      *        The principal connected to this socket.
  75      * @param aAddressReuse
  76      *        If true, the socket is allowed to be bound to an address that is
  77      *        already in use. Default is true.
  78      */
  79     [noscript, optional_argc] void initWithAddress([const] in NetAddrPtr aAddr,
  80                                                    in nsIPrincipal aPrincipal,
  81                                                    [optional] in boolean aAddressReuse);
  82
  83     /**
  84      * close
  85      *
  86      * This method closes a UDP socket.  This does not affect already
  87      * connected client sockets (i.e., the nsISocketTransport instances
  88      * created from this UDP socket).  This will cause the onStopListening
  89      * event to asynchronously fire with a status of NS_BINDING_ABORTED.
  90      */
  91     void close();
  92
  93     /**
  94      * asyncListen
  95      *
  96      * This method puts the UDP socket in the listening state.  It will
  97      * asynchronously listen for and accept client connections.  The listener
  98      * will be notified once for each client connection that is accepted.  The
  99      * listener's onSocketAccepted method will be called on the same thread
 100      * that called asyncListen (the calling thread must have a nsIEventTarget).
 101      *
 102      * The listener will be passed a reference to an already connected socket
 103      * transport (nsISocketTransport).  See below for more details.
 104      *
 105      * @param aListener
 106      *        The listener to be notified when client connections are accepted.
 107      */
 108     void asyncListen(in nsIUDPSocketListener aListener);
 109
 110     /**
 111      * connect
 112      *
 113      * This method connects the UDP socket to a remote UDP address.
 114      *
 115      * @param aRemoteAddr
 116      *        The remote address to connect to
 117      */
 118      void connect([const] in NetAddrPtr aAddr);
 119
 120     /**
 121      * Returns the local address of this UDP socket
 122      */
 123     readonly attribute nsINetAddr localAddr;
 124
 125     /**
 126      * Returns the port of this UDP socket.
 127      */
 128     readonly attribute long port;
 129
 130     /**
 131      * Returns the address to which this UDP socket is bound.  Since a
 132      * UDP socket may be bound to multiple network devices, this address
 133      * may not necessarily be specific to a single network device.  In the
 134      * case of an IP socket, the IP address field would be zerod out to
 135      * indicate a UDP socket bound to all network devices.  Therefore,
 136      * this method cannot be used to determine the IP address of the local
 137      * system.  See nsIDNSService::myHostName if this is what you need.
 138      */
 139     [noscript] NetAddr getAddress();
 140
 141     /**
 142      * send
 143      *
 144      * Send out the datagram to specified remote host and port.
 145      * DNS lookup will be triggered.
 146      *
 147      * @param host The remote host name.
 148      * @param port The remote port.
 149      * @param data The buffer containing the data to be written.
 150      * @param dataLength The maximum number of bytes to be written.
 151      * @return number of bytes written. (0 or dataLength)
 152      */
 153     unsigned long send(in AUTF8String host, in unsigned short port,
 154                        [const, array, size_is(dataLength)]in uint8_t data,
 155                        in unsigned long dataLength);
 156
 157     /**
 158      * sendWithAddr
 159      *
 160      * Send out the datagram to specified remote host and port.
 161      *
 162      * @param addr The remote host address.
 163      * @param data The buffer containing the data to be written.
 164      * @param dataLength The maximum number of bytes to be written.
 165      * @return number of bytes written. (0 or dataLength)
 166      */
 167     unsigned long sendWithAddr(in nsINetAddr addr,
 168                                [const, array, size_is(dataLength)]in uint8_t data,
 169                                in unsigned long dataLength);
 170
 171     /**
 172      * sendWithAddress
 173      *
 174      * Send out the datagram to specified remote address and port.
 175      *
 176      * @param addr The remote host address.
 177      * @param data The buffer containing the data to be written.
 178      * @param dataLength The maximum number of bytes to be written.
 179      * @return number of bytes written. (0 or dataLength)
 180      */
 181     [noscript] unsigned long sendWithAddress([const] in NetAddrPtr addr,
 182                                              [const, array, size_is(dataLength)]in uint8_t data,
 183                                              in unsigned long dataLength);
 184
 185     /**
 186      * sendBinaryStream
 187      *
 188      * Send out the datagram to specified remote address and port.
 189      *
 190      * @param host The remote host name.
 191      * @param port The remote port.
 192      * @param stream The input stream to be sent. This must be a buffered stream implementation.
 193      */
 194     void sendBinaryStream(in AUTF8String host, in unsigned short port,
 195                           in nsIInputStream stream);
 196
 197     /**
 198      * sendBinaryStreamWithAddress
 199      *
 200      * Send out the datagram to specified remote address and port.
 201      *
 202      * @param addr The remote host address.
 203      * @param stream The input stream to be sent. This must be a buffered stream implementation.
 204      */
 205     void sendBinaryStreamWithAddress([const] in NetAddrPtr addr,
 206                                      in nsIInputStream stream);
 207
 208     /**
 209      * joinMulticast
 210      *
 211      * Join the multicast group specified by |addr|.  You are then able to
 212      * receive future datagrams addressed to the group.
 213      *
 214      * @param addr
 215      *        The multicast group address.
 216      * @param iface
 217      *        The local address of the interface on which to join the group.  If
 218      *        this is not specified, the OS may join the group on all interfaces
 219      *        or only the primary interface.
 220      */
 221     void joinMulticast(in AUTF8String addr, [optional] in AUTF8String iface);
 222     [noscript] void joinMulticastAddr([const] in NetAddr addr,
 223                                       [const, optional] in NetAddrPtr iface);
 224
 225     /**
 226      * leaveMulticast
 227      *
 228      * Leave the multicast group specified by |addr|.  You will no longer
 229      * receive future datagrams addressed to the group.
 230      *
 231      * @param addr
 232      *        The multicast group address.
 233      * @param iface
 234      *        The local address of the interface on which to leave the group.
 235      *        If this is not specified, the OS may leave the group on all
 236      *        interfaces or only the primary interface.
 237      */
 238     void leaveMulticast(in AUTF8String addr, [optional] in AUTF8String iface);
 239     [noscript] void leaveMulticastAddr([const] in NetAddr addr,
 240                                        [const, optional] in NetAddrPtr iface);
 241
 242     /**
 243      * multicastLoopback
 244      *
 245      * Whether multicast datagrams sent via this socket should be looped back to
 246      * this host (assuming this host has joined the relevant group).  Defaults
 247      * to true.
 248      * Note: This is currently write-only.
 249      */
 250     attribute boolean multicastLoopback;
 251
 252     /**
 253      * multicastInterface
 254      *
 255      * The interface that should be used for sending future multicast datagrams.
 256      * Note: This is currently write-only.
 257      */
 258     attribute AUTF8String multicastInterface;
 259
 260     /**
 261      * multicastInterfaceAddr
 262      *
 263      * The interface that should be used for sending future multicast datagrams.
 264      * Note: This is currently write-only.
 265      */
 266     [noscript] attribute NetAddr multicastInterfaceAddr;
 267
 268     /**
 269      * recvBufferSize
 270      *
 271      * The size of the receive buffer. Default depends on the OS.
 272      */
 273     [noscript] attribute long recvBufferSize;
 274
 275     /**
 276      * sendBufferSize
 277      *
 278      * The size of the send buffer. Default depends on the OS.
 279      */
 280     [noscript] attribute long sendBufferSize;
 281 };
 282
 283 /**
 284  * nsIUDPSocketListener
 285  *
 286  * This interface is notified whenever a UDP socket accepts a new connection.
 287  * The transport is in the connected state, and read/write streams can be opened
 288  * using the normal nsITransport API.  The address of the client can be found by
 289  * calling the nsISocketTransport::GetAddress method or by inspecting
 290  * nsISocketTransport::GetHost, which returns a string representation of the
 291  * client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
 292  */
 293 [scriptable, uuid(2E4B5DD3-7358-4281-B81F-10C62EF39CB5)]
 294 interface nsIUDPSocketListener : nsISupports
 295 {
 296     /**
 297      * onPacketReceived
 298      *
 299      * This method is called when a client sends an UDP packet.
 300      *
 301      * @param aSocket
 302      *        The UDP socket.
 303      * @param aMessage
 304      *        The message.
 305      */
 306     void onPacketReceived(in nsIUDPSocket aSocket,
 307                           in nsIUDPMessage aMessage);
 308
 309     /**
 310      * onStopListening
 311      *
 312      * This method is called when the listening socket stops for some reason.
 313      * The UDP socket is effectively dead after this notification.
 314      *
 315      * @param aSocket
 316      *        The UDP socket.
 317      * @param aStatus
 318      *        The reason why the UDP socket stopped listening.  If the
 319      *        UDP socket was manually closed, then this value will be
 320      *        NS_BINDING_ABORTED.
 321      */
 322     void onStopListening(in nsIUDPSocket aSocket, in nsresult aStatus);
 323 };
 324
 325 /**
 326  * nsIUDPMessage
 327  *
 328  * This interface is used to encapsulate an incomming UDP message
 329  */
 330 [scriptable, uuid(afdc743f-9cc0-40d8-b442-695dc54bbb74)]
 331 interface nsIUDPMessage : nsISupports
 332 {
 333     /**
 334      * Address of the source of the message
 335      */
 336     readonly attribute nsINetAddr fromAddr;
 337
 338     /**
 339      * Data of the message
 340      */
 341     readonly attribute ACString data;
 342
 343     /**
 344      * Stream to send a response
 345      */
 346     readonly attribute nsIOutputStream outputStream;
 347
 348     /**
 349      * Raw Data of the message
 350      */
 351     [implicit_jscontext] readonly attribute jsval rawData;
 352     [noscript, notxpcom, nostdcall] Uint8TArrayRef getDataAsTArray();
 353 };