/gecko_api/include/nsIIOService.h

  1/*
  2 * DO NOT EDIT.  THIS FILE IS GENERATED FROM /builds/tinderbox/XR-Trunk/Darwin_8.8.4_Depend/mozilla/netwerk/base/public/nsIIOService.idl
  3 */
  4
  5#ifndef __gen_nsIIOService_h__
  6#define __gen_nsIIOService_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 nsIProtocolHandler; /* forward declaration */
 18
 19class nsIChannel; /* forward declaration */
 20
 21class nsIURI; /* forward declaration */
 22
 23class nsIFile; /* forward declaration */
 24
 25
 26/* starting interface:    nsIIOService */
 27#define NS_IIOSERVICE_IID_STR "bddeda3f-9020-4d12-8c70-984ee9f7935e"
 28
 29#define NS_IIOSERVICE_IID \
 30  {0xbddeda3f, 0x9020, 0x4d12, \
 31    { 0x8c, 0x70, 0x98, 0x4e, 0xe9, 0xf7, 0x93, 0x5e }}
 32
 33/**
 34 * nsIIOService provides a set of network utility functions.  This interface
 35 * duplicates many of the nsIProtocolHandler methods in a protocol handler
 36 * independent way (e.g., NewURI inspects the scheme in order to delegate
 37 * creation of the new URI to the appropriate protocol handler).  nsIIOService
 38 * also provides a set of URL parsing utility functions.  These are provided
 39 * as a convenience to the programmer and in some cases to improve performance
 40 * by eliminating intermediate data structures and interfaces.
 41 *
 42 * @status FROZEN
 43 */
 44class NS_NO_VTABLE NS_SCRIPTABLE nsIIOService : public nsISupports {
 45 public: 
 46
 47  NS_DECLARE_STATIC_IID_ACCESSOR(NS_IIOSERVICE_IID)
 48
 49  /**
 50     * Returns a protocol handler for a given URI scheme.
 51     *
 52     * @param aScheme the URI scheme
 53     * @return reference to corresponding nsIProtocolHandler
 54     */
 55  /* nsIProtocolHandler getProtocolHandler (in string aScheme); */
 56  NS_SCRIPTABLE NS_IMETHOD GetProtocolHandler(const char *aScheme, nsIProtocolHandler **_retval) = 0;
 57
 58  /**
 59     * Returns the protocol flags for a given scheme.
 60     *
 61     * @param aScheme the URI scheme
 62     * @return value of corresponding nsIProtocolHandler::protocolFlags
 63     */
 64  /* unsigned long getProtocolFlags (in string aScheme); */
 65  NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(const char *aScheme, PRUint32 *_retval) = 0;
 66
 67  /**
 68     * This method constructs a new URI by determining the scheme of the
 69     * URI spec, and then delegating the construction of the URI to the
 70     * protocol handler for that scheme. QueryInterface can be used on
 71     * the resulting URI object to obtain a more specific type of URI.
 72     *
 73     * @see nsIProtocolHandler::newURI
 74     */
 75  /* nsIURI newURI (in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI); */
 76  NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval) = 0;
 77
 78  /**
 79     * This method constructs a new URI from a nsIFile.
 80     *
 81     * @param aFile specifies the file path
 82     * @return reference to a new nsIURI object
 83     */
 84  /* nsIURI newFileURI (in nsIFile aFile); */
 85  NS_SCRIPTABLE NS_IMETHOD NewFileURI(nsIFile *aFile, nsIURI **_retval) = 0;
 86
 87  /**
 88     * Creates a channel for a given URI.
 89     *
 90     * @param aURI nsIURI from which to make a channel
 91     * @return reference to the new nsIChannel object
 92     */
 93  /* nsIChannel newChannelFromURI (in nsIURI aURI); */
 94  NS_SCRIPTABLE NS_IMETHOD NewChannelFromURI(nsIURI *aURI, nsIChannel **_retval) = 0;
 95
 96  /**
 97     * Equivalent to newChannelFromURI(newURI(...))
 98     */
 99  /* nsIChannel newChannel (in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI); */
