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 <functional> 15 #include <memory> 16 17 #include "rtc_base/checks.h" 18 #include "rtc_base/socket_address.h" 19 #include "rtc_base/system/rtc_export.h" 20 21 namespace webrtc { 22 23 // This interface defines the methods to resolve a hostname asynchronously. 24 // The AsyncDnsResolverInterface class encapsulates a single name query. 25 // 26 // Usage: 27 // std::unique_ptr<AsyncDnsResolverInterface> resolver = 28 // factory->Create(address-to-be-resolved, [r = resolver.get()]() { 29 // if (r->result.GetResolvedAddress(AF_INET, &addr) { 30 // // success 31 // } else { 32 // // failure 33 // error = r->result().GetError(); 34 // } 35 // // Release resolver. 36 // resolver_list.erase(std::remove_if(resolver_list.begin(), 37 // resolver_list.end(), 38 // [](refptr) { refptr.get() == r; }); 39 // }); 40 // resolver_list.push_back(std::move(resolver)); 41 42 class AsyncDnsResolverResult { 43 public: 44 virtual ~AsyncDnsResolverResult() = default; 45 // Returns true iff the address from `Start` was successfully resolved. 46 // If the address was successfully resolved, sets `addr` to a copy of the 47 // address from `Start` with the IP address set to the top most resolved 48 // address of `family` (`addr` will have both hostname and the resolved ip). 49 virtual bool GetResolvedAddress(int family, 50 rtc::SocketAddress* addr) const = 0; 51 // Returns error from resolver. 52 virtual int GetError() const = 0; 53 }; 54 55 // The API for a single name query. 56 // The constructor, destructor and all functions must be called from 57 // the same sequence, and the callback will also be called on that sequence. 58 // The class guarantees that the callback will not be called if the 59 // resolver's destructor has been called. 60 class RTC_EXPORT AsyncDnsResolverInterface { 61 public: 62 virtual ~AsyncDnsResolverInterface() = default; 63 64 // Start address resolution of the hostname in `addr`. 65 virtual void Start(const rtc::SocketAddress& addr, 66 std::function<void()> callback) = 0; 67 // Start address resolution of the hostname in `addr` matching `family`. 68 virtual void Start(const rtc::SocketAddress& addr, 69 int family, 70 std::function<void()> callback) = 0; 71 virtual const AsyncDnsResolverResult& result() const = 0; 72 }; 73 74 // An abstract factory for creating AsyncDnsResolverInterfaces. This allows 75 // client applications to provide WebRTC with their own mechanism for 76 // performing DNS resolution. 77 class AsyncDnsResolverFactoryInterface { 78 public: 79 virtual ~AsyncDnsResolverFactoryInterface() = default; 80 81 // Creates an AsyncDnsResolver and starts resolving the name. The callback 82 // will be called when resolution is finished. 83 // The callback will be called on the sequence that the caller runs on. 84 virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> CreateAndResolve( 85 const rtc::SocketAddress& addr, 86 std::function<void()> callback) = 0; 87 // Creates an AsyncDnsResolver and starts resolving the name to an address 88 // matching the specified family. The callback will be called when resolution 89 // is finished. The callback will be called on the sequence that the caller 90 // runs on. 91 virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> CreateAndResolve( 92 const rtc::SocketAddress& addr, 93 int family, 94 std::function<void()> callback) = 0; 95 // Creates an AsyncDnsResolver and does not start it. 96 // For backwards compatibility, will be deprecated and removed. 97 // One has to do a separate Start() call on the 98 // resolver to start name resolution. 99 virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> Create() = 0; 100 }; 101 102 } // namespace webrtc 103 104 #endif // API_ASYNC_DNS_RESOLVER_H_ 105