nsIWebBrowserPersistDocument.idl (8121B)
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 10 interface nsIInputStream; 11 interface nsIOutputStream; 12 interface nsIPrincipal; 13 interface nsIRemoteTab; 14 interface nsIWebBrowserPersistResourceVisitor; 15 interface nsIWebBrowserPersistWriteCompletion; 16 interface nsIReferrerInfo; 17 interface nsISHEntry; 18 interface nsICookieJarSettings; 19 20 webidl BrowsingContext; 21 22 native 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)] 31 interface 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)] 61 interface 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)] 142 interface 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)] 190 interface 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)] 223 interface nsIWebBrowserPersistDocumentReceiver : nsISupports 224 { 225 void onDocumentReady(in nsIWebBrowserPersistDocument aDocument); 226 void onError(in nsresult aFailure); 227 };