← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/netwerk/base/public/nsIChannel.idl

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/netwerk/base/public/nsIChannel.idl
 
1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 
2
/* ***** BEGIN LICENSE BLOCK *****
 
3
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 
4
 *
 
5
 * The contents of this file are subject to the Netscape Public License
 
6
 * Version 1.1 (the "License"); you may not use this file except in
 
7
 * compliance with the License. You may obtain a copy of the License at
 
8
 * http://www.mozilla.org/NPL/
 
9
 *
 
10
 * Software distributed under the License is distributed on an "AS IS" basis,
 
11
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 
12
 * for the specific language governing rights and limitations under the
 
13
 * License.
 
14
 *
 
15
 * The Original Code is mozilla.org code.
 
16
 *
 
17
 * The Initial Developer of the Original Code is 
 
18
 * Netscape Communications Corporation.
 
19
 * Portions created by the Initial Developer are Copyright (C) 1998
 
20
 * the Initial Developer. All Rights Reserved.
 
21
 *
 
22
 * Contributor(s):
 
23
 *
 
24
 * Alternatively, the contents of this file may be used under the terms of
 
25
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 
26
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 
27
 * in which case the provisions of the GPL or the LGPL are applicable instead
 
28
 * of those above. If you wish to allow use of your version of this file only
 
29
 * under the terms of either the GPL or the LGPL, and not to allow others to
 
30
 * use your version of this file under the terms of the NPL, indicate your
 
31
 * decision by deleting the provisions above and replace them with the notice
 
32
 * and other provisions required by the GPL or the LGPL. If you do not delete
 
33
 * the provisions above, a recipient may use your version of this file under
 
34
 * the terms of any one of the NPL, the GPL or the LGPL.
 
35
 *
 
36
 * ***** END LICENSE BLOCK ***** */
 
37
 
 
38
#include "nsIRequest.idl"
 
39
 
 
40
interface nsIURI;
 
41
interface nsIInterfaceRequestor;
 
42
interface nsIInputStream;
 
43
interface nsIStreamListener;
 
44
 
 
45
/**
 
46
 * The nsIChannel interface allows clients to construct "GET" requests for
 
47
 * specific protocols, and manage them in a uniform way.  Once a channel is
 
48
 * created (via nsIIOService::newChannel), parameters for that request may
 
49
 * be set by using the channel attributes, or by QI'ing to a subclass of
 
50
 * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
 
51
 * by calling nsIChannel::open or nsIChannel::asyncOpen.
 
52
 *
 
53
 * After a request has been completed, the channel is still valid for accessing
 
54
 * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
 
55
 * response headers to be retrieved for the corresponding http transaction. 
 
56
 *
 
57
 * @status FROZEN
 
58
 */
 
