tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

async_dns_resolver.h (4026B)

      1 /*
      2 *  Copyright 2021 The WebRTC Project Authors. All rights reserved.
      3 *
      4 *  Use of this source code is governed by a BSD-style license
      5 *  that can be found in the LICENSE file in the root of the source
      6 *  tree. An additional intellectual property rights grant can be found
      7 *  in the file PATENTS.  All contributing project authors may
      8 *  be found in the AUTHORS file in the root of the source tree.
      9 */
     10 
     11 #ifndef API_ASYNC_DNS_RESOLVER_H_
     12 #define API_ASYNC_DNS_RESOLVER_H_
     13 
     14 #include <memory>
     15 
     16 #include "absl/functional/any_invocable.h"
     17 #include "rtc_base/socket_address.h"
     18 #include "rtc_base/system/rtc_export.h"
     19 
     20 namespace webrtc {
     21 
     22 // This interface defines the methods to resolve a hostname asynchronously.
     23 // The AsyncDnsResolverInterface class encapsulates a single name query.
     24 //
     25 // Usage:
     26 // std::unique_ptr<AsyncDnsResolverInterface> resolver =
     27 //      factory->Create(address-to-be-resolved, [r = resolver.get()]() {
     28 //   if (r->result.GetResolvedAddress(AF_INET, &addr) {
     29 //     // success
     30 //   } else {
     31 //     // failure
     32 //     error = r->result().GetError();
     33 //   }
     34 //   // Release resolver.
     35 //   std::erase_if(resolver_list, [](refptr) { refptr.get() == r; });
     36 // });
     37 // resolver_list.push_back(std::move(resolver));
     38 
     39 class AsyncDnsResolverResult {
     40 public:
     41  virtual ~AsyncDnsResolverResult() = default;
     42  // Returns true iff the address from `Start` was successfully resolved.
     43  // If the address was successfully resolved, sets `addr` to a copy of the
     44  // address from `Start` with the IP address set to the top most resolved
     45  // address of `family` (`addr` will have both hostname and the resolved ip).
     46  virtual bool GetResolvedAddress(int family, SocketAddress* addr) const = 0;
     47  // Returns error from resolver.
     48  virtual int GetError() const = 0;
     49 };
     50 
     51 // The API for a single name query.
     52 // The constructor, destructor and all functions must be called from
     53 // the same sequence, and the callback will also be called on that sequence.
     54 // The class guarantees that the callback will not be called if the
     55 // resolver's destructor has been called.
     56 class RTC_EXPORT AsyncDnsResolverInterface {
     57 public:
     58  virtual ~AsyncDnsResolverInterface() = default;
     59 
     60  // Start address resolution of the hostname in `addr`.
     61  virtual void Start(const SocketAddress& addr,
     62                     absl::AnyInvocable<void()> callback) = 0;
     63  // Start address resolution of the hostname in `addr` matching `family`.
     64  virtual void Start(const SocketAddress& addr,
     65                     int family,
     66                     absl::AnyInvocable<void()> callback) = 0;
     67  virtual const AsyncDnsResolverResult& result() const = 0;
     68 };
     69 
     70 // An abstract factory for creating AsyncDnsResolverInterfaces. This allows
     71 // client applications to provide WebRTC with their own mechanism for
     72 // performing DNS resolution.
     73 class AsyncDnsResolverFactoryInterface {
     74 public:
     75  virtual ~AsyncDnsResolverFactoryInterface() = default;
     76 
     77  // Creates an AsyncDnsResolver and starts resolving the name. The callback
     78  // will be called when resolution is finished.
     79  // The callback will be called on the sequence that the caller runs on.
     80  virtual std::unique_ptr<AsyncDnsResolverInterface> CreateAndResolve(
     81      const SocketAddress& addr,
     82      absl::AnyInvocable<void()> callback) = 0;
     83  // Creates an AsyncDnsResolver and starts resolving the name to an address
     84  // matching the specified family. The callback will be called when resolution
     85  // is finished. The callback will be called on the sequence that the caller
     86  // runs on.
     87  virtual std::unique_ptr<AsyncDnsResolverInterface> CreateAndResolve(
     88      const SocketAddress& addr,
     89      int family,
     90      absl::AnyInvocable<void()> callback) = 0;
     91  // Creates an AsyncDnsResolver and does not start it.
     92  // For backwards compatibility, will be deprecated and removed.
     93  // One has to do a separate Start() call on the
     94  // resolver to start name resolution.
     95  virtual std::unique_ptr<AsyncDnsResolverInterface> Create() = 0;
     96 };
     97 
     98 }  // namespace webrtc
     99 
    100 #endif  // API_ASYNC_DNS_RESOLVER_H_