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