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