Struct xpcom::interfaces::nsIChannel [−] [src]

#[repr(C)]

pub struct nsIChannel { /* fields omitted */ }

interface nsIChannel : nsIRequest

Methods

impl nsIChannel
[src]

[src]

Cast this nsIChannel to one of its base interfaces.

impl nsIChannel
[src]

LOAD_DOCUMENT_URI: i64 = 65536
/**************************************************************************
     * Channel specific load flags:
     *
     * Bits 26-31 are reserved for future use by this interface or one of its
     * derivatives (e.g., see nsICachingChannel).
     */
/**
     * Set (e.g., by the docshell) to indicate whether or not the channel
     * corresponds to a document URI.
     * While setting this flag is sufficient to mark a channel as a document
     * load, _checking_ whether the channel is a document load requires the use
     * of the new channel.isDocument
     */


LOAD_RETARGETED_DOCUMENT_URI: i64 = 131072
/**
     * If the end consumer for this load has been retargeted after discovering
     * its content, this flag will be set:
     */


LOAD_REPLACE: i64 = 262144
/**
     * This flag is set to indicate that this channel is replacing another
     * channel.  This means that:
     *
     * 1) the stream listener this channel will be notifying was initially
     *    passed to the asyncOpen method of some other channel
     *
     *   and
     *
     * 2) this channel's URI is a better identifier of the resource being
     *    accessed than this channel's originalURI.
     *
     * This flag can be set, for example, for redirects or for cases when a
     * single channel has multiple parts to it (and thus can follow
     * onStopRequest with another onStartRequest/onStopRequest pair, each pair
     * for a different request).
     */


LOAD_INITIAL_DOCUMENT_URI: i64 = 524288
/**
     * Set (e.g., by the docshell) to indicate whether or not the channel
     * corresponds to an initial document URI load (e.g., link click).
     */


LOAD_TARGETED: i64 = 1048576
/**
     * Set (e.g., by the URILoader) to indicate whether or not the end consumer
     * for this load has been determined.
     */


LOAD_CALL_CONTENT_SNIFFERS: i64 = 2097152
/**
     * If this flag is set, the channel should call the content sniffers as
     * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
     *
     * Note: Channels may ignore this flag; however, new channel implementations
     * should only do so with good reason.
     */


LOAD_CLASSIFY_URI: i64 = 4194304
/**
     * This flag tells the channel to use URI classifier service to check
     * the URI when opening the channel.
     */


LOAD_MEDIA_SNIFFER_OVERRIDES_CONTENT_TYPE: i64 = 8388608
/**
     * If this flag is set, the media-type content sniffer will be allowed
     * to override any server-set content-type. Otherwise it will only
     * be allowed to override "no content type" and application/octet-stream.
     */


LOAD_EXPLICIT_CREDENTIALS: i64 = 16777216
/**
     * Set to let explicitely provided credentials be used over credentials
     * we have cached previously. In some situations like form login using HTTP
     * auth via XMLHttpRequest we need to let consumers override the cached
     * credentials explicitely. For form login 403 response instead of 401 is
     * usually used to prevent an auth dialog. But any code other then 401/7
     * will leave original credentials in the cache and there is then no way
     * to override them for the same user name.
     */


LOAD_BYPASS_SERVICE_WORKER: i64 = 33554432
/**
     * Set to force bypass of any service worker interception of the channel.
     */


DISPOSITION_INLINE: i64 = 0

DISPOSITION_ATTACHMENT: i64 = 1

[src]

/**
 * The nsIChannel interface allows clients to construct "GET" requests for
 * specific protocols, and manage them in a uniform way.  Once a channel is
 * created (via nsIIOService::newChannel), parameters for that request may
 * be set by using the channel attributes, or by QI'ing to a subclass of
 * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
 * by calling nsIChannel::open or nsIChannel::asyncOpen.
 *
 * After a request has been completed, the channel is still valid for accessing
 * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
 * response headers to be retrieved for the corresponding http transaction.
 *
 * This interface must be used only from the XPCOM main thread.
 */
