nsISocketTransportService.idl (6438B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 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 nsIDNSRecord; 9 interface nsIFile; 10 interface nsISocketTransport; 11 interface nsIProxyInfo; 12 interface nsIRunnable; 13 14 %{C++ 15 class nsASocketHandler; 16 struct PRFileDesc; 17 %} 18 19 [ptr] native PRFileDescPtr(PRFileDesc); 20 [ptr] native nsASocketHandlerPtr(nsASocketHandler); 21 22 [scriptable, function, uuid(338947df-2f3b-4d24-9ce4-ecf161c1b7df)] 23 interface nsISTSShutdownObserver : nsISupports { 24 25 /** 26 * Observe will be called when the SocketTransportService is shutting down, 27 * before threads are stopped. 28 */ 29 void observe(); 30 }; 31 32 [builtinclass, scriptable, uuid(ad56b25f-e6bb-4db3-9f7b-5b7db33fd2b1)] 33 interface nsISocketTransportService : nsISupports 34 { 35 /** 36 * Creates a transport for a specified host and port. 37 * 38 * @param aSocketTypes 39 * array of socket type strings. Empty array if using default 40 * socket type. 41 * @param aHost 42 * specifies the target hostname or IP address literal of the peer 43 * for this socket. 44 * @param aPort 45 * specifies the target port of the peer for this socket. 46 * @param aProxyInfo 47 * specifies the transport-layer proxy type to use. null if no 48 * proxy. used for communicating information about proxies like 49 * SOCKS (which are transparent to upper protocols). 50 * @param aDnsRecord 51 * the dns record to be used for the connection 52 * 53 * @see nsIProxiedProtocolHandler 54 * @see nsIProtocolProxyService::GetProxyInfo 55 * 56 * NOTE: this function can be called from any thread 57 */ 58 nsISocketTransport createTransport(in Array<ACString> aSocketTypes, 59 in AUTF8String aHost, 60 in long aPort, 61 in nsIProxyInfo aProxyInfo, 62 in nsIDNSRecord dnsRecord); 63 64 /** 65 * Create a transport built on a Unix domain socket, connecting to the 66 * given filename. 67 * 68 * Since Unix domain sockets are always local to the machine, they are 69 * not affected by the nsIIOService's 'offline' flag. 70 * 71 * On systems that don't support Unix domain sockets at all, this 72 * returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED. 73 * 74 * The system-level socket API may impose restrictions on the length of 75 * the filename that are stricter than those of the underlying 76 * filesystem. If the file name is too long, this returns 77 * NS_ERROR_FILE_NAME_TOO_LONG. 78 * 79 * The |aPath| parameter must specify an existing directory entry. 80 * Otherwise, this returns NS_ERROR_FILE_NOT_FOUND. 81 * 82 * The program must have search permission on all components of the 83 * path prefix of |aPath|, and read and write permission on |aPath| 84 * itself. Without such permission, this returns 85 * NS_ERROR_CONNECTION_REFUSED. 86 * 87 * The |aPath| parameter must refer to a unix-domain socket. Otherwise, 88 * this returns NS_ERROR_CONNECTION_REFUSED. (POSIX specifies 89 * ECONNREFUSED when "the target address was not listening for 90 * connections", and this is what Linux returns.) 91 * 92 * @param aPath 93 * The file name of the Unix domain socket to which we should 94 * connect. 95 */ 96 nsISocketTransport createUnixDomainTransport(in nsIFile aPath); 97 98 /** 99 * Create a transport built on a Unix domain socket that uses abstract 100 * address name. 101 * 102 * If abstract socket address isn't supported on System, this returns 103 * NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED. 104 * 105 * @param aName 106 * The name of abstract socket adress of the Unix domain socket to 107 * which we should connect. 108 */ 109 nsISocketTransport 110 createUnixDomainAbstractAddressTransport(in ACString aName); 111 112 /** 113 * Adds a new socket to the list of controlled sockets. 114 * 115 * This will fail with the error code NS_ERROR_NOT_AVAILABLE if the maximum 116 * number of sockets is already reached. 117 * In this case, the notifyWhenCanAttachSocket method should be used. 118 * 119 * @param aFd 120 * Open file descriptor of the socket to control. 121 * @param aHandler 122 * Socket handler that will receive notifications when the socket is 123 * ready or detached. 124 * 125 * NOTE: this function may only be called from an event dispatch on the 126 * socket thread. 127 */ 128 [noscript] void attachSocket(in PRFileDescPtr aFd, 129 in nsASocketHandlerPtr aHandler); 130 131 /** 132 * if the number of sockets reaches the limit, then consumers can be 133 * notified when the number of sockets becomes less than the limit. the 134 * notification is asynchronous, delivered via the given nsIRunnable 135 * instance on the socket transport thread. 136 * 137 * @param aEvent 138 * Event that will receive the notification when a new socket can 139 * be attached 140 * 141 * NOTE: this function may only be called from an event dispatch on the 142 * socket thread. 143 */ 144 [noscript] void notifyWhenCanAttachSocket(in nsIRunnable aEvent); 145 146 [noscript] void addShutdownObserver(in nsISTSShutdownObserver aObserver); 147 [noscript] void removeShutdownObserver(in nsISTSShutdownObserver aObserver); 148 }; 149 150 [builtinclass, scriptable, uuid(c5204623-5b58-4a16-8b2e-67c34dd02e3f)] 151 interface nsIRoutedSocketTransportService : nsISocketTransportService 152 { 153 // use this instead of createTransport when you have a transport 154 // that distinguishes between origin and route (aka connection) 155 nsISocketTransport createRoutedTransport(in Array<ACString> aSocketTypes, 156 in AUTF8String aHost, // origin 157 in long aPort, // origin 158 in AUTF8String aHostRoute, 159 in long aPortRoute, 160 in nsIProxyInfo aProxyInfo, 161 in nsIDNSRecord aDnsRecord); 162 };