mozilla

nsIWebBrowserPersist

Interface for persisting DOM documents and URIs to local or remote storage.
Inherits from: nsICancelable Last changed in Gecko 36.0 (Firefox 36.0 / Thunderbird 36.0 / SeaMonkey 2.33)

Implemented by: @mozilla.org/embedding/browser/nsWebBrowser;1 and @mozilla.org/embedding/browser/nsWebBrowserPersist;1. To create an instance, use:

var webBrowserPersist = Components.classes["@mozilla.org/embedding/browser/nsWebBrowserPersist;1"]
                        .createInstance(Components.interfaces.nsIWebBrowserPersist);

Method overview

void cancelSave();
void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
void saveDocument(in nsIDOMDocument aDocument, in nsISupports aFile, in nsISupports aDataPath, in string aOutputContentType, in unsigned long aEncodingFlags, in unsigned long aWrapColumn);
void saveURI(in nsIURI aURI, in nsISupports aCacheKey, in nsIURI aReferrer, in long aReferrerPolicy, in nsIInputStream aPostData, in string aExtraHeaders, in nsISupports aFile, in nsILoadContext aPrivacyContext);
void savePrivacyAwareURI(in nsIURI aURI, in nsISupports aCacheKey, in nsIURI aReferrer, in long aReferrerPolicy, in nsIInputStream aPostData, in string aExtraHeaders, in nsISupports aFile, in boolean aIsPrivate);

Attributes

Attribute Type Description
currentState unsigned long Current state of the persister object. Read only.
persistFlags unsigned long Flags governing how data is fetched and saved from the network. It is best to set this value explicitly unless you are prepared to accept the default values.
progressListener nsIWebProgressListener Callback listener for progress notifications. The object that the embbedder supplies may also implement nsIInterfaceRequestor and be prepared to return nsIAuthPrompt or other interfaces that may be required to download data.
result unsigned long Value indicating the success or failure of the persist operation. Read only.

Constants

