nsIWebBrowserPersist

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

Attributes

Constants

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()

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