/gecko_api/include/nsIProtocolHandler.h
C Header | 345 lines | 104 code | 51 blank | 190 comment | 0 complexity | e7e07786ceaf9159b9589f7f3f16276d MD5 | raw file
1/* 2 * DO NOT EDIT. THIS FILE IS GENERATED FROM /builds/tinderbox/XR-Trunk/Darwin_8.8.4_Depend/mozilla/netwerk/base/public/nsIProtocolHandler.idl 3 */ 4 5#ifndef __gen_nsIProtocolHandler_h__ 6#define __gen_nsIProtocolHandler_h__ 7 8 9#ifndef __gen_nsISupports_h__ 10#include "nsISupports.h" 11#endif 12 13/* For IDL files that don't want to include root IDL files. */ 14#ifndef NS_NO_VTABLE 15#define NS_NO_VTABLE 16#endif 17class nsIURI; /* forward declaration */ 18 19class nsIChannel; /* forward declaration */ 20 21 22/* starting interface: nsIProtocolHandler */ 23#define NS_IPROTOCOLHANDLER_IID_STR "15fd6940-8ea7-11d3-93ad-00104ba0fd40" 24 25#define NS_IPROTOCOLHANDLER_IID \ 26 {0x15fd6940, 0x8ea7, 0x11d3, \ 27 { 0x93, 0xad, 0x00, 0x10, 0x4b, 0xa0, 0xfd, 0x40 }} 28 29/** 30 * nsIProtocolHandler 31 * 32 * @status FROZEN 33 */ 34class NS_NO_VTABLE NS_SCRIPTABLE nsIProtocolHandler : public nsISupports { 35 public: 36 37 NS_DECLARE_STATIC_IID_ACCESSOR(NS_IPROTOCOLHANDLER_IID) 38 39 /** 40 * The scheme of this protocol (e.g., "file"). 41 */ 42 /* readonly attribute ACString scheme; */ 43 NS_SCRIPTABLE NS_IMETHOD GetScheme(nsACString & aScheme) = 0; 44 45 /** 46 * The default port is the port that this protocol normally uses. 47 * If a port does not make sense for the protocol (e.g., "about:") 48 * then -1 will be returned. 49 */ 50 /* readonly attribute long defaultPort; */ 51 NS_SCRIPTABLE NS_IMETHOD GetDefaultPort(PRInt32 *aDefaultPort) = 0; 52 53 /** 54 * Returns the protocol specific flags (see flag definitions below). 55 */ 56 /* readonly attribute unsigned long protocolFlags; */ 57 NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(PRUint32 *aProtocolFlags) = 0; 58 59 /** 60 * Makes a URI object that is suitable for loading by this protocol, 61 * where the URI string is given as an UTF-8 string. The caller may 62 * provide the charset from which the URI string originated, so that 63 * the URI string can be translated back to that charset (if necessary) 64 * before communicating with, for example, the origin server of the URI 65 * string. (Many servers do not support UTF-8 IRIs at the present time, 66 * so we must be careful about tracking the native charset of the origin 67 * server.) 68 * 69 * @param aSpec - the URI string in UTF-8 encoding. depending 70 * on the protocol implementation, unicode character 71 * sequences may or may not be %xx escaped. 72 * @param aOriginCharset - the charset of the document from which this URI 73 * string originated. this corresponds to the 74 * charset that should be used when communicating 75 * this URI to an origin server, for example. if 76 * null, then UTF-8 encoding is assumed (i.e., 77 * no charset transformation from aSpec). 78 * @param aBaseURI - if null, aSpec must specify an absolute URI. 79 * otherwise, aSpec may be resolved relative 80 * to aBaseURI, depending on the protocol. 81 * If the protocol has no concept of relative 82 * URI aBaseURI will simply be ignored. 83 */ 84 /* nsIURI newURI (in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI); */ 85 NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval) = 0; 86 87 /** 88 * Constructs a new channel from the given URI for this protocol handler. 89 */ 90 /* nsIChannel newChannel (in nsIURI aURI); */ 91 NS_SCRIPTABLE NS_IMETHOD NewChannel(nsIURI *aURI, nsIChannel **_retval) = 0; 92 93 /** 94 * Allows a protocol to override blacklisted ports. 95 * 96 * This method will be called when there is an attempt to connect to a port 97 * that is blacklisted. For example, for most protocols, port 25 (Simple Mail 98 * Transfer) is banned. When a URI containing this "known-to-do-bad-things" 99 * port number is encountered, this function will be called to ask if the 100 * protocol handler wants to override the ban. 101 */ 102 /* boolean allowPort (in long port, in string scheme); */ 103 NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 port, const char *scheme, PRBool *_retval) = 0; 104 105 /************************************************************************** 106 * Constants for the protocol flags (the first is the default mask, the 107 * others are deviations): 108 * 109 * NOTE: Implementation must ignore any flags they do not understand. 110 */ 111/** 112 * standard full URI with authority component and concept of relative 113 * URIs (http, ftp, ...) 114 */ 115 enum { URI_STD = 0U }; 116 117 /** 118 * no concept of relative URIs (about, javascript, finger, ...) 119 */ 120 enum { URI_NORELATIVE = 1U }; 121 122 /** 123 * no authority component (file, ...) 124 */ 125 enum { URI_NOAUTH = 2U }; 126 127 /** 128 * The URIs for this protocol have no inherent security context, so 129 * documents loaded via this protocol should inherit the security context 130 * from the document that loads them. 131 */ 132 enum { URI_INHERITS_SECURITY_CONTEXT = 16U }; 133 134 /** 135 * "Automatic" loads that would replace the document (e.g. <meta> refresh, 136 * certain types of XLinks, possibly other loads that the application 137 * decides are not user triggered) are not allowed if the originating (NOT 138 * the target) URI has this protocol flag. Note that the decision as to 139 * what constitutes an "automatic" load is made externally, by the caller 140 * of nsIScriptSecurityManager::CheckLoadURI. See documentation for that 141 * method for more information. 142 * 143 * A typical protocol that might want to set this flag is a protocol that 144 * shows highly untrusted content in a viewing area that the user expects 145 * to have a lot of control over, such as an e-mail reader. 146 */ 147 enum { URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT = 32U }; 148 149 /** 150 * +-------------------------------------------------------------------+ 151 * | | 152 * | ALL PROTOCOL HANDLERS MUST SET ONE OF THE FOLLOWING FOUR FLAGS. | 153 * | | 154 * +-------------------------------------------------------------------+ 155 * 156 * These flags are used to determine who is allowed to load URIs for this 157 * protocol. Note that if a URI is nested, only the flags for the 158 * innermost URI matter. See nsINestedURI. 159 * 160 * If none of these four flags are set, the URI must be treated as if it 161 * had the URI_LOADABLE_BY_ANYONE flag set, for compatibility with protocol 162 * handlers written against Gecko 1.8 or earlier. In this case, there may 163 * be run-time warning messages indicating that a "default insecure" 164 * assumption is being made. At some point in the futures (Mozilla 2.0, 165 * most likely), these warnings will become errors. 166 */ 167/** 168 * The URIs for this protocol can be loaded by anyone. For example, any 169 * website should be allowed to trigger a load of a URI for this protocol. 170 * Web-safe protocols like "http" should set this flag. 171 */ 172 enum { URI_LOADABLE_BY_ANYONE = 64U }; 173 174 /** 175 * The URIs for this protocol are UNSAFE if loaded by untrusted (web) 176 * content and may only be loaded by privileged code (for example, code 177 * which has the system principal). Various internal protocols should set 178 * this flag. 179 */ 180 enum { URI_DANGEROUS_TO_LOAD = 128U }; 181 182 /** 183 * The URIs for this protocol point to resources that are part of the 184 * application's user interface. There are cases when such resources may 185 * be made accessible to untrusted content such as web pages, so this is 186 * less restrictive than URI_DANGEROUS_TO_LOAD but more restrictive than 187 * URI_LOADABLE_BY_ANYONE. See the documentation for 188 * nsIScriptSecurityManager::CheckLoadURI. 189 */ 190 enum { URI_IS_UI_RESOURCE = 256U }; 191 192 /** 193 * Loading of URIs for this protocol from other origins should only be 194 * allowed if those origins should have access to the local filesystem. 195 * It's up to the application to decide what origins should have such 196 * access. Protocols like "file" that point to local data should set this 197 * flag. 198 */ 199 enum { URI_IS_LOCAL_FILE = 512U }; 200 201 /** 202 * Loading channels from this protocol has side-effects that make 203 * it unsuitable for saving to a local file. 204 */ 205 enum { URI_NON_PERSISTABLE = 1024U }; 206 207 /** 208 * Channels using this protocol never call OnDataAvailable 209 * on the listener passed to AsyncOpen and they therefore 210 * do not return any data that we can use. 211 */ 212 enum { URI_DOES_NOT_RETURN_DATA = 2048U }; 213 214 /** 215 * This protocol handler can be proxied via a proxy (socks or http) 216 * (e.g., irc, smtp, http, etc.). If the protocol supports transparent 217 * proxying, the handler should implement nsIProxiedProtocolHandler. 218 * 219 * If it supports only HTTP proxying, then it need not support 220 * nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP 221 * flag (see below). 222 * 223 * @see nsIProxiedProtocolHandler 224 */ 225 enum { ALLOWS_PROXY = 4U }; 226 227 /** 228 * This protocol handler can be proxied using a http proxy (e.g., http, 229 * ftp, etc.). nsIIOService::newChannelFromURI will feed URIs from this 230 * protocol handler to the HTTP protocol handler instead. This flag is 231 * ignored if ALLOWS_PROXY is not set. 232 */ 233 enum { ALLOWS_PROXY_HTTP = 8U }; 234 235}; 236 237 NS_DEFINE_STATIC_IID_ACCESSOR(nsIProtocolHandler, NS_IPROTOCOLHANDLER_IID) 238 239/* Use this macro when declaring classes that implement this interface. */ 240#define NS_DECL_NSIPROTOCOLHANDLER \ 241 NS_SCRIPTABLE NS_IMETHOD GetScheme(nsACString & aScheme); \ 242 NS_SCRIPTABLE NS_IMETHOD GetDefaultPort(PRInt32 *aDefaultPort); \ 243 NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(PRUint32 *aProtocolFlags); \ 244 NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval); \ 245 NS_SCRIPTABLE NS_IMETHOD NewChannel(nsIURI *aURI, nsIChannel **_retval); \ 246 NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 port, const char *scheme, PRBool *_retval); \ 247 248/* Use this macro to declare functions that forward the behavior of this interface to another object. */ 249#define NS_FORWARD_NSIPROTOCOLHANDLER(_to) \ 250 NS_SCRIPTABLE NS_IMETHOD GetScheme(nsACString & aScheme) { return _to GetScheme(aScheme); } \ 251 NS_SCRIPTABLE NS_IMETHOD GetDefaultPort(PRInt32 *aDefaultPort) { return _to GetDefaultPort(aDefaultPort); } \ 252 NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(PRUint32 *aProtocolFlags) { return _to GetProtocolFlags(aProtocolFlags); } \ 253 NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval) { return _to NewURI(aSpec, aOriginCharset, aBaseURI, _retval); } \ 254 NS_SCRIPTABLE NS_IMETHOD NewChannel(nsIURI *aURI, nsIChannel **_retval) { return _to NewChannel(aURI, _retval); } \ 255 NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 port, const char *scheme, PRBool *_retval) { return _to AllowPort(port, scheme, _retval); } \ 256 257/* Use this macro to declare functions that forward the behavior of this interface to another object in a safe way. */ 258#define NS_FORWARD_SAFE_NSIPROTOCOLHANDLER(_to) \ 259 NS_SCRIPTABLE NS_IMETHOD GetScheme(nsACString & aScheme) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetScheme(aScheme); } \ 260 NS_SCRIPTABLE NS_IMETHOD GetDefaultPort(PRInt32 *aDefaultPort) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetDefaultPort(aDefaultPort); } \ 261 NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(PRUint32 *aProtocolFlags) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetProtocolFlags(aProtocolFlags); } \ 262 NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->NewURI(aSpec, aOriginCharset, aBaseURI, _retval); } \ 263 NS_SCRIPTABLE NS_IMETHOD NewChannel(nsIURI *aURI, nsIChannel **_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->NewChannel(aURI, _retval); } \ 264 NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 port, const char *scheme, PRBool *_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->AllowPort(port, scheme, _retval); } \ 265 266#if 0 267/* Use the code below as a template for the implementation class for this interface. */ 268 269/* Header file */ 270class nsProtocolHandler : public nsIProtocolHandler 271{ 272public: 273 NS_DECL_ISUPPORTS 274 NS_DECL_NSIPROTOCOLHANDLER 275 276 nsProtocolHandler(); 277 278private: 279 ~nsProtocolHandler(); 280 281protected: 282 /* additional members */ 283}; 284 285/* Implementation file */ 286NS_IMPL_ISUPPORTS1(nsProtocolHandler, nsIProtocolHandler) 287 288nsProtocolHandler::nsProtocolHandler() 289{ 290 /* member initializers and constructor code */ 291} 292 293nsProtocolHandler::~nsProtocolHandler() 294{ 295 /* destructor code */ 296} 297 298/* readonly attribute ACString scheme; */ 299NS_IMETHODIMP nsProtocolHandler::GetScheme(nsACString & aScheme) 300{ 301 return NS_ERROR_NOT_IMPLEMENTED; 302} 303 304/* readonly attribute long defaultPort; */ 305NS_IMETHODIMP nsProtocolHandler::GetDefaultPort(PRInt32 *aDefaultPort) 306{ 307 return NS_ERROR_NOT_IMPLEMENTED; 308} 309 310/* readonly attribute unsigned long protocolFlags; */ 311NS_IMETHODIMP nsProtocolHandler::GetProtocolFlags(PRUint32 *aProtocolFlags) 312{ 313 return NS_ERROR_NOT_IMPLEMENTED; 314} 315 316/* nsIURI newURI (in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI); */ 317NS_IMETHODIMP nsProtocolHandler::NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval) 318{ 319 return NS_ERROR_NOT_IMPLEMENTED; 320} 321 322/* nsIChannel newChannel (in nsIURI aURI); */ 323NS_IMETHODIMP nsProtocolHandler::NewChannel(nsIURI *aURI, nsIChannel **_retval) 324{ 325 return NS_ERROR_NOT_IMPLEMENTED; 326} 327 328/* boolean allowPort (in long port, in string scheme); */ 329NS_IMETHODIMP nsProtocolHandler::AllowPort(PRInt32 port, const char *scheme, PRBool *_retval) 330{ 331 return NS_ERROR_NOT_IMPLEMENTED; 332} 333 334/* End of implementation class template. */ 335#endif 336 337/** 338 * Protocol handlers are registered with XPCOM under the following CONTRACTID prefix: 339 */ 340#define NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX "@mozilla.org/network/protocol;1?name=" 341/** 342 * For example, "@mozilla.org/network/protocol;1?name=http" 343 */ 344 345#endif /* __gen_nsIProtocolHandler_h__ */