tor-browser

nsIUDPSocket.idl (15073B)

---

/* vim:set ts=4 sw=4 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsINetAddr;
interface nsIUDPSocketListener;
interface nsIUDPSocketSyncListener;
interface nsIUDPMessage;
interface nsISocketTransport;
interface nsIOutputStream;
interface nsIInputStream;
interface nsIPrincipal;

%{ C++
#include "nsTArrayForwardDeclare.h"
namespace mozilla {
namespace net {
union NetAddr;
}
}
%}
native NetAddr(mozilla::net::NetAddr);
[ptr] native NetAddrPtr(mozilla::net::NetAddr);
[ref] native Uint8TArrayRef(FallibleTArray<uint8_t>);

/**
* nsIUDPSocket
*
* An interface to a UDP socket that can accept incoming connections.
*/
[scriptable, builtinclass, uuid(d423bf4e-4499-40cf-bc03-153e2bf206d1)]
interface nsIUDPSocket : nsISupports
{
   /**
    * init
    *
    * This method initializes a UDP socket.
    *
    * @param aPort
    *        The port of the UDP socket.  Pass -1 to indicate no preference,
    *        and a port will be selected automatically.
    * @param aLoopbackOnly
    *        If true, the UDP socket will only respond to connections on the
    *        local loopback interface.  Otherwise, it will accept connections
    *        from any interface.  To specify a particular network interface,
    *        use initWithAddress.
    * @param aPrincipal
    *        The principal connected to this socket.
    * @param aAddressReuse
    *        If true, the socket is allowed to be bound to an address that is
    *        already in use. Default is true.
    */
   [optional_argc] void init(in long aPort,
                             in boolean aLoopbackOnly,
                             in nsIPrincipal aPrincipal,
                             [optional] in boolean aAddressReuse);

   [optional_argc] void init2(in AUTF8String aAddr,
                              in long aPort,
                              in nsIPrincipal aPrincipal,
                              [optional] in boolean aAddressReuse);

   /**
    * initWithAddress
    *
    * This method initializes a UDP socket, and binds it to a particular
    * local address (and hence a particular local network interface).
    *
    * @param aAddr
    *        The address to which this UDP socket should be bound.
    * @param aPrincipal
    *        The principal connected to this socket.
    * @param aAddressReuse
    *        If true, the socket is allowed to be bound to an address that is
    *        already in use. Default is true.
    */
   [noscript, optional_argc] void initWithAddress([const] in NetAddrPtr aAddr,
                                                  in nsIPrincipal aPrincipal,
                                                  [optional] in boolean aAddressReuse);

   /**
    * close
    *
    * This method closes a UDP socket.  This does not affect already
    * connected client sockets (i.e., the nsISocketTransport instances
    * created from this UDP socket).  This will cause the onStopListening
    * event to asynchronously fire with a status of NS_BINDING_ABORTED.
    */
   void close();

   /**
    * asyncListen
    *
    * This method puts the UDP socket in the listening state.  It will
    * asynchronously listen for and accept client connections.  The listener
    * will be notified once for each client connection that is accepted.  The
    * listener's onSocketAccepted method will be called on the same thread
    * that called asyncListen (the calling thread must have a nsIEventTarget).
    *
    * The listener will be passed a reference to an already connected socket
    * transport (nsISocketTransport).  See below for more details.
    *
    * @param aListener
    *        The listener to be notified when client connections are accepted.
    */
   void asyncListen(in nsIUDPSocketListener aListener);

   /**
    * This adds a nsIUDPSocketSyncListener listener (defined below).
    * When data is available onPacketReceived is called and the listener uses
    * recvWithAddr to actually retrieve data from the socket.
    * The listener can be use only if it runs on the socket thread.
    * If it is used off the socket thread there is a risk of triggering a bug
    * in OS thatcan cause a crash.
    */
   [noscript] void syncListen(in nsIUDPSocketSyncListener aListener);

   /**
    * connect
    *
    * This method connects the UDP socket to a remote UDP address.
    *
    * @param aRemoteAddr
    *        The remote address to connect to
    */
   [noscript] void connect([const] in NetAddrPtr aAddr);

   /**
    * Returns the local address of this UDP socket
    */
   readonly attribute nsINetAddr localAddr;

   /**
    * Returns the port of this UDP socket.
    */
   readonly attribute long port;

