netwerk/base/src/nsBaseChannel.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is Google Inc.
  18  * Portions created by the Initial Developer are Copyright (C) 2005
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *  Darin Fisher <darin@meer.net>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsBaseChannel_h__
  39 #define nsBaseChannel_h__
  40
  41 #include "nsString.h"
  42 #include "nsAutoPtr.h"
  43 #include "nsCOMPtr.h"
  44 #include "nsHashPropertyBag.h"
  45 #include "nsInputStreamPump.h"
  46
  47 #include "nsIChannel.h"
  48 #include "nsIInputStream.h"
  49 #include "nsIURI.h"
  50 #include "nsILoadGroup.h"
  51 #include "nsIStreamListener.h"
  52 #include "nsIInterfaceRequestor.h"
  53 #include "nsIProgressEventSink.h"
  54 #include "nsITransport.h"
  55
  56 //-----------------------------------------------------------------------------
  57 // nsBaseChannel is designed to be subclassed.  The subclass is responsible for
  58 // implementing the OpenContentStream method, which will be called by the
  59 // nsIChannel::AsyncOpen and nsIChannel::Open implementations.
  60 //
  61 // nsBaseChannel implements nsIInterfaceRequestor to provide a convenient way
  62 // for subclasses to query both the nsIChannel::notificationCallbacks and
  63 // nsILoadGroup::notificationCallbacks for supported interfaces.
  64 //
  65 // nsBaseChannel implements nsITransportEventSink to support progress & status
  66 // notifications generated by the transport layer.
  67
  68 class nsBaseChannel : public nsHashPropertyBag
  69                     , public nsIChannel
  70                     , public nsIInterfaceRequestor
  71                     , public nsITransportEventSink
  72                     , private nsIStreamListener
  73 {
  74 public:
  75   NS_DECL_ISUPPORTS_INHERITED
  76   NS_DECL_NSIREQUEST
  77   NS_DECL_NSICHANNEL
  78   NS_DECL_NSIINTERFACEREQUESTOR
  79   NS_DECL_NSITRANSPORTEVENTSINK
  80
  81   nsBaseChannel();
  82
  83   // This method must be called to initialize the basechannel instance.
  84   nsresult Init() {
  85     return nsHashPropertyBag::Init();
  86   }
  87
  88 protected:
  89   // -----------------------------------------------
  90   // Methods to be implemented by the derived class:
  91
  92   virtual ~nsBaseChannel() {}
  93
  94 private:
  95   // Implemented by subclass to supply data stream.  The parameter, async, is
  96   // true when called from nsIChannel::AsyncOpen and false otherwise.  When
  97   // async is true, the resulting stream will be used with a nsIInputStreamPump
  98   // instance.  This means that if it is a non-blocking stream that supports
  99   // nsIAsyncInputStream that it will be read entirely on the main application
 100   // thread, and its AsyncWait method will be called whenever ReadSegments
 101   // returns NS_BASE_STREAM_WOULD_BLOCK.  Otherwise, if the stream is blocking,
 102   // then it will be read on one of the background I/O threads, and it does not
 103   // need to implement ReadSegments.  If async is false, this method may return
 104   // NS_ERROR_NOT_IMPLEMENTED to cause the basechannel to implement Open in
 105   // terms of AsyncOpen (see NS_ImplementChannelOpen).
 106   virtual nsresult OpenContentStream(PRBool async, nsIInputStream **stream) = 0;
 107
 108   // The basechannel calls this method from its OnTransportStatus method to
 109   // determine whether to call nsIProgressEventSink::OnStatus in addition to
 110   // nsIProgressEventSink::OnProgress.  This method may be overriden by the
 111   // subclass to enable nsIProgressEventSink::OnStatus events.  If this method
 112   // returns true, then the statusArg out param specifies the "statusArg" value
 113   // to pass to the OnStatus method.  By default, OnStatus messages are
 114   // suppressed.  The status parameter passed to this method is the status value
 115   // from the OnTransportStatus method.
 116   virtual PRBool GetStatusArg(nsresult status, nsString &statusArg) {
 117     return PR_FALSE;
 118   }
 119
 120   // Called when the callbacks available to this channel may have changed.
 121   virtual void OnCallbacksChanged() {
 122   }
 123
 124 public:
 125   // ----------------------------------------------
 126   // Methods provided for use by the derived class:
 127
 128   // Redirect to another channel.  This method takes care of notifying
 129   // observers of this redirect as well as of opening the new channel.  It also
 130   // cancels |this| with the status code NS_BINDING_REDIRECTED.  A failure
 131   // return from this method means that the redirect could not be performed (no
 132   // channel was opened; this channel wasn't canceled.)  The redirectFlags
 133   // parameter consists of the flag values defined on nsIChannelEventSink.
 134   nsresult Redirect(nsIChannel *newChannel, PRUint32 redirectFlags);
 135
 136   // Tests whether a type hint was set. Subclasses can use this to decide
 137   // whether to call SetContentType.
 138   // NOTE: This is only reliable if the subclass didn't itself call
 139   // SetContentType, and should also not be called after OpenContentStream.
 140   PRBool HasContentTypeHint() const;
 141
 142   // The URI member should be initialized before the channel is used, and then
 143   // it should never be changed again until the channel is destroyed.
 144   nsIURI *URI() {
 145     return mURI;
 146   }
 147   void SetURI(nsIURI *uri) {
 148     NS_ASSERTION(uri, "must specify a non-null URI");
 149     NS_ASSERTION(!mURI, "must not modify URI");
 150     mURI = uri;
 151   }
 152   nsIURI *OriginalURI() {
 153     return mOriginalURI ? mOriginalURI : mURI;
 154   }
 155
 156   // The security info is a property of the transport-layer, which should be
 157   // assigned by the subclass.
 158   nsISupports *SecurityInfo() {
 159     return mSecurityInfo;
 160   }
 161   void SetSecurityInfo(nsISupports *info) {
 162     mSecurityInfo = info;
 163   }
 164
 165   // Test the load flags
 166   PRBool HasLoadFlag(PRUint32 flag) {
 167     return (mLoadFlags & flag) != 0;
 168   }
 169
 170   // This is a short-cut to calling nsIRequest::IsPending()
 171   PRBool IsPending() const {
 172     return (mPump != nsnull);
 173   }
 174
 175   // Set the content length that should be reported for this channel.  Pass -1
 176   // to indicate an unspecified content length.
 177   void SetContentLength64(PRInt64 len);
 178   PRInt64 ContentLength64();
 179
 180   // Helper function for querying the channel's notification callbacks.
 181   template <class T> void GetCallback(nsCOMPtr<T> &result) {
 182     GetInterface(NS_GET_TEMPLATE_IID(T), getter_AddRefs(result));
 183   }
 184
 185   // Helper function for calling QueryInterface on this.
 186   nsQueryInterface do_QueryInterface() {
 187     return nsQueryInterface(static_cast<nsIChannel *>(this));
 188   }
 189   // MSVC needs this:
 190   nsQueryInterface do_QueryInterface(nsISupports *obj) {
 191     return nsQueryInterface(obj);
 192   }
 193
 194   // If a subclass does not want to feed transport-layer progress events to the
 195   // base channel via nsITransportEventSink, then it may set this flag to cause
 196   // the base channel to synthesize progress events when it receives data from
 197   // the content stream.  By default, progress events are not synthesized.
 198   void EnableSynthesizedProgressEvents(PRBool enable) {
 199     mSynthProgressEvents = enable;
 200   }
 201
 202   // Some subclasses may wish to manually insert a stream listener between this
 203   // and the channel's listener.  The following methods make that possible.
 204   void SetStreamListener(nsIStreamListener *listener) {
 205     mListener = listener;
 206   }
 207   nsIStreamListener *StreamListener() {
 208     return mListener;
 209   }
 210
 211   // Pushes a new stream converter in front of the channel's stream listener.
 212   // The fromType and toType values are passed to nsIStreamConverterService's
 213   // AsyncConvertData method.  If invalidatesContentLength is true, then the
 214   // channel's content-length property will be assigned a value of -1.  This is
 215   // necessary when the converter changes the length of the resulting data
 216   // stream, which is almost always the case for a "stream converter" ;-)
 217   // This function optionally returns a reference to the new converter.
 218   nsresult PushStreamConverter(const char *fromType, const char *toType,
 219                                PRBool invalidatesContentLength = PR_TRUE,
 220                                nsIStreamListener **converter = nsnull);
 221
 222 private:
 223   NS_DECL_NSISTREAMLISTENER
 224   NS_DECL_NSIREQUESTOBSERVER
 225
 226   // Called to setup mPump and call AsyncRead on it.
 227   nsresult BeginPumpingData();
 228
 229   // Called when the callbacks available to this channel may have changed.
 230   void CallbacksChanged() {
 231     mProgressSink = nsnull;
 232     mQueriedProgressSink = PR_FALSE;
 233     OnCallbacksChanged();
 234   }
 235
 236   nsRefPtr<nsInputStreamPump>         mPump;
 237   nsCOMPtr<nsIInterfaceRequestor>     mCallbacks;
 238   nsCOMPtr<nsIProgressEventSink>      mProgressSink;
 239   nsCOMPtr<nsIURI>                    mOriginalURI;
 240   nsCOMPtr<nsIURI>                    mURI;
 241   nsCOMPtr<nsILoadGroup>              mLoadGroup;
 242   nsCOMPtr<nsISupports>               mOwner;
 243   nsCOMPtr<nsISupports>               mSecurityInfo;
 244   nsCOMPtr<nsIStreamListener>         mListener;
 245   nsCOMPtr<nsISupports>               mListenerContext;
 246   nsCString                           mContentType;
 247   nsCString                           mContentCharset;
 248   PRUint32                            mLoadFlags;
 249   nsresult                            mStatus;
 250   PRPackedBool                        mQueriedProgressSink;
 251   PRPackedBool                        mSynthProgressEvents;
 252   PRPackedBool                        mWasOpened;
 253 };
 254
 255 #endif // !nsBaseChannel_h__