Constant Value Description
PERSIST_FLAGS_NONE 0 No special persistence behavior.
PERSIST_FLAGS_FROM_CACHE 1 Only use cached data (could result in failure if data is not cached).
PERSIST_FLAGS_BYPASS_CACHE 2 Bypass the cached data.
PERSIST_FLAGS_IGNORE_REDIRECTED_DATA 4 Ignore any redirected data (usually adverts).
PERSIST_FLAGS_IGNORE_IFRAMES 8 Ignore iframe content (usually adverts).
PERSIST_FLAGS_NO_CONVERSION 16 Do not run the incoming data through a content converter for example to decompress it.
PERSIST_FLAGS_REPLACE_EXISTING_FILES 32 Replace existing files on the disk (use with due diligence!)
PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS 64 Don't modify or add base tags.
PERSIST_FLAGS_FIXUP_ORIGINAL_DOM 128 Make changes to original DOM rather than cloning nodes.
PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION 256 Fix links relative to destination location (not origin)
PERSIST_FLAGS_DONT_FIXUP_LINKS 512 Do not make any adjustments to links.
PERSIST_FLAGS_SERIALIZE_OUTPUT 1024 Force serialization of output (one file at a time; not concurrent)
PERSIST_FLAGS_DONT_CHANGE_FILENAMES 2048 Don't make any adjustments to filenames.
PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS 4096 Fail on broken in-line links.
PERSIST_FLAGS_CLEANUP_ON_FAILURE 8192 Automatically cleanup after a failed or cancelled operation, deleting all created files and directories. This flag does nothing for failed upload operations to remote servers.
PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION 16384 Let the WebBrowserPersist decide whether the incoming data is encoded and whether it needs to go through a content converter, for example to decompress it.
PERSIST_FLAGS_APPEND_TO_FILE 32768 Append the downloaded data to the target file. This can only be used when persisting to a local file.
PERSIST_FLAGS_FORCE_ALLOW_COOKIES 65536 Force relevant cookies to be sent with this load even if normally they wouldn't be.
PERSIST_STATE_READY 1 Persister is ready to save data.
PERSIST_STATE_SAVING 2 Persister is saving data.
PERSIST_STATE_FINISHED 3 Persister has finished saving data.
ENCODE_FLAGS_SELECTION_ONLY 1 Output only the current selection as opposed to the whole document.
ENCODE_FLAGS_FORMATTED 2 For plain text output. Convert html to plain text that looks like the html. Implies wrap (except inside <pre>), since html wraps. HTML output: always do prettyprinting, ignoring existing formatting.
ENCODE_FLAGS_RAW 4 Output without formatting or wrapping the content. This flag may be used to preserve the original formatting as much as possible.
ENCODE_FLAGS_BODY_ONLY 8 Output only the body section, no HTML tags.
ENCODE_FLAGS_PREFORMATTED 16 Wrap even if when not doing formatted output (for example for text fields).
ENCODE_FLAGS_WRAP 32 Wrap documents at the specified column.
ENCODE_FLAGS_FORMAT_FLOWED 64 For plain text output. Output for format flowed (RFC 2646). This is used when converting to text for mail sending. This differs just slightly but in an important way from normal formatted, and that is that lines are space stuffed. This can't (correctly) be done later.
ENCODE_FLAGS_ABSOLUTE_LINKS 128 Convert links to absolute links where possible.
ENCODE_FLAGS_ENCODE_W3C_ENTITIES 256 Attempt to encode entities standardized at W3C (HTML, MathML, and so on.). This is a catch-all flag for documents with mixed contents. Beware of interoperability issues. See below for other flags which might likely do what you want.
ENCODE_FLAGS_CR_LINEBREAKS 512 Output with carriage return line breaks. May also be combined with ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform default format is used.
ENCODE_FLAGS_LF_LINEBREAKS 1024 Output with linefeed line breaks. May also be combined with ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform default format is used.
ENCODE_FLAGS_NOSCRIPT_CONTENT 2048 For plain text output. Output the content of noscript elements.
ENCODE_FLAGS_NOFRAMES_CONTENT 4096 For plain text output. Output the content of noframes elements.
ENCODE_FLAGS_ENCODE_BASIC_ENTITIES 8192 Encode basic entities, for example output   instead of character code 0xa0. The basic set is just   & < > " for interoperability with older products that don't support α and friends.
ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES 16384 Encode Latin1 entities. This includes the basic set and accented letters between 128 and 255.
ENCODE_FLAGS_ENCODE_HTML_ENTITIES 32768 Encode HTML4 entities. This includes the basic set, accented letters, Greek letters and certain special markup symbols.

Methods

cancelSave()

Cancels the current operation. The caller is responsible for cleaning up partially written files or directories. This has the same effect as calling cancel with an argument of NS_BINDING_ABORTED.

void cancelSave();
Parameters

None.

saveChannel()

Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Save a channel to a file. It must not be opened yet.

void saveChannel(
  in nsIChannel aChannel,
  in nsISupports aFile
);
Parameters
aChannel
The nsIChannel to save to a file.
aFile
Target local file. This may be a nsILocalFile object or an nsIURI object with a file scheme.

saveDocument()

Save the specified DOM document to file and optionally all linked files (for example images, CSS, JS & subframes). Do not call this method until the document has finished loading!

void saveDocument(
  in nsIDOMDocument aDocument,
  in nsISupports aFile,
  in nsISupports aDataPath,
  in string aOutputContentType,
  in unsigned long aEncodingFlags,
  in unsigned long aWrapColumn
);
Parameters
aDocument
Document to save to file. Some implementations of this interface may also support nsnull to imply the currently loaded document.
aFile
Target local file. This may be a nsILocalFile object or an nsIURI object with a file scheme or a scheme that supports uploading (for example ftp).
aDataPath
Path to directory where URIs linked to the document are saved or nsnull if no linked URIs should be saved. This may be a nsILocalFile object or an nsIURI object with a file scheme.
aOutputContentType
The desired MIME type format to save the document and all sub-documents into or nsnull to use the default behavior.
aEncodingFlags
Flags to pass to the encoder.
aWrapColumn
For text documents, indicates the desired width to wrap text at. Parameter is ignored if wrapping is not specified by the encoding flags.
Exceptions thrown
NS_ERROR_INVALID_ARG
One or more arguments was invalid.

