michael@0: /* vim:set ts=4 sw=4 et cindent: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsINetAddr;
michael@0: interface nsIUDPSocketListener;
michael@0: interface nsIUDPMessage;
michael@0: interface nsISocketTransport;
michael@0: interface nsIOutputStream;
michael@0: 
michael@0: %{ C++
michael@0: #include "nsTArrayForwardDeclare.h"
michael@0: namespace mozilla {
michael@0: namespace net {
michael@0: union NetAddr;
michael@0: }
michael@0: }
michael@0: %}
michael@0: native NetAddr(mozilla::net::NetAddr);
michael@0: [ptr] native NetAddrPtr(mozilla::net::NetAddr);
michael@0: [ref] native Uint8TArrayRef(FallibleTArray<uint8_t>);
michael@0: 
michael@0: /**
michael@0:  * nsIUDPSocket
michael@0:  *
michael@0:  * An interface to a UDP socket that can accept incoming connections.
michael@0:  */
michael@0: [scriptable, uuid(6EFE692D-F0B0-4A9E-9E63-837C7452446D)]
michael@0: interface nsIUDPSocket : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * init
michael@0:      *
michael@0:      * This method initializes a UDP socket.
michael@0:      *
michael@0:      * @param aPort
michael@0:      *        The port of the UDP socket.  Pass -1 to indicate no preference,
michael@0:      *        and a port will be selected automatically.
michael@0:      * @param aLoopbackOnly
michael@0:      *        If true, the UDP socket will only respond to connections on the
michael@0:      *        local loopback interface.  Otherwise, it will accept connections
michael@0:      *        from any interface.  To specify a particular network interface,
michael@0:      *        use initWithAddress.
michael@0:      */
michael@0:     void init(in long aPort, in boolean aLoopbackOnly);
michael@0: 
michael@0:     /**
michael@0:      * initWithAddress
michael@0:      *
michael@0:      * This method initializes a UDP socket, and binds it to a particular
michael@0:      * local address (and hence a particular local network interface).
michael@0:      *
michael@0:      * @param aAddr
michael@0:      *        The address to which this UDP socket should be bound.
michael@0:      */
michael@0:     [noscript] void initWithAddress([const] in NetAddrPtr aAddr);
michael@0: 
michael@0:     /**
michael@0:      * close
michael@0:      *
michael@0:      * This method closes a UDP socket.  This does not affect already
michael@0:      * connected client sockets (i.e., the nsISocketTransport instances
michael@0:      * created from this UDP socket).  This will cause the onStopListening
michael@0:      * event to asynchronously fire with a status of NS_BINDING_ABORTED.
michael@0:      */
michael@0:     void close();
michael@0: 
michael@0:     /**
michael@0:      * asyncListen
michael@0:      *
michael@0:      * This method puts the UDP socket in the listening state.  It will
michael@0:      * asynchronously listen for and accept client connections.  The listener
michael@0:      * will be notified once for each client connection that is accepted.  The
michael@0:      * listener's onSocketAccepted method will be called on the same thread
michael@0:      * that called asyncListen (the calling thread must have a nsIEventTarget).
michael@0:      *
michael@0:      * The listener will be passed a reference to an already connected socket
michael@0:      * transport (nsISocketTransport).  See below for more details.
michael@0:      *
michael@0:      * @param aListener
michael@0:      *        The listener to be notified when client connections are accepted.
michael@0:      */
michael@0:     void asyncListen(in nsIUDPSocketListener aListener);
michael@0: 
michael@0:     /**
michael@0:      * Returns the port of this UDP socket.
michael@0:      */
michael@0:     readonly attribute long port;
michael@0: 
michael@0:     /**
michael@0:      * Returns the address to which this UDP socket is bound.  Since a
michael@0:      * UDP socket may be bound to multiple network devices, this address
michael@0:      * may not necessarily be specific to a single network device.  In the
michael@0:      * case of an IP socket, the IP address field would be zerod out to
michael@0:      * indicate a UDP socket bound to all network devices.  Therefore,
michael@0:      * this method cannot be used to determine the IP address of the local
michael@0:      * system.  See nsIDNSService::myHostName if this is what you need.
michael@0:      */
michael@0:     [noscript] NetAddr getAddress();
michael@0: 
michael@0:     /**
michael@0:      * send
michael@0:      *
michael@0:      * Send out the datagram to specified remote host and port.
michael@0:      * DNS lookup will be triggered.
michael@0:      *
michael@0:      * @param host The remote host name.
michael@0:      * @param port The remote port.
michael@0:      * @param data The buffer containing the data to be written.
michael@0:      * @param dataLength The maximum number of bytes to be written.
michael@0:      * @return number of bytes written. (0 or dataLength)
michael@0:      */
michael@0:     unsigned long send(in AUTF8String host, in unsigned short port,
michael@0:                        [const, array, size_is(dataLength)]in uint8_t data,
michael@0:                        in unsigned long dataLength);
michael@0: 
michael@0:     /**
michael@0:      * sendWithAddr
michael@0:      *
michael@0:      * Send out the datagram to specified remote host and port.
michael@0:      *
michael@0:      * @param addr The remote host address.
michael@0:      * @param data The buffer containing the data to be written.
michael@0:      * @param dataLength The maximum number of bytes to be written.
michael@0:      * @return number of bytes written. (0 or dataLength)
michael@0:      */
michael@0:     unsigned long sendWithAddr(in nsINetAddr addr,
michael@0:                                [const, array, size_is(dataLength)]in uint8_t data,
michael@0:                                in unsigned long dataLength);
michael@0: 
michael@0:     /**
michael@0:      * sendWithAddress
michael@0:      *
michael@0:      * Send out the datagram to specified remote address and port.
michael@0:      *
michael@0:      * @param addr The remote host address.
michael@0:      * @param data The buffer containing the data to be written.
michael@0:      * @param dataLength The maximum number of bytes to be written.
michael@0:      * @return number of bytes written. (0 or dataLength)
michael@0:      */
michael@0:     [noscript] unsigned long sendWithAddress([const] in NetAddrPtr addr,
michael@0:                                              [const, array, size_is(dataLength)]in uint8_t data,
michael@0:                                              in unsigned long dataLength);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * nsIUDPSocketListener
michael@0:  *
michael@0:  * This interface is notified whenever a UDP socket accepts a new connection.
michael@0:  * The transport is in the connected state, and read/write streams can be opened
michael@0:  * using the normal nsITransport API.  The address of the client can be found by
michael@0:  * calling the nsISocketTransport::GetAddress method or by inspecting
michael@0:  * nsISocketTransport::GetHost, which returns a string representation of the
michael@0:  * client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
michael@0:  */
michael@0: [scriptable, uuid(2E4B5DD3-7358-4281-B81F-10C62EF39CB5)]
michael@0: interface nsIUDPSocketListener : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * onPacketReceived
michael@0:      *
michael@0:      * This method is called when a client sends an UDP packet.
michael@0:      *
michael@0:      * @param aSocket
michael@0:      *        The UDP socket.
michael@0:      * @param aMessage
michael@0:      *        The message.
michael@0:      */
michael@0:     void onPacketReceived(in nsIUDPSocket aSocket,
michael@0:                           in nsIUDPMessage aMessage);
michael@0: 
michael@0:     /**
michael@0:      * onStopListening
michael@0:      *
michael@0:      * This method is called when the listening socket stops for some reason.
michael@0:      * The UDP socket is effectively dead after this notification.
michael@0:      *
michael@0:      * @param aSocket
michael@0:      *        The UDP socket.
michael@0:      * @param aStatus
michael@0:      *        The reason why the UDP socket stopped listening.  If the
michael@0:      *        UDP socket was manually closed, then this value will be
michael@0:      *        NS_BINDING_ABORTED.
michael@0:      */
michael@0:     void onStopListening(in nsIUDPSocket aSocket, in nsresult aStatus);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * nsIUDPMessage
michael@0:  *
michael@0:  * This interface is used to encapsulate an incomming UDP message
michael@0:  */
michael@0: [scriptable, uuid(afdc743f-9cc0-40d8-b442-695dc54bbb74)]
michael@0: interface nsIUDPMessage : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * Address of the source of the message
michael@0:      */
michael@0:     readonly attribute nsINetAddr fromAddr;
michael@0: 
michael@0:     /**
michael@0:      * Data of the message
michael@0:      */
michael@0:     readonly attribute ACString data;
michael@0: 
michael@0:     /**
michael@0:      * Stream to send a response
michael@0:      */
michael@0:     readonly attribute nsIOutputStream outputStream;
michael@0: 
michael@0:     /**
michael@0:      * Raw Data of the message
michael@0:      */
michael@0:     [implicit_jscontext] readonly attribute jsval rawData;
michael@0:     [noscript, notxpcom, nostdcall] Uint8TArrayRef getDataAsTArray();
michael@0: };