/**
     * The original URI used to construct the channel. This is used in
     * the case of a redirect or URI "resolution" (e.g. resolving a
     * resource: URI to a file: URI) so that the original pre-redirect
     * URI can still be obtained.  This is never null.  Attempts to
     * set it to null must throw.
     *
     * NOTE: this is distinctly different from the http Referer (referring URI),
     * which is typically the page that contained the original URI (accessible
     * from nsIHttpChannel).
     */

attribute nsIURI originalURI;

[src]

/**
 * The nsIChannel interface allows clients to construct "GET" requests for
 * specific protocols, and manage them in a uniform way.  Once a channel is
 * created (via nsIIOService::newChannel), parameters for that request may
 * be set by using the channel attributes, or by QI'ing to a subclass of
 * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
 * by calling nsIChannel::open or nsIChannel::asyncOpen.
 *
 * After a request has been completed, the channel is still valid for accessing
 * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
 * response headers to be retrieved for the corresponding http transaction.
 *
 * This interface must be used only from the XPCOM main thread.
 */
/**
     * The original URI used to construct the channel. This is used in
     * the case of a redirect or URI "resolution" (e.g. resolving a
     * resource: URI to a file: URI) so that the original pre-redirect
     * URI can still be obtained.  This is never null.  Attempts to
     * set it to null must throw.
     *
     * NOTE: this is distinctly different from the http Referer (referring URI),
     * which is typically the page that contained the original URI (accessible
     * from nsIHttpChannel).
     */

attribute nsIURI originalURI;

[src]

/**
     * The URI corresponding to the channel.  Its value is immutable.
     */

readonly attribute nsIURI URI;

[src]

/**
     * The owner, corresponding to the entity that is responsible for this
     * channel.  Used by the security manager to grant or deny privileges to
     * mobile code loaded from this channel.
     *
     * NOTE: this is a strong reference to the owner, so if the owner is also
     * holding a strong reference to the channel, care must be taken to
     * explicitly drop its reference to the channel.
     */

attribute nsISupports owner;

[src]

/**
     * The owner, corresponding to the entity that is responsible for this
     * channel.  Used by the security manager to grant or deny privileges to
     * mobile code loaded from this channel.
     *
     * NOTE: this is a strong reference to the owner, so if the owner is also
     * holding a strong reference to the channel, care must be taken to
     * explicitly drop its reference to the channel.
     */

attribute nsISupports owner;

[src]

/**
     * The notification callbacks for the channel.  This is set by clients, who
     * wish to provide a means to receive progress, status and protocol-specific
     * notifications.  If this value is NULL, the channel implementation may use
     * the notification callbacks from its load group.  The channel may also
     * query the notification callbacks from its load group if its notification
     * callbacks do not supply the requested interface.
     *
     * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
     * and nsIAuthPrompt/nsIAuthPrompt2.
     *
     * When the channel is done, it must not continue holding references to
     * this object.
     *
     * NOTE: A channel implementation should take care when "caching" an
     * interface pointer queried from its notification callbacks.  If the
     * notification callbacks are changed, then a cached interface pointer may
     * become invalid and may therefore need to be re-queried.
     */

attribute nsIInterfaceRequestor notificationCallbacks;

[src]

/**
     * The notification callbacks for the channel.  This is set by clients, who
     * wish to provide a means to receive progress, status and protocol-specific
     * notifications.  If this value is NULL, the channel implementation may use
     * the notification callbacks from its load group.  The channel may also
     * query the notification callbacks from its load group if its notification
     * callbacks do not supply the requested interface.
     *
     * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
     * and nsIAuthPrompt/nsIAuthPrompt2.
     *
     * When the channel is done, it must not continue holding references to
     * this object.
     *
     * NOTE: A channel implementation should take care when "caching" an
     * interface pointer queried from its notification callbacks.  If the
     * notification callbacks are changed, then a cached interface pointer may
     * become invalid and may therefore need to be re-queried.
     */

attribute nsIInterfaceRequestor notificationCallbacks;

[src]

/**
     * Transport-level security information (if any) corresponding to the
     * channel.
     *
     * NOTE: In some circumstances TLS information is propagated onto
     * non-nsIHttpChannel objects to indicate that their contents were likely
     * delivered over TLS all the same.  For example, document.open() may
     * create an nsWyciwygChannel to store the data that will be written to the
     * document.  In that case, if the caller has TLS information, we propagate
     * that info onto the nsWyciwygChannel given that it is likely that the
     * caller will be writing data that was delivered over TLS to the document.
     */

