net/proxy/dhcp_proxy_script_fetcher.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 #ifndef NET_PROXY_DHCP_SCRIPT_FETCHER_H_
   6 #define NET_PROXY_DHCP_SCRIPT_FETCHER_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/compiler_specific.h"
  10 #include "base/strings/string16.h"
  11 #include "net/base/completion_callback.h"
  12 #include "net/base/net_export.h"
  13 #include "net/proxy/proxy_script_fetcher.h"
  14 #include "url/gurl.h"
  15
  16 namespace net {
  17
  18 // Interface for classes that can fetch a proxy script as configured via DHCP.
  19 //
  20 // The Fetch method on this interface tries to retrieve the most appropriate
  21 // PAC script configured via DHCP.
  22 //
  23 // Normally there are zero or one DHCP scripts configured, but in the
  24 // presence of multiple adapters with DHCP enabled, the fetcher resolves
  25 // which PAC script to use if one or more are available.
  26 class NET_EXPORT_PRIVATE DhcpProxyScriptFetcher {
  27  public:
  28   // Destruction should cancel any outstanding requests.
  29   virtual ~DhcpProxyScriptFetcher();
  30
  31   // Attempts to retrieve the most appropriate PAC script configured via DHCP,
  32   // and invokes |callback| on completion.
  33   //
  34   // Returns OK on success, otherwise the error code. If the return code is
  35   // ERR_IO_PENDING, then the request completes asynchronously, and |callback|
  36   // will be invoked later with the final error code.
  37   //
  38   // After synchronous or asynchronous completion with a result code of OK,
  39   // |*utf16_text| is filled with the response. On failure, the result text is
  40   // an empty string, and the result code is a network error. Some special
  41   // network errors that may occur are:
  42   //
  43   //    ERR_PAC_NOT_IN_DHCP   -- no script configured in DHCP.
  44   //
  45   //    The following all indicate there was one or more script configured
  46   //    in DHCP but all failed to download, and the error for the most
  47   //    preferred adapter that had a script configured was what the error
  48   //    code says:
  49   //
  50   //      ERR_TIMED_OUT         -- fetch took too long to complete.
  51   //      ERR_FILE_TOO_BIG      -- response body was too large.
  52   //      ERR_PAC_STATUS_NOT_OK -- script failed to download.
  53   //      ERR_NOT_IMPLEMENTED   -- script required authentication.
  54   //
  55   // If the request is cancelled (either using the "Cancel()" method or by
  56   // deleting |this|), then no callback is invoked.
  57   //
  58   // Only one fetch is allowed to be outstanding at a time.
  59   virtual int Fetch(base::string16* utf16_text,
  60                     const CompletionCallback& callback) = 0;
  61
  62   // Aborts the in-progress fetch (if any).
  63   virtual void Cancel() = 0;
  64
  65   // After successful completion of |Fetch()|, this will return the URL
  66   // retrieved from DHCP.  It is reset if/when |Fetch()| is called again.
  67   virtual const GURL& GetPacURL() const = 0;
  68
  69   // Intended for unit tests only, so they can test that factories return
  70   // the right types under given circumstances.
  71   virtual std::string GetFetcherName() const;
  72
  73  protected:
  74   DhcpProxyScriptFetcher();
  75
  76  private:
  77   DISALLOW_COPY_AND_ASSIGN(DhcpProxyScriptFetcher);
  78 };
  79
  80 // A do-nothing retriever, always returns synchronously with
  81 // ERR_NOT_IMPLEMENTED result and empty text.
  82 class NET_EXPORT_PRIVATE DoNothingDhcpProxyScriptFetcher
  83     : public DhcpProxyScriptFetcher {
  84  public:
  85   DoNothingDhcpProxyScriptFetcher();
  86   ~DoNothingDhcpProxyScriptFetcher() override;
  87
  88   int Fetch(base::string16* utf16_text,
  89             const CompletionCallback& callback) override;
  90   void Cancel() override;
  91   const GURL& GetPacURL() const override;
  92
  93  private:
  94   GURL gurl_;
  95   DISALLOW_COPY_AND_ASSIGN(DoNothingDhcpProxyScriptFetcher);
  96 };
  97
  98 }  // namespace net
  99
 100 #endif  // NET_PROXY_DHCP_SCRIPT_FETCHER_H_