Mozilla/mozilla/netwerk/base/public/nsIRequest.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"

interface nsILoadGroup;

typedef unsigned long nsLoadFlags;

/**
 * nsIRequest
 *
 * @status UNDER_REVIEW
 */
[scriptable, uuid(F2CAABA0-2F25-11d3-A164-0050041CAF44)]
interface nsIRequest : nsISupports
{
    /**
     * Returns the name of the request.  Often this is the URL of the request.
     */
    readonly attribute wstring name;

    /**
     * Returns true if the request is pending (active).  Returns false 
     * after completion or successful calling Cancel.  Suspended requests
     * are still considered pending.
     */
    boolean isPending();

    /**
     * Returns any error status associated with the request.
     */
    readonly attribute nsresult status;

    /**
     * Cancels the current request.  This will close any open input or
     * output streams and terminate any async requests.  Users should 
     * normally pass NS_BINDING_ABORTED, although other errors may also
     * be passed.  The error passed in will become the value of the 
     * status attribute.
     */
    void cancel(in nsresult status);

    /**
     * Suspends the current requests.  This may have the effect of closing
     * any underlying transport (in order to free up resources), although
     * any open streams remain logically opened and will continue delivering
     * data when the transport is resumed. 
     */
    void suspend();

    /**
     * Resumes the current request.  This may have the effect of re-opening
     * any underlying transport and will resume the delivery of data to 
     * any open streams. 
     */
    void resume();

    /**
     * Accesses the load group in which this request is currently a member.
     */
    attribute nsILoadGroup loadGroup;

    /**
     * Accesses the load flags for this request.
     */
    attribute nsLoadFlags loadFlags;

    /**************************************************************************
     * Below are the various load flags which may be or'd together.
     */

    /**
     * No special load flags:
     */
    const unsigned long LOAD_NORMAL = 0;

    /** 
     * Don't deliver status notifications to the nsIProgressEventSink, or keep 
     * this load from completing the nsILoadGroup it may belong to:
     */
    const unsigned long LOAD_BACKGROUND = 1 << 0; 

    /**************************************************************************
     * For requests that are channels, the following flags may apply.
     */

    /**
     * Used exclusively by the uriloader and docshell to indicate whether or
     * not this request corresponds to the toplevel document.
     */
    const unsigned long LOAD_DOCUMENT_URI = 1 << 1;

    /** 
     * If the end consumer for this load has been retargeted after discovering 
     * it's content, this flag will be set:
     */
    const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 2;

	/**
	 * This flag is used to tell the webshell not to cancel the load in cases
	 * when the request is receiving multipart/replace document
	 */
	const unsigned long LOAD_REPLACE = 1 << 3;

    /**************************************************************************
     * The following flags control caching behavior.  With the exception of
     * INHIBIT_PERSISTENT_CACHING, they are all mutually exclusive.
     */

    /*
     * Don't store data in the disk cache.  This can be used to preserve
     * privacy, e.g. so that no https transactions are recorded, or to avoid
     * caching a stream to disk that is already stored in a local file,
     * e.g. the mailbox: protocol.
     */
    const unsigned long INHIBIT_PERSISTENT_CACHING = 1 << 8;

    /**
     * Force an end-to-end download of content data from the origin server (and
     * any intervening proxies that sit between it and the client), e.g. this
     * flag is used for a shift-reload.
     */
    const unsigned long FORCE_RELOAD = 1 << 9;

    /**
     * Force revalidation with server (or proxy) to verify that cached content
     * is up-to-date, e.g. by comparing last-modified date on server with that
     * of the cached version.  This flag is used when the reload button is
     * pressed.
     */
    const unsigned long FORCE_VALIDATION = 1 << 10;

    /**
     * When cache data is potentially out of date, it can be revalidated with
     * the origin server to see if the content needs to be reloaded.  The
     * following three flags control how often this validation occurs.
     * These flags are commonly used for "normal" loading.
     */
    const unsigned long VALIDATE_NEVER             = 1 << 11;
    const unsigned long VALIDATE_ALWAYS            = 1 << 12;
    const unsigned long VALIDATE_ONCE_PER_SESSION  = 1 << 13;
};