• file
• revisions
• annotate
• diff
• comparison
• raw

netwerk/base/public/nsISocketTransportService.idl@b8a032363ba2 (annotated)

netwerk/base/public/nsISocketTransportService.idl

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

michael@0	1	/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
michael@0	2	/* This Source Code Form is subject to the terms of the Mozilla Public
michael@0	3	* License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0	4	* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0	5
michael@0	6	#include "nsISupports.idl"
michael@0	7
michael@0	8	interface nsIFile;
michael@0	9	interface nsISocketTransport;
michael@0	10	interface nsIProxyInfo;
michael@0	11	interface nsIRunnable;
michael@0	12
michael@0	13	%{C++
michael@0	14	class nsASocketHandler;
michael@0	15	struct PRFileDesc;
michael@0	16	%}
michael@0	17
michael@0	18	[ptr] native PRFileDescPtr(PRFileDesc);
michael@0	19	[ptr] native nsASocketHandlerPtr(nsASocketHandler);
michael@0	20
michael@0	21	[scriptable, uuid(ad56b25f-e6bb-4db3-9f7b-5b7db33fd2b1)]
michael@0	22	interface nsISocketTransportService : nsISupports
michael@0	23	{
michael@0	24	/**
michael@0	25	* Creates a transport for a specified host and port.
michael@0	26	*
michael@0	27	* @param aSocketTypes
michael@0	28	* array of socket type strings. null if using default socket type.
michael@0	29	* @param aTypeCount
michael@0	30	* specifies length of aSocketTypes.
michael@0	31	* @param aHost
michael@0	32	* specifies the target hostname or IP address literal of the peer
michael@0	33	* for this socket.
michael@0	34	* @param aPort
michael@0	35	* specifies the target port of the peer for this socket.
michael@0	36	* @param aProxyInfo
michael@0	37	* specifies the transport-layer proxy type to use. null if no
michael@0	38	* proxy. used for communicating information about proxies like
michael@0	39	* SOCKS (which are transparent to upper protocols).
michael@0	40	*
michael@0	41	* @see nsIProxiedProtocolHandler
michael@0	42	* @see nsIProtocolProxyService::GetProxyInfo
michael@0	43	*
michael@0	44	* NOTE: this function can be called from any thread
michael@0	45	*/
michael@0	46	nsISocketTransport createTransport([array, size_is(aTypeCount)]
michael@0	47	in string aSocketTypes,
michael@0	48	in unsigned long aTypeCount,
michael@0	49	in AUTF8String aHost,
michael@0	50	in long aPort,
michael@0	51	in nsIProxyInfo aProxyInfo);
michael@0	52
michael@0	53	/**
michael@0	54	* Create a transport built on a Unix domain socket, connecting to the
michael@0	55	* given filename.
michael@0	56	*
michael@0	57	* Since Unix domain sockets are always local to the machine, they are
michael@0	58	* not affected by the nsIIOService's 'offline' flag.
michael@0	59	*
michael@0	60	* On systems that don't support Unix domain sockets at all, this
michael@0	61	* returns NS_ERROR_SOCKET_ADDRESS_NOT_SUPPORTED.
michael@0	62	*
michael@0	63	* The system-level socket API may impose restrictions on the length of
michael@0	64	* the filename that are stricter than those of the underlying
michael@0	65	* filesystem. If the file name is too long, this returns
michael@0	66	* NS_ERROR_FILE_NAME_TOO_LONG.
michael@0	67	*
michael@0	68	* The |aPath| parameter must specify an existing directory entry.
michael@0	69	* Otherwise, this returns NS_ERROR_FILE_NOT_FOUND.
michael@0	70	*
michael@0	71	* The program must have search permission on all components of the
michael@0	72	* path prefix of |aPath|, and read and write permission on |aPath|
michael@0	73	* itself. Without such permission, this returns
michael@0	74	* NS_ERROR_CONNECTION_REFUSED.
michael@0	75	*
michael@0	76	* The |aPath| parameter must refer to a unix-domain socket. Otherwise,
michael@0	77	* this returns NS_ERROR_CONNECTION_REFUSED. (POSIX specifies
michael@0	78	* ECONNREFUSED when "the target address was not listening for
michael@0	79	* connections", and this is what Linux returns.)
michael@0	80	*
michael@0	81	* @param aPath
michael@0	82	* The file name of the Unix domain socket to which we should
michael@0	83	* connect.
michael@0	84	*/
michael@0	85	nsISocketTransport createUnixDomainTransport(in nsIFile aPath);
michael@0	86
michael@0	87	/**
michael@0	88	* Adds a new socket to the list of controlled sockets.
michael@0	89	*
michael@0	90	* This will fail with the error code NS_ERROR_NOT_AVAILABLE if the maximum
michael@0	91	* number of sockets is already reached.
michael@0	92	* In this case, the notifyWhenCanAttachSocket method should be used.
michael@0	93	*
michael@0	94	* @param aFd
michael@0	95	* Open file descriptor of the socket to control.
michael@0	96	* @param aHandler
michael@0	97	* Socket handler that will receive notifications when the socket is
michael@0	98	* ready or detached.
michael@0	99	*
michael@0	100	* NOTE: this function may only be called from an event dispatch on the
michael@0	101	* socket thread.
michael@0	102	*/
michael@0	103	[noscript] void attachSocket(in PRFileDescPtr aFd,
michael@0	104	in nsASocketHandlerPtr aHandler);
michael@0	105
michael@0	106	/**
michael@0	107	* if the number of sockets reaches the limit, then consumers can be
michael@0	108	* notified when the number of sockets becomes less than the limit. the
michael@0	109	* notification is asynchronous, delivered via the given nsIRunnable
michael@0	110	* instance on the socket transport thread.
michael@0	111	*
michael@0	112	* @param aEvent
michael@0	113	* Event that will receive the notification when a new socket can
michael@0	114	* be attached
michael@0	115	*
michael@0	116	* NOTE: this function may only be called from an event dispatch on the
michael@0	117	* socket thread.
michael@0	118	*/
michael@0	119	[noscript] void notifyWhenCanAttachSocket(in nsIRunnable aEvent);
michael@0	120	};