winhttp_api_wrapper.h 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. // Copyright 2020 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. #ifndef SERVICES_PROXY_RESOLVER_WIN_WINHTTP_API_WRAPPER_H_
  5. #define SERVICES_PROXY_RESOLVER_WIN_WINHTTP_API_WRAPPER_H_
  6. #include <windows.h>
  7. #include <winhttp.h>
  8. #include <string>
  9. #include "base/component_export.h"
  10. namespace proxy_resolver_win {
  11. // This provides a layer of abstraction between calling code and WinHTTP APIs,
  12. // allowing them to be mocked out for testing. This object is not thread safe
  13. // and it's expected that the caller will handle using it on the same thread or
  14. // sequence. In general, documentation for these APIs can be found here:
  15. // https://docs.microsoft.com/en-us/windows/win32/api/winhttp/
  16. class COMPONENT_EXPORT(PROXY_RESOLVER_WIN) WinHttpAPIWrapper {
  17. public:
  18. virtual ~WinHttpAPIWrapper() = default;
  19. // Creates our WinHttp session handle |session_handle_|. The lifetime of that
  20. // session handle is determined by the lifetime of this object. It'll get
  21. // closed when this object destructs.
  22. [[nodiscard]] virtual bool CallWinHttpOpen() = 0;
  23. // Controls the timeout for WinHttpGetProxyForUrlEx().
  24. [[nodiscard]] virtual bool CallWinHttpSetTimeouts(int resolve_timeout,
  25. int connect_timeout,
  26. int send_timeout,
  27. int receive_timeout) = 0;
  28. // Sets the callback WinHttp will call into with the result of any
  29. // asynchronous call.
  30. [[nodiscard]] virtual bool CallWinHttpSetStatusCallback(
  31. WINHTTP_STATUS_CALLBACK internet_callback) = 0;
  32. // Fetches the proxy configs for the current active network connection and
  33. // current Windows user. The |ie_proxy_config| says whether or not
  34. // AutoProxy (WPAD) is enabled and if there's a PAC URL configured for this
  35. // connection/user.
  36. [[nodiscard]] virtual bool CallWinHttpGetIEProxyConfigForCurrentUser(
  37. WINHTTP_CURRENT_USER_IE_PROXY_CONFIG* ie_proxy_config) = 0;
  38. // Creates a handle |resolver_handle| that should be used for the call to
  39. // WinHttpGetProxyForUrlEx().
  40. [[nodiscard]] virtual bool CallWinHttpCreateProxyResolver(
  41. HINTERNET* out_resolver_handle) = 0;
  42. // Using the specific |resolver_handle| handle from
  43. // CallWinHttpCreateProxyResolver(), resolve a proxy for a specific |url| with
  44. // the aid of some |autoproxy_options|. When WinHttpGetProxyForUrlEx()
  45. // finishes its work or hits an error, it'll call into the callback set by
  46. // CallWinHttpSetStatusCallback() above exactly once and supply the provided
  47. // |context|.
  48. //
  49. // WinHttpGetProxyForUrlEx() will go async to do all necessary logic. As long
  50. // as it receives good inputs (valid handle, valid combination of flags,
  51. // non-null PAC URL if needed), this API will almost always return
  52. // ERROR_IO_PENDING. It'll only fail for reasons like running out of memory.
  53. // When it returns ERROR_IO_PENDING, CallWinHttpGetProxyForUrlEx() will return
  54. // true.
  55. //
  56. // WinHttpGetProxyForUrlEx() will do proxy fallback internally and return to
  57. // a proxy result. It will first check WPAD (if enabled). If that fails, it'll
  58. // attempt to download and run any provided PAC script. If the PAC script was
  59. // not provided or if it fails, it'll use the right per-interface static
  60. // proxy. If all else fails or isn't configured, it'll simply return DIRECT.
  61. // WinHttpGetProxyForUrlEx() supports commonly used enterprise proxy features
  62. // such as DirectAccess/NRPT.
  63. [[nodiscard]] virtual bool CallWinHttpGetProxyForUrlEx(
  64. HINTERNET resolver_handle,
  65. const std::string& url,
  66. WINHTTP_AUTOPROXY_OPTIONS* autoproxy_options,
  67. DWORD_PTR context) = 0;
  68. // As long as CallWinHttpGetProxyForUrlEx() doesn't hit any errors, there will
  69. // be a proxy result to examine. This function retrieves that proxy resolution
  70. // result |proxy_result| using the resolver's handle |resolver_handle|. The
  71. // result must be freed with CallWinHttpFreeProxyResult().
  72. [[nodiscard]] virtual bool CallWinHttpGetProxyResult(
  73. HINTERNET resolver_handle,
  74. WINHTTP_PROXY_RESULT* proxy_result) = 0;
  75. // Frees the |proxy_result| retrieved by CallWinHttpGetProxyResult().
  76. virtual void CallWinHttpFreeProxyResult(
  77. WINHTTP_PROXY_RESULT* proxy_result) = 0;
  78. // Every opened HINTERNET handle must be closed. This closes handle
  79. // |internet_handle|. After being closed, WinHttp calls cannot be made using
  80. // that handle.
  81. virtual void CallWinHttpCloseHandle(HINTERNET internet_handle) = 0;
  82. };
  83. } // namespace proxy_resolver_win
  84. #endif // SERVICES_PROXY_RESOLVER_WIN_WINHTTP_API_WRAPPER_H_