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 nsIFile;
9
interface nsIServerSocketListener;
10
interface nsISocketTransport;
11
12
native PRNetAddr(union PRNetAddr);
13
[ptr] native PRNetAddrPtr(union PRNetAddr);
14
15
typedef unsigned long nsServerSocketFlag;
16
17
/**
18
* nsIServerSocket
19
*
20
* An interface to a server socket that can accept incoming connections.
21
*/
22
[scriptable, uuid(7a9c39cb-a13f-4eef-9bdf-a74301628742)]
23
interface nsIServerSocket : nsISupports
24
{
25
/**
26
* @name Server Socket Flags
27
* These flags define various socket options.
28
* @{
29
*/
30
/// The server socket will only respond to connections on the
31
/// local loopback interface. Otherwise, it will accept connections
32
/// from any interface. To specify a particular network interface,
33
/// use initWithAddress.
34
const nsServerSocketFlag LoopbackOnly = 0x00000001;
35
/// The server socket will not be closed when Gecko is set
36
/// offline.
37
const nsServerSocketFlag KeepWhenOffline = 0x00000002;
38
/** @} */
39
40
/**
41
* init
42
*
43
* This method initializes a server socket.
44
*
45
* @param aPort
46
* The port of the server socket. Pass -1 to indicate no preference,
47
* and a port will be selected automatically.
48
* @param aLoopbackOnly
49
* If true, the server socket will only respond to connections on the
50
* local loopback interface. Otherwise, it will accept connections
51
* from any interface. To specify a particular network interface,
52
* use initWithAddress.
53
* @param aBackLog
54
* The maximum length the queue of pending connections may grow to.
55
* This parameter may be silently limited by the operating system.
56
* Pass -1 to use the default value.
57
*/
58
void init(in long aPort,
59
in boolean aLoopbackOnly,
60
in long aBackLog);
61
62
/**
63
* the same as init(), but initializes an IPv6 server socket
64
*/
65
void initIPv6(in long aPort,
66
in boolean aLoopbackOnly,
67
in long aBackLog);
68
69
/**
70
* initSpecialConnection
71
*
72
* This method initializes a server socket and offers the ability to have
73
* that socket not get terminated if Gecko is set offline.
74
*
75
* @param aPort
76
* The port of the server socket. Pass -1 to indicate no preference,
77
* and a port will be selected automatically.
78
* @param aFlags
79
* Flags for the socket.
80
* @param aBackLog
81
* The maximum length the queue of pending connections may grow to.
82
* This parameter may be silently limited by the operating system.
83
* Pass -1 to use the default value.
84
*/
85
void initSpecialConnection(in long aPort,
86
in nsServerSocketFlag aFlags,
87
in long aBackLog);
88
89
90
/**
91
* initWithAddress
92
*
93
* This method initializes a server socket, and binds it to a particular
94
* local address (and hence a particular local network interface).
95
*
96
* @param aAddr
97
* The address to which this server socket should be bound.
98
* @param aBackLog
99
* The maximum length the queue of pending connections may grow to.
100
* This parameter may be silently limited by the operating system.
101
* Pass -1 to use the default value.
102
*/
103
[noscript] void initWithAddress([const] in PRNetAddrPtr aAddr, in long aBackLog);
104
105
/**
106
* initWithFilename
107
*
108
* This method initializes a Unix domain or "local" server socket. Such
109
* a socket has a name in the filesystem, like an ordinary file. To
110
* connect, a client supplies the socket's filename, and the usual
111
* permission checks on socket apply.
112
*
113
* This makes Unix domain sockets useful for communication between the
114
* programs being run by a specific user on a single machine: the
115
* operating system takes care of authentication, and the user's home
116
* directory or profile directory provide natural per-user rendezvous
117
* points.
118
*
119
* Since Unix domain sockets are always local to the machine, they are
120
* not affected by the nsIIOService's 'offline' flag.
121
*
122
* The system-level socket API may impose restrictions on the length of
123
* the filename that are stricter than those of the underlying
124
* filesystem. If the file name is too long, this returns
125
* NS_ERROR_FILE_NAME_TOO_LONG.
126
*
127
* All components of the path prefix of |aPath| must name directories;
128
* otherwise, this returns NS_ERROR_FILE_NOT_DIRECTORY.
129
*
130
* This call requires execute permission on all directories containing
131
* the one in which the socket is to be created, and write and execute
132
* permission on the directory itself. Otherwise, this returns
133
* NS_ERROR_CONNECTION_REFUSED.
134
*
135
* This call creates the socket's directory entry. There must not be
136
* any existing entry with the given name. If there is, this returns
137
* NS_ERROR_SOCKET_ADDRESS_IN_USE.
138
*
139
* On systems that don't support Unix domain sockets at all, this
140
* returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
141
*
142
* @param aPath nsIFile
143
* The file name at which the socket should be created.
144
*
145
* @param aPermissions unsigned long
146
* Unix-style permission bits to be applied to the new socket.
147
*
148
* Note about permissions: Linux's unix(7) man page claims that some
149
* BSD-derived systems ignore permissions on UNIX-domain sockets;
150
* NetBSD's bind(2) man page agrees, but says it does check now (dated
151
* 2005). POSIX has required 'connect' to fail if write permission on
152
* the socket itself is not granted since 2003 (Issue 6). NetBSD says
153
* that the permissions on the containing directory (execute) have
154
* always applied, so creating sockets in appropriately protected
155
* directories should be secure on both old and new systems.
156
*/
157
void initWithFilename(in nsIFile aPath, in unsigned long aPermissions,
158
in long aBacklog);
159
160
/**
161
* initWithAbstractAddress
162
*
163
* This mehtod is a flavor of initWithFilename method. This initializes
164
* a UNIX domain socket that uses abstract socket address.
165
* This socket type is only supported on Linux and Android.
166
*
167
* On systems that don't support this type's UNIX domain sockets at all,
168
* this returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
169
*
170
* @param aName
171
* The abstract socket address which the socket should be created.
172
* @param aBacklog
173
* The maximum length the queue of pending connections may grow to.
174
*/
175
void initWithAbstractAddress(in AUTF8String aName,
176
in long aBacklog);
177
178
/**
179
* close
180
*
181
* This method closes a server socket. This does not affect already
182
* connected client sockets (i.e., the nsISocketTransport instances
183
* created from this server socket). This will cause the onStopListening
184
* event to asynchronously fire with a status of NS_BINDING_ABORTED.
185
*/
186
void close();
187
188
/**
189
* asyncListen
190
*
191
* This method puts the server socket in the listening state. It will
192
* asynchronously listen for and accept client connections. The listener
193
* will be notified once for each client connection that is accepted. The
194
* listener's onSocketAccepted method will be called on the same thread
195
* that called asyncListen (the calling thread must have a nsIEventTarget).
196
*
197
* The listener will be passed a reference to an already connected socket
198
* transport (nsISocketTransport). See below for more details.
199
*
200
* @param aListener
201
* The listener to be notified when client connections are accepted.
202
*/
203
void asyncListen(in nsIServerSocketListener aListener);
204
205
/**
206
* Returns the port of this server socket.
207
*/
208
readonly attribute long port;
209
210
/**
211
* Returns the address to which this server socket is bound. Since a
212
* server socket may be bound to multiple network devices, this address
213
* may not necessarily be specific to a single network device. In the
214
* case of an IP socket, the IP address field would be zerod out to
215
* indicate a server socket bound to all network devices. Therefore,
216
* this method cannot be used to determine the IP address of the local
217
* system. See nsIDNSService::myHostName if this is what you need.
218
*/
219
[noscript] PRNetAddr getAddress();
220
};
221
222
/**
223
* nsIServerSocketListener
224
*
225
* This interface is notified whenever a server socket accepts a new connection.
226
* The transport is in the connected state, and read/write streams can be opened
227
* using the normal nsITransport API. The address of the client can be found by
228
* calling the nsISocketTransport::GetAddress method or by inspecting
229
* nsISocketTransport::GetHost, which returns a string representation of the
230
* client's IP address (NOTE: this may be an IPv4 or IPv6 string literal).
231
*/
232
[scriptable, uuid(836d98ec-fee2-4bde-b609-abd5e966eabd)]
233
interface nsIServerSocketListener : nsISupports
234
{
235
/**
236
* onSocketAccepted
237
*
238
* This method is called when a client connection is accepted.
239
*
240
* @param aServ
241
* The server socket.
242
* @param aTransport
243
* The connected socket transport.
244
*/
245
void onSocketAccepted(in nsIServerSocket aServ,
246
in nsISocketTransport aTransport);
247
248
/**
249
* onStopListening
250
*
251
* This method is called when the listening socket stops for some reason.
252
* The server socket is effectively dead after this notification.
253
*
254
* @param aServ
255
* The server socket.
256
* @param aStatus
257
* The reason why the server socket stopped listening. If the
258
* server socket was manually closed, then this value will be
259
* NS_BINDING_ABORTED.
260
*/
261
void onStopListening(in nsIServerSocket aServ, in nsresult aStatus);
262
};