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 #include "nsThreadUtils.h"
  56
  57 //-----------------------------------------------------------------------------
  58 // nsBaseChannel is designed to be subclassed.  The subclass is responsible for
  59 // implementing the OpenContentStream method, which will be called by the
  60 // nsIChannel::AsyncOpen and nsIChannel::Open implementations.
  61 //
  62 // nsBaseChannel implements nsIInterfaceRequestor to provide a convenient way
  63 // for subclasses to query both the nsIChannel::notificationCallbacks and
  64 // nsILoadGroup::notificationCallbacks for supported interfaces.
  65 //
  66 // nsBaseChannel implements nsITransportEventSink to support progress & status
  67 // notifications generated by the transport layer.
  68
  69 class nsBaseChannel : public nsHashPropertyBag
  70                     , public nsIChannel
  71                     , public nsIInterfaceRequestor
  72                     , public nsITransportEventSink
  73                     , private nsIStreamListener
  74 {
  75 public:
  76   NS_DECL_ISUPPORTS_INHERITED
  77   NS_DECL_NSIREQUEST
  78   NS_DECL_NSICHANNEL
  79   NS_DECL_NSIINTERFACEREQUESTOR
  80   NS_DECL_NSITRANSPORTEVENTSINK
  81
  82   nsBaseChannel();
  83
  84   // This method must be called to initialize the basechannel instance.
  85   nsresult Init() {
  86     return nsHashPropertyBag::Init();
  87   }
  88
  89 protected:
  90   // -----------------------------------------------
  91   // Methods to be implemented by the derived class:
  92
  93   virtual ~nsBaseChannel() {}
  94
  95 private:
  96   // Implemented by subclass to supply data stream.  The parameter, async, is
  97   // true when called from nsIChannel::AsyncOpen and false otherwise.  When
  98   // async is true, the resulting stream will be used with a nsIInputStreamPump
  99   // instance.  This means that if it is a non-blocking stream that supports
 100   // nsIAsyncInputStream that it will be read entirely on the main application
 101   // thread, and its AsyncWait method will be called whenever ReadSegments
 102   // returns NS_BASE_STREAM_WOULD_BLOCK.  Otherwise, if the stream is blocking,
 103   // then it will be read on one of the background I/O threads, and it does not
 104   // need to implement ReadSegments.  If async is false, this method may return
 105   // NS_ERROR_NOT_IMPLEMENTED to cause the basechannel to implement Open in
 106   // terms of AsyncOpen (see NS_ImplementChannelOpen).
 107   // A callee is allowed to return an nsIChannel instead of an nsIInputStream.
 108   // That case will be treated as a redirect to the new channel.  By default
 109   // *channel will be set to null by the caller, so callees who don't want to
 110   // return one an just not touch it.
 111   virtual nsresult OpenContentStream(PRBool async, nsIInputStream **stream,
 112                                      nsIChannel** channel) = 0;
 113
 114   // The basechannel calls this method from its OnTransportStatus method to
 115   // determine whether to call nsIProgressEventSink::OnStatus in addition to
 116   // nsIProgressEventSink::OnProgress.  This method may be overriden by the
 117   // subclass to enable nsIProgressEventSink::OnStatus events.  If this method
 118   // returns true, then the statusArg out param specifies the "statusArg" value
 119   // to pass to the OnStatus method.  By default, OnStatus messages are
 120   // suppressed.  The status parameter passed to this method is the status value
 121   // from the OnTransportStatus method.
 122   virtual PRBool GetStatusArg(nsresult status, nsString &statusArg) {
 123     return PR_FALSE;
 124   }
 125
 126   // Called when the callbacks available to this channel may have changed.
 127   virtual void OnCallbacksChanged() {
 128   }
 129
 130 public:
 131   // ----------------------------------------------
 132   // Methods provided for use by the derived class:
 133
 134   // Redirect to another channel.  This method takes care of notifying
 135   // observers of this redirect as well as of opening the new channel, if asked
 136   // to do so.  It also cancels |this| with the status code
 137   // NS_BINDING_REDIRECTED.  A failure return from this method means that the
 138   // redirect could not be performed (no channel was opened; this channel
 139   // wasn't canceled.)  The redirectFlags parameter consists of the flag values
 140   // defined on nsIChannelEventSink.
 141   nsresult Redirect(nsIChannel *newChannel, PRUint32 redirectFlags,
 142                     PRBool openNewChannel);
 143
 144   // Tests whether a type hint was set. Subclasses can use this to decide
 145   // whether to call SetContentType.
 146   // NOTE: This is only reliable if the subclass didn't itself call
 147   // SetContentType, and should also not be called after OpenContentStream.
 148   PRBool HasContentTypeHint() const;
 149
 150   // The URI member should be initialized before the channel is used, and then
 151   // it should never be changed again until the channel is destroyed.
 152   nsIURI *URI() {
 153     return mURI;
 154   }
 155   void SetURI(nsIURI *uri) {
 156     NS_ASSERTION(uri, "must specify a non-null URI");
 157     NS_ASSERTION(!mURI, "must not modify URI");
 158     NS_ASSERTION(!mOriginalURI, "how did that get set so early?");
 159     mURI = uri;
 160     mOriginalURI = uri;
 161   }
 162   nsIURI *OriginalURI() {
 163     return mOriginalURI;
 164   }
 165
 166   // The security info is a property of the transport-layer, which should be
 167   // assigned by the subclass.
 168   nsISupports *SecurityInfo() {
 169     return mSecurityInfo;
 170   }
 171   void SetSecurityInfo(nsISupports *info) {
 172     mSecurityInfo = info;
 173   }
 174
 175   // Test the load flags
 176   PRBool HasLoadFlag(PRUint32 flag) {
 177     return (mLoadFlags & flag) != 0;
 178   }
 179
 180   // This is a short-cut to calling nsIRequest::IsPending()
 181   PRBool IsPending() const {
 182     return mPump || mWaitingOnAsyncRedirect;
 183   }
 184
 185   // Set the content length that should be reported for this channel.  Pass -1
 186   // to indicate an unspecified content length.
 187   void SetContentLength64(PRInt64 len);
 188   PRInt64 ContentLength64();
 189
 190   // Helper function for querying the channel's notification callbacks.
 191   template <class T> void GetCallback(nsCOMPtr<T> &result) {
 192     GetInterface(NS_GET_TEMPLATE_IID(T), getter_AddRefs(result));
 193   }
 194
 195   // Helper function for calling QueryInterface on this.
 196   nsQueryInterface do_QueryInterface() {
 197     return nsQueryInterface(static_cast<nsIChannel *>(this));
 198   }
 199   // MSVC needs this:
 200   nsQueryInterface do_QueryInterface(nsISupports *obj) {
 201     return nsQueryInterface(obj);
 202   }
 203
 204   // If a subclass does not want to feed transport-layer progress events to the
 205   // base channel via nsITransportEventSink, then it may set this flag to cause
 206   // the base channel to synthesize progress events when it receives data from
 207   // the content stream.  By default, progress events are not synthesized.
 208   void EnableSynthesizedProgressEvents(PRBool enable) {
 209     mSynthProgressEvents = enable;
 210   }
 211
 212   // Some subclasses may wish to manually insert a stream listener between this
 213   // and the channel's listener.  The following methods make that possible.
 214   void SetStreamListener(nsIStreamListener *listener) {
 215     mListener = listener;
 216   }
 217   nsIStreamListener *StreamListener() {
 218     return mListener;
 219   }
 220
 221   // Pushes a new stream converter in front of the channel's stream listener.
 222   // The fromType and toType values are passed to nsIStreamConverterService's
 223   // AsyncConvertData method.  If invalidatesContentLength is true, then the
 224   // channel's content-length property will be assigned a value of -1.  This is
 225   // necessary when the converter changes the length of the resulting data
 226   // stream, which is almost always the case for a "stream converter" ;-)
 227   // This function optionally returns a reference to the new converter.
 228   nsresult PushStreamConverter(const char *fromType, const char *toType,
 229                                PRBool invalidatesContentLength = PR_TRUE,
 230                                nsIStreamListener **converter = nsnull);
 231
 232 private:
 233   NS_DECL_NSISTREAMLISTENER
 234   NS_DECL_NSIREQUESTOBSERVER
 235
 236   // Called to setup mPump and call AsyncRead on it.
 237   nsresult BeginPumpingData();
 238
 239   // Called when the callbacks available to this channel may have changed.
 240   void CallbacksChanged() {
 241     mProgressSink = nsnull;
 242     mQueriedProgressSink = PR_FALSE;
 243     OnCallbacksChanged();
 244   }
 245
 246   // Handle an async redirect callback.  This will only be called if we
 247   // returned success from AsyncOpen while posting a redirect runnable.
 248   void HandleAsyncRedirect(nsIChannel* newChannel);
 249
 250   class RedirectRunnable : public nsRunnable
 251   {
 252   public:
 253     RedirectRunnable(nsBaseChannel* chan, nsIChannel* newChannel)
 254       : mChannel(chan), mNewChannel(newChannel)
 255     {
 256       NS_PRECONDITION(newChannel, "Must have channel to redirect to");
 257     }
 258
 259     NS_IMETHOD Run()
 260     {
 261       mChannel->HandleAsyncRedirect(mNewChannel);
 262       return NS_OK;
 263     }
 264
 265   private:
 266     nsRefPtr<nsBaseChannel> mChannel;
 267     nsCOMPtr<nsIChannel> mNewChannel;
 268   };
 269   friend class RedirectRunnable;
 270
 271   nsRefPtr<nsInputStreamPump>         mPump;
 272   nsCOMPtr<nsIInterfaceRequestor>     mCallbacks;
 273   nsCOMPtr<nsIProgressEventSink>      mProgressSink;
 274   nsCOMPtr<nsIURI>                    mOriginalURI;
 275   nsCOMPtr<nsIURI>                    mURI;
 276   nsCOMPtr<nsILoadGroup>              mLoadGroup;
 277   nsCOMPtr<nsISupports>               mOwner;
 278   nsCOMPtr<nsISupports>               mSecurityInfo;
 279   nsCOMPtr<nsIStreamListener>         mListener;
 280   nsCOMPtr<nsISupports>               mListenerContext;
 281   nsCString                           mContentType;
 282   nsCString                           mContentCharset;
 283   PRUint32                            mLoadFlags;
 284   nsresult                            mStatus;
 285   PRPackedBool                        mQueriedProgressSink;
 286   PRPackedBool                        mSynthProgressEvents;
 287   PRPackedBool                        mWasOpened;
 288   PRPackedBool                        mWaitingOnAsyncRedirect;
 289 };
 290
 291 #endif // !nsBaseChannel_h__