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