net/url_request/url_request_context_builder.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This class is useful for building a simple URLRequestContext. Most creators
   6 // of new URLRequestContexts should use this helper class to construct it. Call
   7 // any configuration params, and when done, invoke Build() to construct the
   8 // URLRequestContext. This URLRequestContext will own all its own storage.
   9 //
  10 // URLRequestContextBuilder and its associated params classes are initially
  11 // populated with "sane" default values. Read through the comments to figure out
  12 // what these are.
  13
  14 #ifndef NET_URL_REQUEST_URL_REQUEST_CONTEXT_BUILDER_H_
  15 #define NET_URL_REQUEST_URL_REQUEST_CONTEXT_BUILDER_H_
  16
  17 #include <string>
  18 #include <vector>
  19
  20 #include "base/basictypes.h"
  21 #include "base/files/file_path.h"
  22 #include "base/memory/ref_counted.h"
  23 #include "base/memory/scoped_ptr.h"
  24 #include "base/memory/scoped_vector.h"
  25 #include "build/build_config.h"
  26 #include "net/base/net_export.h"
  27 #include "net/base/network_delegate.h"
  28 #include "net/dns/host_resolver.h"
  29 #include "net/http/http_network_session.h"
  30 #include "net/proxy/proxy_config_service.h"
  31 #include "net/proxy/proxy_service.h"
  32 #include "net/quic/quic_protocol.h"
  33 #include "net/socket/next_proto.h"
  34
  35 namespace base {
  36 class SingleThreadTaskRunner;
  37 }
  38
  39 namespace net {
  40
  41 class ChannelIDService;
  42 class CookieStore;
  43 class FtpTransactionFactory;
  44 class HostMappingRules;
  45 class HttpAuthHandlerFactory;
  46 class HttpServerProperties;
  47 class ProxyConfigService;
  48 class URLRequestContext;
  49 class URLRequestInterceptor;
  50
  51 class NET_EXPORT URLRequestContextBuilder {
  52  public:
  53   struct NET_EXPORT HttpCacheParams {
  54     enum Type {
  55       IN_MEMORY,
  56       DISK,
  57     };
  58
  59     HttpCacheParams();
  60     ~HttpCacheParams();
  61
  62     // The type of HTTP cache. Default is IN_MEMORY.
  63     Type type;
  64
  65     // The max size of the cache in bytes. Default is algorithmically determined
  66     // based off available disk space.
  67     int max_size;
  68
  69     // The cache path (when type is DISK).
  70     base::FilePath path;
  71   };
  72
  73   struct NET_EXPORT HttpNetworkSessionParams {
  74     HttpNetworkSessionParams();
  75     ~HttpNetworkSessionParams();
  76
  77     // These fields mirror those in HttpNetworkSession::Params;
  78     bool ignore_certificate_errors;
  79     HostMappingRules* host_mapping_rules;
  80     uint16 testing_fixed_http_port;
  81     uint16 testing_fixed_https_port;
  82     NextProtoVector next_protos;
  83     std::string trusted_spdy_proxy;
  84     bool use_alternative_services;
  85     bool enable_quic;
  86     bool enable_insecure_quic;
  87     QuicTagVector quic_connection_options;
  88   };
  89
  90   URLRequestContextBuilder();
  91   ~URLRequestContextBuilder();
  92
  93   // Extracts the component pointers required to construct an HttpNetworkSession
  94   // and copies them into the Params used to create the session. This function
  95   // should be used to ensure that a context and its associated
  96   // HttpNetworkSession are consistent.
  97   static void SetHttpNetworkSessionComponents(
  98       const URLRequestContext* context,
  99       HttpNetworkSession::Params* params);
 100
 101   // These functions are mutually exclusive.  The ProxyConfigService, if
 102   // set, will be used to construct a ProxyService.
 103   void set_proxy_config_service(
 104       scoped_ptr<ProxyConfigService> proxy_config_service) {
 105     proxy_config_service_ = proxy_config_service.Pass();
 106   }
 107   void set_proxy_service(scoped_ptr<ProxyService> proxy_service) {
 108     proxy_service_ = proxy_service.Pass();
 109   }
 110
 111   // Call these functions to specify hard-coded Accept-Language
 112   // or User-Agent header values for all requests that don't
 113   // have the headers already set.
 114   void set_accept_language(const std::string& accept_language) {
 115     accept_language_ = accept_language;
 116   }
 117   void set_user_agent(const std::string& user_agent) {
 118     user_agent_ = user_agent;
 119   }
 120
 121   // Control support for data:// requests. By default it's disabled.
 122   void set_data_enabled(bool enable) {
 123     data_enabled_ = enable;
 124   }
 125
 126 #if !defined(DISABLE_FILE_SUPPORT)
 127   // Control support for file:// requests. By default it's disabled.
 128   void set_file_enabled(bool enable) {
 129     file_enabled_ = enable;
 130   }
 131 #endif
 132
 133 #if !defined(DISABLE_FTP_SUPPORT)
 134   // Control support for ftp:// requests. By default it's disabled.
 135   void set_ftp_enabled(bool enable) {
 136     ftp_enabled_ = enable;
 137   }
 138 #endif
 139
 140   // Unlike the other setters, the builder does not take ownership of the
 141   // NetLog.
 142   // TODO(mmenke):  Probably makes sense to get rid of this, and have consumers
 143   // set their own NetLog::Observers instead.
 144   void set_net_log(NetLog* net_log) { net_log_ = net_log; }
 145
 146   // By default host_resolver is constructed with CreateDefaultResolver.
 147   void set_host_resolver(scoped_ptr<HostResolver> host_resolver) {
 148     host_resolver_ = host_resolver.Pass();
 149   }
 150
 151   // Uses BasicNetworkDelegate by default. Note that calling Build will unset
 152   // any custom delegate in builder, so this must be called each time before
 153   // Build is called.
 154   void set_network_delegate(scoped_ptr<NetworkDelegate> delegate) {
 155     network_delegate_ = delegate.Pass();
 156   }
 157
 158   // Adds additional auth handler factories to be used in addition to what is
 159   // provided in the default |HttpAuthHandlerRegistryFactory|. The auth |scheme|
 160   // and |factory| are provided. The builder takes ownership of the factory and
 161   // Build() must be called after this method.
 162   void add_http_auth_handler_factory(const std::string& scheme,
 163                                      HttpAuthHandlerFactory* factory) {
 164     extra_http_auth_handlers_.push_back(SchemeFactory(scheme, factory));
 165   }
 166
 167   // By default HttpCache is enabled with a default constructed HttpCacheParams.
 168   void EnableHttpCache(const HttpCacheParams& params);
 169   void DisableHttpCache();
 170
 171   // Override default HttpNetworkSession::Params settings.
 172   void set_http_network_session_params(
 173       const HttpNetworkSessionParams& http_network_session_params) {
 174     http_network_session_params_ = http_network_session_params;
 175   }
 176
 177   void set_transport_security_persister_path(
 178       const base::FilePath& transport_security_persister_path) {
 179     transport_security_persister_path_ = transport_security_persister_path;
 180   }
 181
 182   // Adjust |http_network_session_params_.next_protos| to enable SPDY and QUIC.
 183   void SetSpdyAndQuicEnabled(bool spdy_enabled,
 184                              bool quic_enabled);
 185
 186   void set_enable_insecure_quic(bool enable_insecure_quic) {
 187     http_network_session_params_.enable_insecure_quic = enable_insecure_quic;
 188   }
 189
 190   void set_quic_connection_options(
 191       const QuicTagVector& quic_connection_options) {
 192     http_network_session_params_.quic_connection_options =
 193         quic_connection_options;
 194   }
 195
 196   void set_throttling_enabled(bool throttling_enabled) {
 197     throttling_enabled_ = throttling_enabled;
 198   }
 199
 200   void set_backoff_enabled(bool backoff_enabled) {
 201     backoff_enabled_ = backoff_enabled;
 202   }
 203
 204   void SetInterceptors(
 205       ScopedVector<URLRequestInterceptor> url_request_interceptors);
 206
 207   // Override the default in-memory cookie store and channel id service.
 208   // |cookie_store| must not be NULL. |channel_id_service| may be NULL to
 209   // disable channel id for this context.
 210   // Note that a persistent cookie store should not be used with an in-memory
 211   // channel id service, and one cookie store should not be shared between
 212   // multiple channel-id stores (or used both with and without a channel id
 213   // store).
 214   void SetCookieAndChannelIdStores(
 215       const scoped_refptr<CookieStore>& cookie_store,
 216       scoped_ptr<ChannelIDService> channel_id_service);
 217
 218   // Sets the task runner used to perform file operations. If not set, one will
 219   // be created.
 220   void SetFileTaskRunner(
 221       const scoped_refptr<base::SingleThreadTaskRunner>& task_runner);
 222
 223   // Note that if SDCH is enabled without a policy object observing
 224   // the SDCH manager and handling at least Get-Dictionary events, the
 225   // result will be "Content-Encoding: sdch" advertisements, but no
 226   // dictionaries fetches and no specific dictionaries advertised.
 227   // SdchOwner in net/sdch/sdch_owner.h is a simple policy object.
 228   void set_sdch_enabled(bool enable) { sdch_enabled_ = enable; }
 229
 230   // Sets a specific HttpServerProperties for use in the
 231   // URLRequestContext rather than creating a default HttpServerPropertiesImpl.
 232   void SetHttpServerProperties(
 233       scoped_ptr<HttpServerProperties> http_server_properties);
 234
 235   scoped_ptr<URLRequestContext> Build();
 236
 237  private:
 238   struct NET_EXPORT SchemeFactory {
 239     SchemeFactory(const std::string& scheme, HttpAuthHandlerFactory* factory);
 240     ~SchemeFactory();
 241
 242     std::string scheme;
 243     HttpAuthHandlerFactory* factory;
 244   };
 245
 246   std::string accept_language_;
 247   std::string user_agent_;
 248   // Include support for data:// requests.
 249   bool data_enabled_;
 250 #if !defined(DISABLE_FILE_SUPPORT)
 251   // Include support for file:// requests.
 252   bool file_enabled_;
 253 #endif
 254 #if !defined(DISABLE_FTP_SUPPORT)
 255   // Include support for ftp:// requests.
 256   bool ftp_enabled_;
 257 #endif
 258   bool http_cache_enabled_;
 259   bool throttling_enabled_;
 260   bool backoff_enabled_;
 261   bool sdch_enabled_;
 262
 263   scoped_refptr<base::SingleThreadTaskRunner> file_task_runner_;
 264   HttpCacheParams http_cache_params_;
 265   HttpNetworkSessionParams http_network_session_params_;
 266   base::FilePath transport_security_persister_path_;
 267   NetLog* net_log_;
 268   scoped_ptr<HostResolver> host_resolver_;
 269   scoped_ptr<ChannelIDService> channel_id_service_;
 270   scoped_ptr<ProxyConfigService> proxy_config_service_;
 271   scoped_ptr<ProxyService> proxy_service_;
 272   scoped_ptr<NetworkDelegate> network_delegate_;
 273   scoped_refptr<CookieStore> cookie_store_;
 274   scoped_ptr<FtpTransactionFactory> ftp_transaction_factory_;
 275   std::vector<SchemeFactory> extra_http_auth_handlers_;
 276   ScopedVector<URLRequestInterceptor> url_request_interceptors_;
 277   scoped_ptr<HttpServerProperties> http_server_properties_;
 278
 279   DISALLOW_COPY_AND_ASSIGN(URLRequestContextBuilder);
 280 };
 281
 282 }  // namespace net
 283
 284 #endif  // NET_URL_REQUEST_URL_REQUEST_CONTEXT_BUILDER_H_