59
[scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
 
60
interface nsIChannel : nsIRequest
 
61
{
 
62
    /**
 
63
     * The original URI used to construct the channel. This is used in the case
 
64
     * of a redirect or URI "resolution" (e.g. resolving a resource: URI to a
 
65
     * file: URI) so that the original pre-redirect URI can still be obtained. 
 
66
     *
 
67
     * NOTE: this is distinctly different from the http Referer (referring URI),
 
68
     * which is typically the page that contained the original URI (accessible
 
69
     * from nsIHttpChannel).
 
70
     */
 
71
    attribute nsIURI originalURI;
 
72
 
 
73
    /**
 
74
     * The URI corresponding to the channel.  Its value is immutable.
 
75
     */
 
76
    readonly attribute nsIURI URI;
 
77
 
 
78
    /**
 
79
     * The owner, corresponding to the entity that is responsible for this
 
80
     * channel.  Used by the security manager to grant or deny privileges to
 
81
     * mobile code loaded from this channel.
 
82
     *
 
83
     * NOTE: this is a strong reference to the owner, so if the owner is also
 
84
     * holding a strong reference to the channel, care must be taken to 
 
85
     * explicitly drop its reference to the channel.
 
86
     */
 
87
    attribute nsISupports owner;
 
88
 
 
89
    /**
 
90
     * The notification callbacks for the channel.  This is set by clients, who
 
91
     * wish to provide a means to receive progress, status and protocol-specific 
 
92
     * notifications.  If this value is NULL, the channel implementation may use
 
93
     * the notification callbacks from its load group.
 
94
     * 
 
95
     * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
 
96
     * and nsIAuthPrompt.
 
97
     */
 
98
    attribute nsIInterfaceRequestor notificationCallbacks;
 
99
 
 
100
    /**
 
101
     * Transport-level security information (if any) corresponding to the channel.
 
102
     */
 
103
    readonly attribute nsISupports securityInfo;
 
104
 
 
105
    /**
 
106
     * The MIME type of the channel's content if available. 
 
107
     * 
 
108
     * NOTE: the content type can often be wrongly specified (e.g., wrong file
 
109
     * extension, wrong MIME type, wrong document type stored on a server, etc.),
 
110
     * and the caller most likely wants to verify with the actual data.
 
111
     *
 
112
     * Setting contentType before the channel has been opened provides a hint
 
113
     * to the channel as to what the MIME type is.  The channel may ignore this
 
114
     * hint in deciding on the actual MIME type that it will report.
 
115
     *
 
116
     * Setting contentType after onStartRequest has been fired or after open()
 
117
     * is called will override the type determined by the channel.
 
118
     *
 
119
     * Setting contentType between the time that asyncOpen() is called and the
 
120
     * time when onStartRequest is fired has undefined behavior at this time.
 
121
     *
 
122
     * The value of the contentType attribute is a lowercase string.  A value
 
123
     * assigned to this attribute will be parsed and normalized as follows:
 
124
     *  1- any parameters (delimited with a ';') will be stripped.
 
125
     *  2- if a charset parameter is given, then its value will replace the
 
126
     *     the contentCharset attribute of the channel.
 
127
     *  3- the stripped contentType will be lowercased.
 
128
     * Any implementation of nsIChannel must follow these rules.
 
129
     */
 
130
    attribute ACString contentType;
 
131
 
 
132
    /**
 
133
     * The character set of the channel's content if available and if applicable.
 
134
     * This attribute only applies to textual data.
 
135
     *
 
136
     * The value of the contentCharset attribute is a mixedcase string.
 
137
     */
 
138
    attribute ACString contentCharset;
 
139
 
 
140
    /**
 
141
     * The length of the data associated with the channel if available.  A value
 
142
     * of -1 indicates that the content length is unknown.
 
143
     */
 
144
    attribute long contentLength;
 
145
 
 
146
    /**
 
147
     * Synchronously open the channel.
 
148
     *
 
149
     * @return blocking input stream to the channel's data.
 
150
     *
 
151
     * NOTE: nsIChannel implementations are not required to implement this
 
152
     * method.  Moreover, since this method may block the calling thread, it
 
153
     * should not be called on a thread that processes UI events.
 
154
     */
 
155
    nsIInputStream open();
 
156
 
 
157
    /**
 
158
     * Asynchronously open this channel.  Data is fed to the specified stream
 
159
     * listener as it becomes available.
 
160
     *
 
161
     * @param aListener the nsIStreamListener implementation
 
162
     * @param aContext an opaque parameter forwarded to aListener's methods
 
163
     */
 
164
    void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
 
165
 
 
166
    /**************************************************************************
 
167
     * Channel specific load flags:
 
168
     *
 
169
     * Bits 21-31 are reserved for future use by this interface or one of its
 
170
     * derivatives (e.g., see nsICachingChannel).
 
171
     */
 
172
 
 
173
    /**
 
174
     * Set (e.g., by the docshell) to indicate whether or not the channel
 
175
     * corresponds to a document URI.
 
176
     */
 
177
    const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
 
178
 
 
179
    /** 
 
180
     * If the end consumer for this load has been retargeted after discovering 
 
181
     * it's content, this flag will be set:
 
182
     */
 
183
    const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
 
184
 
 
185
    /**
 
186
     * This flag is set to indicate that onStopRequest may be followed by
 
187
     * another onStartRequest/onStopRequest pair.  This flag is, for example,
 
188
     * used by the multipart/replace stream converter.
 
189
     */
 
190
    const unsigned long LOAD_REPLACE = 1 << 18;
 
191
 
 
192
    /**
 
193
     * Set (e.g., by the docshell) to indicate whether or not the channel
 
194
     * corresponds to an initial document URI load (e.g., link click).
 
195
     */
 
196
    const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
 
197
 
 
198
    /**
 
199
     * Set (e.g., by the URILoader) to indicate whether or not the end consumer
 
200
     * for this load has been determined.
 
201
     */
 
202
    const unsigned long LOAD_TARGETED = 1 << 20;
 
203
};