readonly attribute nsISupports securityInfo;

[src]

/**
     * The MIME type of the channel's content if available.
     *
     * NOTE: the content type can often be wrongly specified (e.g., wrong file
     * extension, wrong MIME type, wrong document type stored on a server, etc.),
     * and the caller most likely wants to verify with the actual data.
     *
     * Setting contentType before the channel has been opened provides a hint
     * to the channel as to what the MIME type is.  The channel may ignore this
     * hint in deciding on the actual MIME type that it will report.
     *
     * Setting contentType after onStartRequest has been fired or after open()
     * is called will override the type determined by the channel.
     *
     * Setting contentType between the time that asyncOpen() is called and the
     * time when onStartRequest is fired has undefined behavior at this time.
     *
     * The value of the contentType attribute is a lowercase string.  A value
     * assigned to this attribute will be parsed and normalized as follows:
     *  1- any parameters (delimited with a ';') will be stripped.
     *  2- if a charset parameter is given, then its value will replace the
     *     the contentCharset attribute of the channel.
     *  3- the stripped contentType will be lowercased.
     * Any implementation of nsIChannel must follow these rules.
     */

attribute ACString contentType;

[src]

/**
     * The MIME type of the channel's content if available.
     *
     * NOTE: the content type can often be wrongly specified (e.g., wrong file
     * extension, wrong MIME type, wrong document type stored on a server, etc.),
     * and the caller most likely wants to verify with the actual data.
     *
     * Setting contentType before the channel has been opened provides a hint
     * to the channel as to what the MIME type is.  The channel may ignore this
     * hint in deciding on the actual MIME type that it will report.
     *
     * Setting contentType after onStartRequest has been fired or after open()
     * is called will override the type determined by the channel.
     *
     * Setting contentType between the time that asyncOpen() is called and the
     * time when onStartRequest is fired has undefined behavior at this time.
     *
     * The value of the contentType attribute is a lowercase string.  A value
     * assigned to this attribute will be parsed and normalized as follows:
     *  1- any parameters (delimited with a ';') will be stripped.
     *  2- if a charset parameter is given, then its value will replace the
     *     the contentCharset attribute of the channel.
     *  3- the stripped contentType will be lowercased.
     * Any implementation of nsIChannel must follow these rules.
     */

attribute ACString contentType;

[src]

/**
     * The character set of the channel's content if available and if applicable.
     * This attribute only applies to textual data.
     *
     * The value of the contentCharset attribute is a mixedcase string.
     */

attribute ACString contentCharset;

[src]

/**
     * The character set of the channel's content if available and if applicable.
     * This attribute only applies to textual data.
     *
     * The value of the contentCharset attribute is a mixedcase string.
     */

attribute ACString contentCharset;

[src]

/**
     * The length of the data associated with the channel if available.  A value
     * of -1 indicates that the content length is unknown. Note that this is a
     * 64-bit value and obsoletes the "content-length" property used on some
     * channels.
     */

attribute int64_t contentLength;

[src]

/**
     * The length of the data associated with the channel if available.  A value
     * of -1 indicates that the content length is unknown. Note that this is a
     * 64-bit value and obsoletes the "content-length" property used on some
     * channels.
     */

attribute int64_t contentLength;

[src]

/**
     * Synchronously open the channel.
     *
     * @return blocking input stream to the channel's data.
     *
     * NOTE: nsIChannel implementations are not required to implement this
     * method.  Moreover, since this method may block the calling thread, it
     * should not be called on a thread that processes UI events.  Like any
     * other nsIChannel method it must not be called on any thread other
     * than the XPCOM main thread.
     *
     * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
     * is reopened.
     */

nsIInputStream open ();

[src]

/**
     * Performs content security check and calls open()
     */

nsIInputStream open2 ();

[src]