   /**
    * Returns the address to which this UDP socket is bound.  Since a
    * UDP socket may be bound to multiple network devices, this address
    * may not necessarily be specific to a single network device.  In the
    * case of an IP socket, the IP address field would be zerod out to
    * indicate a UDP socket bound to all network devices.  Therefore,
    * this method cannot be used to determine the IP address of the local
    * system.  See nsIDNSService::myHostName if this is what you need.
    */
   [noscript] NetAddr getAddress();

   /**
    * send
    *
    * Send out the datagram to specified remote host and port.
    * DNS lookup will be triggered.
    *
    * @param host The remote host name.
    * @param port The remote port.
    * @param data The buffer containing the data to be written.
    * @return number of bytes written. (0 or length of data)
    */
   unsigned long send(in AUTF8String host, in unsigned short port,
                      in Array<uint8_t> data);

   /**
    * sendWithAddr
    *
    * Send out the datagram to specified remote host and port.
    *
    * @param addr The remote host address.
    * @param data The buffer containing the data to be written.
    * @return number of bytes written. (0 or length of data)
    */
   unsigned long sendWithAddr(in nsINetAddr addr,
                              in Array<uint8_t> data);


   /**
    * Receive a datagram.
    * @param addr The remote host address.
    * @param data The buffer to store received datagram.
    */
   [noscript] void recvWithAddr(out NetAddr addr,
                                out Array<uint8_t> data);

   /**
    * sendWithAddress
    *
    * Send out the datagram to specified remote address and port.
    *
    * @param addr The remote host address.
    * @param data The buffer containing the data to be written.
    * @return number of bytes written. (0 or length of data)
    */
   [noscript] unsigned long sendWithAddress([const] in NetAddrPtr addr,
                                            [array, size_is(length), const] in uint8_t data,
                                            in unsigned long length);

   /**
    * sendBinaryStream
    *
    * Send out the datagram to specified remote address and port.
    *
    * @param host The remote host name.
    * @param port The remote port.
    * @param stream The input stream to be sent. This must be a buffered stream implementation.
    */
   void sendBinaryStream(in AUTF8String host, in unsigned short port,
                         in nsIInputStream stream);

   /**
    * sendBinaryStreamWithAddress
    *
    * Send out the datagram to specified remote address and port.
    *
    * @param addr The remote host address.
    * @param stream The input stream to be sent. This must be a buffered stream implementation.
    */
   [noscript] void sendBinaryStreamWithAddress([const] in NetAddrPtr addr,
                                               in nsIInputStream stream);

   /**
    * joinMulticast
    *
    * Join the multicast group specified by |addr|.  You are then able to
    * receive future datagrams addressed to the group.
    *
    * @param addr
    *        The multicast group address.
    * @param iface
    *        The local address of the interface on which to join the group.  If
    *        this is not specified, the OS may join the group on all interfaces
    *        or only the primary interface.
    */
   void joinMulticast(in AUTF8String addr, [optional] in AUTF8String iface);
   [noscript] void joinMulticastAddr([const] in NetAddr addr,
                                     [const, optional] in NetAddrPtr iface);

   /**
    * leaveMulticast
    *
    * Leave the multicast group specified by |addr|.  You will no longer
    * receive future datagrams addressed to the group.
    *
    * @param addr
    *        The multicast group address.
    * @param iface
    *        The local address of the interface on which to leave the group.
    *        If this is not specified, the OS may leave the group on all
    *        interfaces or only the primary interface.
    */
   void leaveMulticast(in AUTF8String addr, [optional] in AUTF8String iface);
   [noscript] void leaveMulticastAddr([const] in NetAddr addr,
                                      [const, optional] in NetAddrPtr iface);

   /**
     * getFileDescriptor
     *
     * Get the file descriptor of the socket.
     *
     * @return The file descriptor.
     */
   [noscript, notxpcom] int64_t getFileDescriptor();

   /**
     * enableWritePoll
     *
     * Request that the UDP socket polls for write-availability.
     * Typically called after a non-blocking send returns WOULD_BLOCK.
     *
     * Note that the socket always polls for read-availability.
     */
   [noscript, notxpcom] void enableWritePoll();

    /**
     * isSocketClosed
     *
     * @return true when the socket is already closed.
     */
   [noscript, notxpcom] boolean isSocketClosed();

   /**
    * addOutputBytes
    *
    * Add number of bytes written to the socket. Used when sending data through
    * file descriptor optained from getFileDescriptor instead of nsIUDPSocket
    * methods.
    *
    * @param aBytes
    *        The number of bytes written.
    */
   [noscript, notxpcom] void addOutputBytes(in uint32_t aBytes);

