1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIUDPSocket.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,219 @@
1.4 +/* vim:set ts=4 sw=4 et cindent: */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsINetAddr;
1.12 +interface nsIUDPSocketListener;
1.13 +interface nsIUDPMessage;
1.14 +interface nsISocketTransport;
1.15 +interface nsIOutputStream;
1.16 +
1.17 +%{ C++
1.18 +#include "nsTArrayForwardDeclare.h"
1.19 +namespace mozilla {
1.20 +namespace net {
1.21 +union NetAddr;
1.22 +}
1.23 +}
1.24 +%}
1.25 +native NetAddr(mozilla::net::NetAddr);
1.26 +[ptr] native NetAddrPtr(mozilla::net::NetAddr);
1.27 +[ref] native Uint8TArrayRef(FallibleTArray<uint8_t>);
1.28 +
1.29 +/**
1.30 + * nsIUDPSocket
1.31 + *
1.32 + * An interface to a UDP socket that can accept incoming connections.
1.33 + */
1.34 +[scriptable, uuid(6EFE692D-F0B0-4A9E-9E63-837C7452446D)]
1.35 +interface nsIUDPSocket : nsISupports
1.36 +{
1.37 + /**
1.38 + * init
1.39 + *
1.40 + * This method initializes a UDP socket.
1.41 + *
1.42 + * @param aPort
1.43 + * The port of the UDP socket. Pass -1 to indicate no preference,
1.44 + * and a port will be selected automatically.
1.45 + * @param aLoopbackOnly
1.46 + * If true, the UDP socket will only respond to connections on the
1.47 + * local loopback interface. Otherwise, it will accept connections
1.48 + * from any interface. To specify a particular network interface,
1.49 + * use initWithAddress.
1.50 + */
1.51 + void init(in long aPort, in boolean aLoopbackOnly);
1.52 +
1.53 + /**
1.54 + * initWithAddress
1.55 + *
1.56 + * This method initializes a UDP socket, and binds it to a particular
1.57 + * local address (and hence a particular local network interface).
1.58 + *
1.59 + * @param aAddr
1.60 + * The address to which this UDP socket should be bound.
1.61 + */
1.62 + [noscript] void initWithAddress([const] in NetAddrPtr aAddr);
1.63 +
1.64 + /**
1.65 + * close
1.66 + *
1.67 + * This method closes a UDP socket. This does not affect already
1.68 + * connected client sockets (i.e., the nsISocketTransport instances
1.69 + * created from this UDP socket). This will cause the onStopListening
1.70 + * event to asynchronously fire with a status of NS_BINDING_ABORTED.
1.71 + */
1.72 + void close();
1.73 +
1.74 + /**
1.75 + * asyncListen
1.76 + *
1.77 + * This method puts the UDP socket in the listening state. It will
1.78 + * asynchronously listen for and accept client connections. The listener
1.79 + * will be notified once for each client connection that is accepted. The
1.80 + * listener's onSocketAccepted method will be called on the same thread
1.81 + * that called asyncListen (the calling thread must have a nsIEventTarget).
1.82 + *
1.83 + * The listener will be passed a reference to an already connected socket
1.84 + * transport (nsISocketTransport). See below for more details.
1.85 + *
1.86 + * @param aListener
1.87 + * The listener to be notified when client connections are accepted.
1.88 + */
1.89 + void asyncListen(in nsIUDPSocketListener aListener);
1.90 +
1.91 + /**
1.92 + * Returns the port of this UDP socket.
1.93 + */
1.94 + readonly attribute long port;
1.95 +
1.96 + /**
1.97 + * Returns the address to which this UDP socket is bound. Since a
1.98 + * UDP socket may be bound to multiple network devices, this address
1.99 + * may not necessarily be specific to a single network device. In the
1.100 + * case of an IP socket, the IP address field would be zerod out to
1.101 + * indicate a UDP socket bound to all network devices. Therefore,
1.102 + * this method cannot be used to determine the IP address of the local
1.103 + * system. See nsIDNSService::myHostName if this is what you need.
1.104 + */
1.105 + [noscript] NetAddr getAddress();
1.106 +
1.107 + /**
1.108 + * send
1.109 + *
1.110 + * Send out the datagram to specified remote host and port.
1.111 + * DNS lookup will be triggered.
1.112 + *
1.113 + * @param host The remote host name.
1.114 + * @param port The remote port.
1.115 + * @param data The buffer containing the data to be written.
1.116 + * @param dataLength The maximum number of bytes to be written.
1.117 + * @return number of bytes written. (0 or dataLength)
1.118 + */
1.119 + unsigned long send(in AUTF8String host, in unsigned short port,
1.120 + [const, array, size_is(dataLength)]in uint8_t data,
1.121 + in unsigned long dataLength);
1.122 +
1.123 + /**
1.124 + * sendWithAddr
1.125 + *
1.126 + * Send out the datagram to specified remote host and port.
1.127 + *
1.128 + * @param addr The remote host address.
1.129 + * @param data The buffer containing the data to be written.
1.130 + * @param dataLength The maximum number of bytes to be written.
1.131 + * @return number of bytes written. (0 or dataLength)
1.132 + */
1.133 + unsigned long sendWithAddr(in nsINetAddr addr,
1.134 + [const, array, size_is(dataLength)]in uint8_t data,
1.135 + in unsigned long dataLength);
1.136 +
1.137 + /**
1.138 + * sendWithAddress
1.139 + *
1.140 + * Send out the datagram to specified remote address and port.
1.141 + *
1.142 + * @param addr The remote host address.
1.143 + * @param data The buffer containing the data to be written.
1.144 + * @param dataLength The maximum number of bytes to be written.
1.145 + * @return number of bytes written. (0 or dataLength)
1.146 + */
1.147 + [noscript] unsigned long sendWithAddress([const] in NetAddrPtr addr,
1.148 + [const, array, size_is(dataLength)]in uint8_t data,
1.149 + in unsigned long dataLength);
1.150 +};
1.151 +
1.152 +/**
1.153 + * nsIUDPSocketListener
1.154 + *
1.155 + * This interface is notified whenever a UDP socket accepts a new connection.
1.156 + * The transport is in the connected state, and read/write streams can be opened
1.157 + * using the normal nsITransport API. The address of the client can be found by
1.158 + * calling the nsISocketTransport::GetAddress method or by inspecting
1.159 + * nsISocketTransport::GetHost, which returns a string representation of the
1.160 + * client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
1.161 + */
1.162 +[scriptable, uuid(2E4B5DD3-7358-4281-B81F-10C62EF39CB5)]
1.163 +interface nsIUDPSocketListener : nsISupports
1.164 +{
1.165 + /**
1.166 + * onPacketReceived
1.167 + *
1.168 + * This method is called when a client sends an UDP packet.
1.169 + *
1.170 + * @param aSocket
1.171 + * The UDP socket.
1.172 + * @param aMessage
1.173 + * The message.
1.174 + */
1.175 + void onPacketReceived(in nsIUDPSocket aSocket,
1.176 + in nsIUDPMessage aMessage);
1.177 +
1.178 + /**
1.179 + * onStopListening
1.180 + *
1.181 + * This method is called when the listening socket stops for some reason.
1.182 + * The UDP socket is effectively dead after this notification.
1.183 + *
1.184 + * @param aSocket
1.185 + * The UDP socket.
1.186 + * @param aStatus
1.187 + * The reason why the UDP socket stopped listening. If the
1.188 + * UDP socket was manually closed, then this value will be
1.189 + * NS_BINDING_ABORTED.
1.190 + */
1.191 + void onStopListening(in nsIUDPSocket aSocket, in nsresult aStatus);
1.192 +};
1.193 +
1.194 +/**
1.195 + * nsIUDPMessage
1.196 + *
1.197 + * This interface is used to encapsulate an incomming UDP message
1.198 + */
1.199 +[scriptable, uuid(afdc743f-9cc0-40d8-b442-695dc54bbb74)]
1.200 +interface nsIUDPMessage : nsISupports
1.201 +{
1.202 + /**
1.203 + * Address of the source of the message
1.204 + */
1.205 + readonly attribute nsINetAddr fromAddr;
1.206 +
1.207 + /**
1.208 + * Data of the message
1.209 + */
1.210 + readonly attribute ACString data;
1.211 +
1.212 + /**
1.213 + * Stream to send a response
1.214 + */
1.215 + readonly attribute nsIOutputStream outputStream;
1.216 +
1.217 + /**
1.218 + * Raw Data of the message
1.219 + */
1.220 + [implicit_jscontext] readonly attribute jsval rawData;
1.221 + [noscript, notxpcom, nostdcall] Uint8TArrayRef getDataAsTArray();
1.222 +};