/**
     * Asynchronously open this channel.  Data is fed to the specified stream
     * listener as it becomes available.  The stream listener's methods are
     * called on the thread that calls asyncOpen and are not called until
     * after asyncOpen returns.  If asyncOpen returns successfully, the
     * channel promises to call at least onStartRequest and onStopRequest.
     *
     * If the nsIRequest object passed to the stream listener's methods is not
     * this channel, an appropriate onChannelRedirect notification needs to be
     * sent to the notification callbacks before onStartRequest is called.
     * Once onStartRequest is called, all following method calls on aListener
     * will get the request that was passed to onStartRequest.
     *
     * If the channel's and loadgroup's notification callbacks do not provide
     * an nsIChannelEventSink when onChannelRedirect would be called, that's
     * equivalent to having called onChannelRedirect.
     *
     * If asyncOpen returns successfully, the channel is responsible for
     * keeping itself alive until it has called onStopRequest on aListener or
     * called onChannelRedirect.
     *
     * Implementations are allowed to synchronously add themselves to the
     * associated load group (if any).
     *
     * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
     * channel is reopened.
     *
     * @param aListener the nsIStreamListener implementation
     * @param aContext an opaque parameter forwarded to aListener's methods
     * @see nsIChannelEventSink for onChannelRedirect
     */

void asyncOpen (in nsIStreamListener aListener, in nsISupports aContext);

[src]

/**
     * Performs content security check and calls asyncOpen().
     */

void asyncOpen2 (in nsIStreamListener aListener);

[src]

/**
     * Access to the type implied or stated by the Content-Disposition header
     * if available and if applicable. This allows determining inline versus
     * attachment.
     *
     * Setting contentDisposition provides a hint to the channel about the
     * disposition.  If a normal Content-Disposition header is present its
     * value will always be used.  If it is missing the hinted value will
     * be used if set.
     *
     * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
     * doesn't exist for this type of channel or is empty, and return
     * DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present.
     */

attribute unsigned long contentDisposition;

[src]

/**
     * Access to the type implied or stated by the Content-Disposition header
     * if available and if applicable. This allows determining inline versus
     * attachment.
     *
     * Setting contentDisposition provides a hint to the channel about the
     * disposition.  If a normal Content-Disposition header is present its
     * value will always be used.  If it is missing the hinted value will
     * be used if set.
     *
     * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
     * doesn't exist for this type of channel or is empty, and return
     * DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present.
     */

attribute unsigned long contentDisposition;

[src]

/**
     * Access to the filename portion of the Content-Disposition header if
     * available and if applicable. This allows getting the preferred filename
     * without having to parse it out yourself.
     *
     * Setting contentDispositionFilename provides a hint to the channel about
     * the disposition.  If a normal Content-Disposition header is present its
     * value will always be used.  If it is missing the hinted value will be
     * used if set.
     *
     * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't
     * exist for this type of channel, if the header is empty, if the header
     * doesn't contain a filename portion, or the value of the filename
     * attribute is empty/missing.
     */

attribute AString contentDispositionFilename;

[src]

/**
     * Access to the filename portion of the Content-Disposition header if
     * available and if applicable. This allows getting the preferred filename
     * without having to parse it out yourself.
     *
     * Setting contentDispositionFilename provides a hint to the channel about
     * the disposition.  If a normal Content-Disposition header is present its
     * value will always be used.  If it is missing the hinted value will be
     * used if set.
     *
     * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't
     * exist for this type of channel, if the header is empty, if the header
     * doesn't contain a filename portion, or the value of the filename
     * attribute is empty/missing.
     */

attribute AString contentDispositionFilename;

[src]

/**
     * Access to the raw Content-Disposition header if available and applicable.
     *
     * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
     * doesn't exist for this type of channel or is empty.
     *
     * @deprecated Use contentDisposition/contentDispositionFilename instead.
     */

readonly attribute ACString contentDispositionHeader;

[src]

/**
     * The LoadInfo object contains information about a network load, why it
     * was started, and how we plan on using the resulting response.
     * If a network request is redirected, the new channel will receive a new
     * LoadInfo object. The new object will contain mostly the same
     * information as the pre-redirect one, but updated as appropriate.
     * For detailed information about what parts of LoadInfo are updated on
     * redirect, see documentation on individual properties.
     */

