Struct xpcom::interfaces::nsIBackgroundFileSaver
[−]
[src]
#[repr(C)]pub struct nsIBackgroundFileSaver { /* fields omitted */ }
interface nsIBackgroundFileSaver : nsISupports
/**
* Allows saving data to a file, while handling all the input/output on a
* background thread, including the initial file name assignment and any
* subsequent renaming of the target file.
*
* This interface is designed for file downloads. Generally, they start in the
* temporary directory, while the user is selecting the final name. Then, they
* are moved to the chosen target directory with a ".part" extension appended to
* the file name. Finally, they are renamed when the download is completed.
*
* Components implementing both nsIBackgroundFileSaver and nsIStreamListener
* allow data to be fed using an implementation of OnDataAvailable that never
* blocks the calling thread. They suspend the request that drives the stream
* listener in case too much data is being fed, and resume it when the data has
* been written. Calling OnStopRequest does not necessarily close the target
* file, and the Finish method must be called to complete the operation.
*
* Components implementing both nsIBackgroundFileSaver and nsIAsyncOutputStream
* allow data to be fed directly to the non-blocking output stream, that however
* may return NS_BASE_STREAM_WOULD_BLOCK in case too much data is being fed.
* Closing the output stream does not necessarily close the target file, and the
* Finish method must be called to complete the operation.
*
* @remarks Implementations may require the consumer to always call Finish. If
* the object reference is released without calling Finish, a memory
* leak may occur, and the target file might be kept locked. All
* public methods of the interface may only be called from the main
* thread.
*/
Methods
impl nsIBackgroundFileSaver
[src]
pub fn coerce<T: nsIBackgroundFileSaverCoerce>(&self) -> &T
[src]
Cast this nsIBackgroundFileSaver
to one of its base interfaces.
impl nsIBackgroundFileSaver
[src]
pub unsafe fn GetObserver(
&self,
aObserver: *mut *const nsIBackgroundFileSaverObserver
) -> nsresult
[src]
&self,
aObserver: *mut *const nsIBackgroundFileSaverObserver
) -> nsresult
/**
* This observer receives notifications when the target file name changes and
* when the operation completes, successfully or not.
*
* @remarks A strong reference to the observer is held. Notification events
* are dispatched to the thread that created the object that
* implements nsIBackgroundFileSaver.
*/
attribute nsIBackgroundFileSaverObserver observer;
pub unsafe fn SetObserver(
&self,
aObserver: *const nsIBackgroundFileSaverObserver
) -> nsresult
[src]
&self,
aObserver: *const nsIBackgroundFileSaverObserver
) -> nsresult
/**
* This observer receives notifications when the target file name changes and
* when the operation completes, successfully or not.
*
* @remarks A strong reference to the observer is held. Notification events
* are dispatched to the thread that created the object that
* implements nsIBackgroundFileSaver.
*/
attribute nsIBackgroundFileSaverObserver observer;
pub unsafe fn GetSignatureInfo(
&self,
aSignatureInfo: *mut *const nsIArray
) -> nsresult
[src]
&self,
aSignatureInfo: *mut *const nsIArray
) -> nsresult
/**
* An nsIArray of nsIX509CertList, representing a chain of X.509 signatures on
* the downloaded file. Each list may belong to a different signer and contain
* certificates all the way up to the root.
*
* @throws NS_ERROR_NOT_AVAILABLE
* In case this is called before the onSaveComplete method has been
* called to notify success, or enableSignatureInfo has not been
* called.
*/
readonly attribute nsIArray signatureInfo;
pub unsafe fn GetSha256Hash(&self, aSha256Hash: &mut nsACString) -> nsresult
[src]
/**
* The SHA-256 hash, in raw bytes, associated with the data that was saved.
*
* In case the enableAppend method has been called, the hash computation
* includes the contents of the existing file, if any.
*
* @throws NS_ERROR_NOT_AVAILABLE
* In case the enableSha256 method has not been called, or before the
* onSaveComplete method has been called to notify success.
*/
readonly attribute ACString sha256Hash;
pub unsafe fn EnableSignatureInfo(&self) -> nsresult
[src]
/**
* Instructs the component to compute the signatureInfo of the target file,
* and make it available in the signatureInfo property.
*
* @remarks This must be set on the main thread before the first call to
* setTarget.
*/
void enableSignatureInfo ();
pub unsafe fn EnableSha256(&self) -> nsresult
[src]
/**
* Instructs the component to compute the SHA-256 hash of the target file, and
* make it available in the sha256Hash property.
*
* @remarks This must be set on the main thread before the first call to
* setTarget.
*/
void enableSha256 ();
pub unsafe fn EnableAppend(&self) -> nsresult
[src]
/**
* Instructs the component to append data to the initial target file, that
* will be specified by the first call to the setTarget method, instead of
* overwriting the file.
*
* If the initial target file does not exist, this method has no effect.
*
* @remarks This must be set on the main thread before the first call to
* setTarget.
*/
void enableAppend ();
pub unsafe fn SetTarget(
&self,
aTarget: *const nsIFile,
aKeepPartial: bool
) -> nsresult
[src]
&self,
aTarget: *const nsIFile,
aKeepPartial: bool
) -> nsresult
/**
* Sets the name of the output file to be written. The target can be changed
* after data has already been fed, in which case the existing file will be
* moved to the new destination.
*
* In case the specified file already exists, and this method is called for
* the first time, the file may be either overwritten or appended to, based on
* whether the enableAppend method was called. Subsequent calls always
* overwrite the specified target file with the previously saved data.
*
* No file will be written until this function is called at least once. It's
* recommended not to feed any data until the output file is set.
*
* If an input/output error occurs with the specified file, the save operation
* fails. Failure is notified asynchronously through the observer.
*
* @param aTarget
* New output file to be written.
* @param aKeepPartial
* Indicates whether aFile should be kept as partially completed,
* rather than deleted, if the operation fails or is canceled. This is
* generally set for downloads that use temporary ".part" files.
*/
void setTarget (in nsIFile aTarget, in bool aKeepPartial);
pub unsafe fn Finish(&self, aStatus: nsresult) -> nsresult
[src]
/**
* Terminates access to the output file, then notifies the observer with the
* specified status code. A failure code will force the operation to be
* canceled, in which case the output file will be deleted if requested.
*
* This forces the involved streams to be closed, thus no more data should be
* fed to the component after this method has been called.
*
* This is the last method that should be called on this object, and the
* target file name cannot be changed anymore after this method has been
* called. Conversely, before calling this method, the file can still be
* renamed even if all the data has been fed.
*
* @param aStatus
* Result code that determines whether the operation should succeed or
* be canceled, and is notified to the observer. If the operation
* fails meanwhile for other reasons, or the observer has been already
* notified of completion, this status code is ignored.
*/
void finish (in nsresult aStatus);
Methods from Deref<Target = nsISupports>
pub fn coerce<T: nsISupportsCoerce>(&self) -> &T
[src]
Cast this nsISupports
to one of its base interfaces.
pub unsafe fn QueryInterface(
&self,
uuid: &nsIID,
result: *mut *mut c_void
) -> nsresult
[src]
&self,
uuid: &nsIID,
result: *mut *mut c_void
) -> nsresult
void QueryInterface (in nsIIDRef uuid, [iid_is (uuid), retval] out nsQIResult result);
pub unsafe fn AddRef(&self) -> nsrefcnt
[src]
[noscript,notxpcom] nsrefcnt AddRef ();
pub unsafe fn Release(&self) -> nsrefcnt
[src]
[noscript,notxpcom] nsrefcnt Release ();
Trait Implementations
impl XpCom for nsIBackgroundFileSaver
[src]
const IID: nsIID
IID: nsIID = nsID(3291825316, 26668, 16994, [180, 7, 36, 83, 210, 110, 102, 13])
fn query_interface<T: XpCom>(&self) -> Option<RefPtr<T>>
[src]
Perform a QueryInterface call on this object, attempting to dynamically cast it to the requested interface type. Returns Some(RefPtr) if the cast succeeded, and None otherwise. Read more
impl RefCounted for nsIBackgroundFileSaver
[src]
unsafe fn addref(&self)
[src]
Increment the reference count.
unsafe fn release(&self)
[src]
Decrement the reference count, potentially freeing backing memory.
impl Deref for nsIBackgroundFileSaver
[src]
type Target = nsISupports
The resulting type after dereferencing.
fn deref(&self) -> &nsISupports
[src]
Dereferences the value.