nsIWebBrowserPersist 编辑

embedding/components/webbrowserpersist/nsIWebBrowserPersist.idlScriptable 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()

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

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);
    // Starting with Firefox 36 saveURI takes 8 parameters when called. aReferrerPolicy was added.
    // obj_Persist.saveURI(obj_URI,null,null,null,null,null,obj_TargetFile,privacyContext);
  } catch (e) {
    alert(e);
  }
}

See also

• nsICancelable