1/* -*- Mode: IDL; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7#include "nsISupports.idl"
8#include "nsIContentPolicy.idl"
9
10interface nsIInputStream;
11interface nsIOutputStream;
12interface nsIPrincipal;
13interface nsIRemoteTab;
14interface nsIWebBrowserPersistResourceVisitor;
15interface nsIWebBrowserPersistWriteCompletion;
16interface nsIReferrerInfo;
17interface nsISHEntry;
18interface nsICookieJarSettings;
19
20webidl BrowsingContext;
21
22native SHEntryRef(already_AddRefed<nsISHEntry>);
23
24/**
25 * Interface for the URI-mapping information that can be supplied when
26 * serializing the DOM of an nsIWebBrowserPersistDocument.
27 *
28 * @see nsIWebBrowserPersistDocument
29 */
30[scriptable, uuid(d52e8b93-2771-45e8-a5b0-6e12b667046b)]
31interface nsIWebBrowserPersistURIMap : nsISupports
32{
33  /**
34   * The number of URI mappings.
35   */
36  readonly attribute unsigned long numMappedURIs;
37
38  /**
39   * Obtain the URI mapping at the given index, which must be less than
40   * numMappedURIs, as a pair of URI spec strings.
41   */
42  void getURIMapping(in unsigned long aIndex,
43                     out AUTF8String aMapFrom,
44                     out AUTF8String aMapTo);
45
46  /**
47   * The spec of the base URI that the document will have after it is
48   * serialized.
49   */
50  readonly attribute AUTF8String targetBaseURI;
51};
52
53/**
54 * Interface representing a document that can be serialized with
55 * nsIWebBrowserPersist; it may or may not be in this process.  Some
56 * information is exposed as attributes, which may or may not reflect
57 * changes made to the underlying document; most of these are
58 * self-explanatory from their names and types.
59 */
60[scriptable, builtinclass, uuid(74aa4918-5d15-46b6-9ccf-74f9696d721d)]
61interface nsIWebBrowserPersistDocument : nsISupports
62{
63  readonly attribute boolean isClosed;
64  readonly attribute boolean isPrivate;
65  readonly attribute AUTF8String documentURI;
66  readonly attribute AUTF8String baseURI;
67  readonly attribute ACString contentType;
68  readonly attribute ACString characterSet;
69  readonly attribute AString title;
70  readonly attribute nsIReferrerInfo referrerInfo;
71  readonly attribute nsICookieJarSettings cookieJarSettings;
72  readonly attribute AString contentDisposition;
73  readonly attribute nsIInputStream postData;
74  readonly attribute nsIPrincipal principal;
75
76  /**
77   * The cache key.  Unlike in nsISHEntry, where it's wrapped in an
78   * nsISupportsPRUint32, this is just the integer.
79   */
80  [infallible]
81  readonly attribute unsigned long cacheKey;
82
83  /**
84   * This attribute is set by nsIWebBrowserPersist implementations to
85   * propagate persist flags that apply to the DOM traversal and
86   * serialization (rather than to managing file I/O).
87   */
88  attribute unsigned long persistFlags;
89
90  /**
91   * Walk the DOM searching for external resources needed to render it.
92   * The visitor callbacks may be called either before or after
93   * readResources returns.
94   *
95   * @see nsIWebBrowserPersistResourceVisitor
96   */
97  void readResources(in nsIWebBrowserPersistResourceVisitor aVisitor);
98
99  /**
100   * Serialize the document's DOM.
101   *
102   * @param aStream       The output stream to write the document to.
103   *
104   * @param aURIMap       Optional; specifies URI rewriting to perform on
105   *                      external references (as read by readResources).
106   *                      If given, also causes relative hyperlinks to be
107   *                      converted to absolute in the written text.
108   *
109   * @param aRequestedContentType
110   *                      The desired MIME type to save the document as;
111   *                      optional and defaults to the document's type.
112   *                      (If no encoder exists for that type, "text/html"
113   *                      is used instead.)
114   *
115   * @param aEncoderFlags Flags to pass to the encoder.
116   *
117   * @param aWrapColumn   Desired text width, ignored if wrapping is not
118   *                      specified by the encoding flags, or if 0.
119   *
120   * @param aCompletion   Callback invoked when writing is complete.
121   *                      It may be called either before or after writeContent
122   *                      returns.
123   *
124   * @see nsIDocumentEncoder
125   */
126  void writeContent(in nsIOutputStream aStream,
127                    in nsIWebBrowserPersistURIMap aURIMap,
128                    in ACString aRequestedContentType,
129                    in unsigned long aEncoderFlags,
130                    in unsigned long aWrapColumn,
131                    in nsIWebBrowserPersistWriteCompletion aCompletion);
132
133  [notxpcom, nostdcall] SHEntryRef GetHistory();
134};
135
136/**
137 * Asynchronous visitor that receives external resources linked by an
138 * nsIWebBrowserPersistDocument and which are needed to render the
139 * document.
140 */
141[scriptable, uuid(8ce37706-b7d3-481a-be68-54f174fc0d0a)]
142interface nsIWebBrowserPersistResourceVisitor : nsISupports
143{
144  /**
145   * Indicates a resource that is not a document; e.g., an image, script,
146   * or stylesheet.
147   *
148   * @param aDocument   The document containing the reference.
149   * @param aURI        The absolute URI spec for the referenced resource.
150   * @param aContentPolicyType The type of resource.
151   */
152  void visitResource(in nsIWebBrowserPersistDocument aDocument,
153                     in AUTF8String aURI,
154                     in nsContentPolicyType aContentPolicyType);
155
156  /**
157   * Indicates a subdocument resource; e.g., a frame or iframe.
158   *
159   * @param aDocument     The document containing the reference.
160   * @param aSubDocument  The referenced document.
161   */
162  void visitDocument(in nsIWebBrowserPersistDocument aDocument,
163                     in nsIWebBrowserPersistDocument aSubDocument);
164
165  /**
166   * Indicates a cross origin subdocument resource; e.g., a frame
167   * or iframe loaded in another process.
168   *
169   * @param aDocument     The document containing the reference.
170   * @param aContext      The referenced document's browsing context.
171   */
172  void visitBrowsingContext(in nsIWebBrowserPersistDocument aDocument,
173                            in BrowsingContext aContext);
174
175  /**
176   * Indicates that the document traversal is complete.
177   *
178   * @param aDocument   The document that was being traversed.
179   * @param aStatus     Indicates whether the traversal encountered an error.
180   */
181  void endVisit(in nsIWebBrowserPersistDocument aDocument,
182                in nsresult aStatus);
183};
184
185/**
186 * Asynchronous callback for when nsIWebBrowserPersistDocument is finished
187 * serializing the document's DOM.
188 */
189[scriptable, function, uuid(a07e6892-38ae-4207-8340-7fa6ec446ed6)]
190interface nsIWebBrowserPersistWriteCompletion : nsISupports
191{
192  /**
193   * Indicates that serialization is finished.
194   *
195   * @param aDocument     The document that was being serialized.
196   *
197   * @param aStream       The stream that was being written to.  If it
198   *                      needs to be closed, the callback must do that;
199   *                      the serialization process leaves it open.
200   *
201   * @param aContentType  The content type with which the document was
202   *                      actually serialized; this may be useful to set
203   *                      metadata on the result, or if uploading it.
204   *
205   * @param aStatus       Indicates whether serialization encountered an error.
206   */
207  void onFinish(in nsIWebBrowserPersistDocument aDocument,
208                in nsIOutputStream aStream,
209                in ACString aContentType,
210                in nsresult aStatus);
211};
212
213/**
214 * Asynchronous callback for creating a persistable document from some
215 * other object.
216 *
217 * XXXbz This should really be changed to just return a promise that
218 * then gets resolved or rejected...
219 *
220 * @see WebBrowserPersistable in FrameLoader.webidl.
221 */
222[scriptable, uuid(321e3174-594f-4036-b7be-791b821bd376)]
223interface nsIWebBrowserPersistDocumentReceiver : nsISupports
224{
225  void onDocumentReady(in nsIWebBrowserPersistDocument aDocument);
226  void onError(in nsresult aFailure);
227};
228