Source code

Revision control

Other Tools

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
* @return number of bytes written. (0 or length of data)
151
*/
152
unsigned long send(in AUTF8String host, in unsigned short port,
153
in Array<uint8_t> data);
154
155
/**
156
* sendWithAddr
157
*
158
* Send out the datagram to specified remote host and port.
159
*
160
* @param addr The remote host address.
161
* @param data The buffer containing the data to be written.
162
* @return number of bytes written. (0 or length of data)
163
*/
164
unsigned long sendWithAddr(in nsINetAddr addr,
165
in Array<uint8_t> data);
166
167
/**
168
* sendWithAddress
169
*
170
* Send out the datagram to specified remote address and port.
171
*
172
* @param addr The remote host address.
173
* @param data The buffer containing the data to be written.
174
* @return number of bytes written. (0 or length of data)
175
*/
176
[noscript] unsigned long sendWithAddress([const] in NetAddrPtr addr,
177
in Array<uint8_t> data);
178
179
/**
180
* sendBinaryStream
181
*
182
* Send out the datagram to specified remote address and port.
183
*
184
* @param host The remote host name.
185
* @param port The remote port.
186
* @param stream The input stream to be sent. This must be a buffered stream implementation.
187
*/
188
void sendBinaryStream(in AUTF8String host, in unsigned short port,
189
in nsIInputStream stream);
190
191
/**
192
* sendBinaryStreamWithAddress
193
*
194
* Send out the datagram to specified remote address and port.
195
*
196
* @param addr The remote host address.
197
* @param stream The input stream to be sent. This must be a buffered stream implementation.
198
*/
199
void sendBinaryStreamWithAddress([const] in NetAddrPtr addr,
200
in nsIInputStream stream);
201
202
/**
203
* joinMulticast
204
*
205
* Join the multicast group specified by |addr|. You are then able to
206
* receive future datagrams addressed to the group.
207
*
208
* @param addr
209
* The multicast group address.
210
* @param iface
211
* The local address of the interface on which to join the group. If
212
* this is not specified, the OS may join the group on all interfaces
213
* or only the primary interface.
214
*/
215
void joinMulticast(in AUTF8String addr, [optional] in AUTF8String iface);
216
[noscript] void joinMulticastAddr([const] in NetAddr addr,
217
[const, optional] in NetAddrPtr iface);
218
219
/**
220
* leaveMulticast
221
*
222
* Leave the multicast group specified by |addr|. You will no longer
223
* receive future datagrams addressed to the group.
224
*
225
* @param addr
226
* The multicast group address.
227
* @param iface
228
* The local address of the interface on which to leave the group.
229
* If this is not specified, the OS may leave the group on all
230
* interfaces or only the primary interface.
231
*/
232
void leaveMulticast(in AUTF8String addr, [optional] in AUTF8String iface);
233
[noscript] void leaveMulticastAddr([const] in NetAddr addr,
234
[const, optional] in NetAddrPtr iface);
235
236
/**
237
* multicastLoopback
238
*
239
* Whether multicast datagrams sent via this socket should be looped back to
240
* this host (assuming this host has joined the relevant group). Defaults
241
* to true.
242
* Note: This is currently write-only.
243
*/
244
attribute boolean multicastLoopback;
245
246
/**
247
* multicastInterface
248
*
249
* The interface that should be used for sending future multicast datagrams.
250
* Note: This is currently write-only.
251
*/
252
attribute AUTF8String multicastInterface;
253
254
/**
255
* multicastInterfaceAddr
256
*
257
* The interface that should be used for sending future multicast datagrams.
258
* Note: This is currently write-only.
259
*/
260
[noscript] attribute NetAddr multicastInterfaceAddr;
261
262
/**
263
* recvBufferSize
264
*
265
* The size of the receive buffer. Default depends on the OS.
266
*/
267
[noscript] attribute long recvBufferSize;
268
269
/**
270
* sendBufferSize
271
*
272
* The size of the send buffer. Default depends on the OS.
273
*/
274
[noscript] attribute long sendBufferSize;
275
};
276
277
/**
278
* nsIUDPSocketListener
279
*
280
* This interface is notified whenever a UDP socket accepts a new connection.
281
* The transport is in the connected state, and read/write streams can be opened
282
* using the normal nsITransport API. The address of the client can be found by
283
* calling the nsISocketTransport::GetAddress method or by inspecting
284
* nsISocketTransport::GetHost, which returns a string representation of the
285
* client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
286
*/
287
[scriptable, uuid(2E4B5DD3-7358-4281-B81F-10C62EF39CB5)]
288
interface nsIUDPSocketListener : nsISupports
289
{
290
/**
291
* onPacketReceived
292
*
293
* This method is called when a client sends an UDP packet.
294
*
295
* @param aSocket
296
* The UDP socket.
297
* @param aMessage
298
* The message.
299
*/
300
void onPacketReceived(in nsIUDPSocket aSocket,
301
in nsIUDPMessage aMessage);
302
303
/**
304
* onStopListening
305
*
306
* This method is called when the listening socket stops for some reason.
307
* The UDP socket is effectively dead after this notification.
308
*
309
* @param aSocket
310
* The UDP socket.
311
* @param aStatus
312
* The reason why the UDP socket stopped listening. If the
313
* UDP socket was manually closed, then this value will be
314
* NS_BINDING_ABORTED.
315
*/
316
void onStopListening(in nsIUDPSocket aSocket, in nsresult aStatus);
317
};
318
319
/**
320
* nsIUDPMessage
321
*
322
* This interface is used to encapsulate an incomming UDP message
323
*/
324
[scriptable, builtinclass, uuid(afdc743f-9cc0-40d8-b442-695dc54bbb74)]
325
interface nsIUDPMessage : nsISupports
326
{
327
/**
328
* Address of the source of the message
329
*/
330
readonly attribute nsINetAddr fromAddr;
331
332
/**
333
* Data of the message
334
*/
335
readonly attribute ACString data;
336
337
/**
338
* Stream to send a response
339
*/
340
readonly attribute nsIOutputStream outputStream;
341
342
/**
343
* Raw Data of the message
344
*/
345
[implicit_jscontext] readonly attribute jsval rawData;
346
[noscript, notxpcom, nostdcall] Uint8TArrayRef getDataAsTArray();
347
};