saveURI()

As of Firefox 26, this method should no longer be used from add-on code. Please use Downloads.createDownload() instead.

As of Firefox 36, a new parameter aReferrerPolicy was added as the fourth argument, changing the number of parameters from 7 to 8 and shifting the order of the parameters in a backwards incompatible way.

Save the specified URI to file.

void saveURI(
  in nsIURI aURI,
  in nsISupports aCacheKey,
  in nsIURI aReferrer,
  in long aReferrerPolicy,
  in nsIInputStream aPostData,
  in string aExtraHeaders,
  in nsISupports aFile,
  in nsILoadContext aPrivacyContext
);
Parameters
aURI
URI to save to file. Some implementations of this interface may also support nsnull to imply the currently loaded URI.
aCacheKey
An object representing the URI in the cache or nsnull. This can be a necko cache key, an nsIWebPageDescriptor, or the currentDescriptor of an nsIWebPageDescriptor.
aReferrer
The referrer URI to pass with an HTTP request or nsnull.
aReferrerPolicy Requires Gecko 36.0
The referrer policy to use for the request, taken from nsIHttpChannel.
aPostData
Post data to pass with an HTTP request or nsnull.
aExtraHeaders
Additional headers to supply with an HTTP request or nsnull.
aFile
Target file. This may be a nsILocalFile object or an nsIURI object with a file scheme or a scheme that supports uploading (for example ftp).
aPrivacyContext
A context derived from a relevant window or document (eg. the window containing a link being saved) via a docshell that QIs to nsILoadContext. Used to ensure that privacy-sensitive operations (such as saving a URI related to a private browsing session) do not leak any information (eg. cookies, permanent cache, etc.) Null must only be passed in the event that no such relevant context exists (ie. the URI being saved is unrelated to any current browsing session).

Important: If you think that you should be passing null here, you are almost certainly wrong. null should be passed only when no plausible privacy context exists for the URI to be saved, which is an exceedingly rare corner case.

Exceptions thrown
NS_ERROR_INVALID_ARG
One or more arguments was invalid.

savePrivacyAwareURI()

Save the specified URI to file, explicitly dictating whether the operation should be considered private for the purposes of network requests, caching, etc. All arguments and exceptions are identical to saveURI, with the exception of aIsPrivate which is used to indicate the private nature of the operation.

Example

function downloadFile(httpLoc, sourceWindow) {
  try {
    //new obj_URI object
    var obj_URI = Components.classes["@mozilla.org/network/io-service;1"].getService(Components.interfaces.nsIIOService).newURI(httpLoc, null, null);

    //new file object
    var obj_TargetFile = Components.classes["@mozilla.org/file/local;1"].createInstance(Components.interfaces.nsILocalFile);

    //set file with path
    obj_TargetFile.initWithPath("c:\\temp\\test.pdf");
    //if file doesn't exist, create
    if(!obj_TargetFile.exists()) {
      obj_TargetFile.create(0x00,0644);
    }

    //new persistence object
    var obj_Persist = Components.classes["@mozilla.org/embedding/browser/nsWebBrowserPersist;1"].createInstance(Components.interfaces.nsIWebBrowserPersist);

    // with persist flags if desired
    const nsIWBP = Components.interfaces.nsIWebBrowserPersist;
    const flags = nsIWBP.PERSIST_FLAGS_REPLACE_EXISTING_FILES;
    obj_Persist.persistFlags = flags | nsIWBP.PERSIST_FLAGS_FROM_CACHE;

    var privacyContext = sourceWindow.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
                                     .getInterface(Components.interfaces.nsIWebNavigation)
                                     .QueryInterface(Components.interfaces.nsILoadContext);

    //save file to target
    obj_Persist.saveURI(obj_URI,null,null,null,null,obj_TargetFile,privacyContext);
  } catch (e) {
    alert(e);
  }
}

See also