   /**
    * addInputBytes
    *
    * Add number of bytes read from the socket. Used when reading data through
    * file descriptor optained from getFileDescriptor instead of nsIUDPSocket
    * methods.
    *
    * @param aBytes
    *        The number of bytes read.
    */
   [noscript, notxpcom] void addInputBytes(in uint32_t aBytes);

   /**
    * multicastLoopback
    *
    * Whether multicast datagrams sent via this socket should be looped back to
    * this host (assuming this host has joined the relevant group).  Defaults
    * to true.
    * Note: This is currently write-only.
    */
   attribute boolean multicastLoopback;

   /**
    * multicastInterface
    *
    * The interface that should be used for sending future multicast datagrams.
    * Note: This is currently write-only.
    */
   attribute AUTF8String multicastInterface;

   /**
    * multicastInterfaceAddr
    *
    * The interface that should be used for sending future multicast datagrams.
    * Note: This is currently write-only.
    */
   [noscript] attribute NetAddr multicastInterfaceAddr;

   /**
    * recvBufferSize
    *
    * The size of the receive buffer. Default depends on the OS.
    */
   [noscript] attribute long recvBufferSize;

   /**
    * sendBufferSize
    *
    * The size of the send buffer. Default depends on the OS.
    */
   [noscript] attribute long sendBufferSize;

   /**
    * dontFragment
    *
    * The don't fragment flag.
    * The socket must be initialized before calling this function.
    */
   [noscript] attribute boolean dontFragment;
};

/**
* nsIUDPSocketListener
*
* This interface is notified whenever a UDP socket accepts a new connection.
* The transport is in the connected state, and read/write streams can be opened
* using the normal nsITransport API.  The address of the client can be found by
* calling the nsISocketTransport::GetAddress method or by inspecting
* nsISocketTransport::GetHost, which returns a string representation of the
* client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
*/
[scriptable, uuid(2E4B5DD3-7358-4281-B81F-10C62EF39CB5)]
interface nsIUDPSocketListener : nsISupports
{
   /**
    * onPacketReceived
    *
    * This method is called when a client sends a UDP packet.
    *
    * @param aSocket
    *        The UDP socket.
    * @param aMessage
    *        The message.
    */
   void onPacketReceived(in nsIUDPSocket aSocket,
                         in nsIUDPMessage aMessage);

   /**
    * onStopListening
    *
    * This method is called when the listening socket stops for some reason.
    * The UDP socket is effectively dead after this notification.
    *
    * @param aSocket
    *        The UDP socket.
    * @param aStatus
    *        The reason why the UDP socket stopped listening.  If the
    *        UDP socket was manually closed, then this value will be
    *        NS_BINDING_ABORTED.
    */
   void onStopListening(in nsIUDPSocket aSocket, in nsresult aStatus);
};

/**
* nsIUDPMessage
*
* This interface is used to encapsulate an incomming UDP message
*/
[scriptable, builtinclass, uuid(afdc743f-9cc0-40d8-b442-695dc54bbb74)]
interface nsIUDPMessage : nsISupports
{
   /**
    * Address of the source of the message
    */
   readonly attribute nsINetAddr fromAddr;

   /**
    * Data of the message
    */
   readonly attribute ACString data;

   /**
    * Stream to send a response
    */
   readonly attribute nsIOutputStream outputStream;

   /**
    * Raw Data of the message
    */
   [implicit_jscontext] readonly attribute jsval rawData;
   [noscript, notxpcom, nostdcall] Uint8TArrayRef getDataAsTArray();
};

[uuid(99f3d085-3d69-45da-a2c2-a6176af617cb)]
interface nsIUDPSocketSyncListener : nsISupports
{
   /**
    * onPacketReceived
    *
    * This method is called when a client sends an UDP packet.
    *
    * @param aSocket
    *        The UDP socket.
    * @param aMessage
    *        The message.
    */
   void onPacketReceived(in nsIUDPSocket aSocket);

   /**
    * onStopListening
    *
    * This method is called when the listening socket stops for some reason.
    * The UDP socket is effectively dead after this notification.
    *
    * @param aSocket
    *        The UDP socket.
    * @param aStatus
    *        The reason why the UDP socket stopped listening.  If the
    *        UDP socket was manually closed, then this value will be
    *        NS_BINDING_ABORTED.
    */
   void onStopListening(in nsIUDPSocket aSocket, in nsresult aStatus);
};