attribute nsILoadInfo loadInfo;

[src]

/**
     * The LoadInfo object contains information about a network load, why it
     * was started, and how we plan on using the resulting response.
     * If a network request is redirected, the new channel will receive a new
     * LoadInfo object. The new object will contain mostly the same
     * information as the pre-redirect one, but updated as appropriate.
     * For detailed information about what parts of LoadInfo are updated on
     * redirect, see documentation on individual properties.
     */

attribute nsILoadInfo loadInfo;

[src]

/**
     * Returns true if the channel is used to create a document.
     * It returns true if the loadFlags have LOAD_DOCUMENT_URI set, or if
     * LOAD_HTML_OBJECT_DATA is set and the channel has the appropriate
     * MIME type.
     * Note: May have the wrong value if called before OnStartRequest as we
     * don't know the MIME type yet.
     */

readonly attribute bool isDocument;

Methods from Deref<Target = nsIRequest>

[src]

Cast this nsIRequest to one of its base interfaces.

[src]

/**
     * The name of the request.  Often this is the URI of the request.
     */

readonly attribute AUTF8String name;

[src]

/**
     * Indicates whether the request is pending. nsIRequest::isPending is
     * true when there is an outstanding asynchronous event that will make
     * the request no longer be pending.  Requests do not necessarily start
     * out pending; in some cases, requests have to be explicitly initiated
     * (e.g. nsIChannel implementations are only pending once asyncOpen
     * returns successfully).
     *
     * Requests can become pending multiple times during their lifetime.
     *
     * @return TRUE if the request has yet to reach completion.
     * @return FALSE if the request has reached completion (e.g., after
     *   OnStopRequest has fired).
     * @note Suspended requests are still considered pending.
     */

boolean isPending ();

[src]

/**
     * The error status associated with the request.
     */

readonly attribute nsresult status;

[src]

/**
     * 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.
     *
     * Implementations must not send any notifications (e.g. via
     * nsIRequestObserver) synchronously from this function. Similarly,
     * removal from the load group (if any) must also happen asynchronously.
     *
     * Requests that use nsIStreamListener must not call onDataAvailable
     * anymore after cancel has been called.
     *
     * @param aStatus the reason for canceling this request.
     *
     * NOTE: most nsIRequest implementations expect aStatus to be a
     * failure code; however, some implementations may allow aStatus to
     * be a success code such as NS_OK.  In general, aStatus should be
     * a failure code.
     */

void cancel (in nsresult aStatus);

[src]

/**
     * Suspends the current request.  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.
     *
     * Calling cancel() on a suspended request must not send any
     * notifications (such as onstopRequest) until the request is resumed.
     *
     * NOTE: some implementations are unable to immediately suspend, and
     * may continue to deliver events already posted to an event queue. In
     * general, callers should be capable of handling events even after
     * suspending a request.
     */

void suspend ();

[src]

/**
     * 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 ();

[src]

/**
     * The load group of this request.  While pending, the request is a
     * member of the load group.  It is the responsibility of the request
     * to implement this policy.
     */

attribute nsILoadGroup loadGroup;

[src]

/**
     * The load group of this request.  While pending, the request is a
     * member of the load group.  It is the responsibility of the request
     * to implement this policy.
     */

attribute nsILoadGroup loadGroup;

[src]

/**
     * The load flags of this request.  Bits 0-15 are reserved.
     *
     * When added to a load group, this request's load flags are merged with
     * the load flags of the load group.
     */

attribute nsLoadFlags loadFlags;

[src]

/**
     * The load flags of this request.  Bits 0-15 are reserved.
     *
     * When added to a load group, this request's load flags are merged with
     * the load flags of the load group.
     */

attribute nsLoadFlags loadFlags;

Trait Implementations

impl XpCom for nsIChannel
[src]

IID: nsIID = nsID(741906533, 9179, 19111, [159, 229, 96, 204, 123, 0, 105, 126])

[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 nsIChannel
[src]

[src]

Increment the reference count.

[src]

Decrement the reference count, potentially freeing backing memory.

impl Deref for nsIChannel
[src]

The resulting type after dereferencing.

[src]

Dereferences the value.