100  NS_SCRIPTABLE NS_IMETHOD NewChannel(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIChannel **_retval) = 0;
101
102  /**
103     * Returns true if networking is in "offline" mode. When in offline mode, 
104     * attempts to access the network will fail (although this does not 
105     * necessarily correlate with whether there is actually a network 
106     * available -- that's hard to detect without causing the dialer to 
107     * come up).
108     *
109     * Changing this fires observer notifications ... see below.
110     */
111  /* attribute boolean offline; */
112  NS_SCRIPTABLE NS_IMETHOD GetOffline(PRBool *aOffline) = 0;
113  NS_SCRIPTABLE NS_IMETHOD SetOffline(PRBool aOffline) = 0;
114
115  /**
116     * Checks if a port number is banned. This involves consulting a list of
117     * unsafe ports, corresponding to network services that may be easily
118     * exploitable. If the given port is considered unsafe, then the protocol
119     * handler (corresponding to aScheme) will be asked whether it wishes to
120     * override the IO service's decision to block the port. This gives the
121     * protocol handler ultimate control over its own security policy while
122     * ensuring reasonable, default protection.
123     *
124     * @see nsIProtocolHandler::allowPort
125     */
126  /* boolean allowPort (in long aPort, in string aScheme); */
127  NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 aPort, const char *aScheme, PRBool *_retval) = 0;
128
129  /**
130     * Utility to extract the scheme from a URL string, consistently and
131     * according to spec (see RFC 2396).
132     *
133     * NOTE: Most URL parsing is done via nsIURI, and in fact the scheme
134     * can also be extracted from a URL string via nsIURI.  This method
135     * is provided purely as an optimization.
136     *
137     * @param aSpec the URL string to parse
138     * @return URL scheme
139     *
140     * @throws NS_ERROR_MALFORMED_URI if URL string is not of the right form.
141     */
142  /* ACString extractScheme (in AUTF8String urlString); */
143  NS_SCRIPTABLE NS_IMETHOD ExtractScheme(const nsACString & urlString, nsACString & _retval) = 0;
144
145};
146
147  NS_DEFINE_STATIC_IID_ACCESSOR(nsIIOService, NS_IIOSERVICE_IID)
148
149/* Use this macro when declaring classes that implement this interface. */
150#define NS_DECL_NSIIOSERVICE \
151  NS_SCRIPTABLE NS_IMETHOD GetProtocolHandler(const char *aScheme, nsIProtocolHandler **_retval); \
152  NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(const char *aScheme, PRUint32 *_retval); \
153  NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval); \
154  NS_SCRIPTABLE NS_IMETHOD NewFileURI(nsIFile *aFile, nsIURI **_retval); \
155  NS_SCRIPTABLE NS_IMETHOD NewChannelFromURI(nsIURI *aURI, nsIChannel **_retval); \
156  NS_SCRIPTABLE NS_IMETHOD NewChannel(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIChannel **_retval); \
157  NS_SCRIPTABLE NS_IMETHOD GetOffline(PRBool *aOffline); \
158  NS_SCRIPTABLE NS_IMETHOD SetOffline(PRBool aOffline); \
159  NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 aPort, const char *aScheme, PRBool *_retval); \
160  NS_SCRIPTABLE NS_IMETHOD ExtractScheme(const nsACString & urlString, nsACString & _retval); 
161
162/* Use this macro to declare functions that forward the behavior of this interface to another object. */
163#define NS_FORWARD_NSIIOSERVICE(_to) \
164  NS_SCRIPTABLE NS_IMETHOD GetProtocolHandler(const char *aScheme, nsIProtocolHandler **_retval) { return _to GetProtocolHandler(aScheme, _retval); } \
165  NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(const char *aScheme, PRUint32 *_retval) { return _to GetProtocolFlags(aScheme, _retval); } \
166  NS_SCRIPTABLE NS_IMETHOD NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval) { return _to NewURI(aSpec, aOriginCharset, aBaseURI, _retval); } \
167  NS_SCRIPTABLE NS_IMETHOD NewFileURI(nsIFile *aFile, nsIURI **_retval) { return _to NewFileURI(aFile, _retval); } \
168  NS_SCRIPTABLE NS_IMETHOD NewChannelFromURI(nsIURI *aURI, nsIChannel **_retval) { return _to NewChannelFromURI(aURI, _retval); } \
169  NS_SCRIPTABLE NS_IMETHOD NewChannel(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIChannel **_retval) { return _to NewChannel(aSpec, aOriginCharset, aBaseURI, _retval); } \
170  NS_SCRIPTABLE NS_IMETHOD GetOffline(PRBool *aOffline) { return _to GetOffline(aOffline); } \
171  NS_SCRIPTABLE NS_IMETHOD SetOffline(PRBool aOffline) { return _to SetOffline(aOffline); } \
172  NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 aPort, const char *aScheme, PRBool *_retval) { return _to AllowPort(aPort, aScheme, _retval); } \
173  NS_SCRIPTABLE NS_IMETHOD ExtractScheme(const nsACString & urlString, nsACString & _retval) { return _to ExtractScheme(urlString, _retval); } 
174
175/* Use this macro to declare functions that forward the behavior of this interface to another object in a safe way. */
176#define NS_FORWARD_SAFE_NSIIOSERVICE(_to) \
177  NS_SCRIPTABLE NS_IMETHOD GetProtocolHandler(const char *aScheme, nsIProtocolHandler **_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetProtocolHandler(aScheme, _retval); } \
178  NS_SCRIPTABLE NS_IMETHOD GetProtocolFlags(const char *aScheme, PRUint32 *_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetProtocolFlags(aScheme, _retval); } \
179  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); } \
180  NS_SCRIPTABLE NS_IMETHOD NewFileURI(nsIFile *aFile, nsIURI **_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->NewFileURI(aFile, _retval); } \
181  NS_SCRIPTABLE NS_IMETHOD NewChannelFromURI(nsIURI *aURI, nsIChannel **_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->NewChannelFromURI(aURI, _retval); } \
182  NS_SCRIPTABLE NS_IMETHOD NewChannel(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIChannel **_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->NewChannel(aSpec, aOriginCharset, aBaseURI, _retval); } \
183  NS_SCRIPTABLE NS_IMETHOD GetOffline(PRBool *aOffline) { return !_to ? NS_ERROR_NULL_POINTER : _to->GetOffline(aOffline); } \
184  NS_SCRIPTABLE NS_IMETHOD SetOffline(PRBool aOffline) { return !_to ? NS_ERROR_NULL_POINTER : _to->SetOffline(aOffline); } \
185  NS_SCRIPTABLE NS_IMETHOD AllowPort(PRInt32 aPort, const char *aScheme, PRBool *_retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->AllowPort(aPort, aScheme, _retval); } \
186  NS_SCRIPTABLE NS_IMETHOD ExtractScheme(const nsACString & urlString, nsACString & _retval) { return !_to ? NS_ERROR_NULL_POINTER : _to->ExtractScheme(urlString, _retval); } 
187
188#if 0
189/* Use the code below as a template for the implementation class for this interface. */
190
191/* Header file */
192class nsIOService : public nsIIOService
193{
194public:
195  NS_DECL_ISUPPORTS
196  NS_DECL_NSIIOSERVICE
197
198  nsIOService();
199
200private:
201  ~nsIOService();
202
203protected:
204  /* additional members */
205};
206
207/* Implementation file */
208NS_IMPL_ISUPPORTS1(nsIOService, nsIIOService)
209
210nsIOService::nsIOService()
211{
212  /* member initializers and constructor code */
213}
214
215nsIOService::~nsIOService()
216{
217  /* destructor code */
218}
219
220/* nsIProtocolHandler getProtocolHandler (in string aScheme); */
221NS_IMETHODIMP nsIOService::GetProtocolHandler(const char *aScheme, nsIProtocolHandler **_retval)
222{
223    return NS_ERROR_NOT_IMPLEMENTED;
224}
225
226/* unsigned long getProtocolFlags (in string aScheme); */
227NS_IMETHODIMP nsIOService::GetProtocolFlags(const char *aScheme, PRUint32 *_retval)
228{
229    return NS_ERROR_NOT_IMPLEMENTED;
230}
231
232/* nsIURI newURI (in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI); */
233NS_IMETHODIMP nsIOService::NewURI(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIURI **_retval)
234{
235    return NS_ERROR_NOT_IMPLEMENTED;
236}
237
238/* nsIURI newFileURI (in nsIFile aFile); */
239NS_IMETHODIMP nsIOService::NewFileURI(nsIFile *aFile, nsIURI **_retval)
240{
241    return NS_ERROR_NOT_IMPLEMENTED;
242}
243
244/* nsIChannel newChannelFromURI (in nsIURI aURI); */
245NS_IMETHODIMP nsIOService::NewChannelFromURI(nsIURI *aURI, nsIChannel **_retval)
246{
247    return NS_ERROR_NOT_IMPLEMENTED;
248}
249
250/* nsIChannel newChannel (in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI); */
251NS_IMETHODIMP nsIOService::NewChannel(const nsACString & aSpec, const char *aOriginCharset, nsIURI *aBaseURI, nsIChannel **_retval)
252{
253    return NS_ERROR_NOT_IMPLEMENTED;
254}
255
256/* attribute boolean offline; */
257NS_IMETHODIMP nsIOService::GetOffline(PRBool *aOffline)
258{
259    return NS_ERROR_NOT_IMPLEMENTED;
260}
261NS_IMETHODIMP nsIOService::SetOffline(PRBool aOffline)
262{
263    return NS_ERROR_NOT_IMPLEMENTED;
264}
265
266/* boolean allowPort (in long aPort, in string aScheme); */
267NS_IMETHODIMP nsIOService::AllowPort(PRInt32 aPort, const char *aScheme, PRBool *_retval)
268{
269    return NS_ERROR_NOT_IMPLEMENTED;
270}
271
272/* ACString extractScheme (in AUTF8String urlString); */
273NS_IMETHODIMP nsIOService::ExtractScheme(const nsACString & urlString, nsACString & _retval)
274{
275    return NS_ERROR_NOT_IMPLEMENTED;
276}
277
278/* End of implementation class template. */
279#endif
280
281/**
282 * We send notifications through nsIObserverService with topic
283 * NS_IOSERVICE_GOING_OFFLINE_TOPIC and data NS_IOSERVICE_OFFLINE
284 * when 'offline' has changed from false to true, and we are about
285 * to shut down network services such as DNS. When those
286 * services have been shut down, we send a notification with
287 * topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
288 * NS_IOSERVICE_OFFLINE.
289 *
290 * When 'offline' changes from true to false, then after
291 * network services have been restarted, we send a notification
292 * with topic NS_IOSERVICE_OFFLINE_STATUS_TOPIC and data
293 * NS_IOSERVICE_ONLINE.
294 */
295#define NS_IOSERVICE_GOING_OFFLINE_TOPIC  "network:offline-about-to-go-offline"
296#define NS_IOSERVICE_OFFLINE_STATUS_TOPIC "network:offline-status-changed"
297#define NS_IOSERVICE_OFFLINE              "offline"
298#define NS_IOSERVICE_ONLINE               "online"
299
300#endif /* __gen_nsIIOService_h__ */