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
16namespace 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.
26class 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.
82class NET_EXPORT_PRIVATE DoNothingDhcpProxyScriptFetcher
83    : public DhcpProxyScriptFetcher {
84 public:
85  DoNothingDhcpProxyScriptFetcher();
86  virtual ~DoNothingDhcpProxyScriptFetcher();
87
88  virtual int Fetch(base::string16* utf16_text,
89                    const CompletionCallback& callback) OVERRIDE;
90  virtual void Cancel() OVERRIDE;
91  virtual const GURL& GetPacURL() const OVERRIDE;
92 private:
93  GURL gurl_;
94  DISALLOW_COPY_AND_ASSIGN(DoNothingDhcpProxyScriptFetcher);
95};
96
97}  // namespace net
98
99#endif  // NET_PROXY_DHCP_SCRIPT_FETCHER_H_
100