Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 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 | |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 14 | #include <memory> |
| 15 | |
Harald Alvestrand | 96e1882 | 2023-08-30 19:39:05 | [diff] [blame] | 16 | #include "absl/functional/any_invocable.h" |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 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 | // resolver_list.erase(std::remove_if(resolver_list.begin(), |
| 36 | // resolver_list.end(), |
| 37 | // [](refptr) { refptr.get() == r; }); |
| 38 | // }); |
| 39 | // resolver_list.push_back(std::move(resolver)); |
| 40 | |
| 41 | class AsyncDnsResolverResult { |
| 42 | public: |
| 43 | virtual ~AsyncDnsResolverResult() = default; |
Artem Titov | 0e61fdd | 2021-07-25 19:50:14 | [diff] [blame] | 44 | // Returns true iff the address from `Start` was successfully resolved. |
| 45 | // If the address was successfully resolved, sets `addr` to a copy of the |
| 46 | // address from `Start` with the IP address set to the top most resolved |
| 47 | // address of `family` (`addr` will have both hostname and the resolved ip). |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 48 | virtual bool GetResolvedAddress(int family, |
| 49 | rtc::SocketAddress* addr) const = 0; |
| 50 | // Returns error from resolver. |
| 51 | virtual int GetError() const = 0; |
| 52 | }; |
| 53 | |
Harald Alvestrand | b7b306b | 2021-10-05 14:05:36 | [diff] [blame] | 54 | // The API for a single name query. |
| 55 | // The constructor, destructor and all functions must be called from |
| 56 | // the same sequence, and the callback will also be called on that sequence. |
| 57 | // The class guarantees that the callback will not be called if the |
| 58 | // resolver's destructor has been called. |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 59 | class RTC_EXPORT AsyncDnsResolverInterface { |
| 60 | public: |
| 61 | virtual ~AsyncDnsResolverInterface() = default; |
| 62 | |
Artem Titov | 0e61fdd | 2021-07-25 19:50:14 | [diff] [blame] | 63 | // Start address resolution of the hostname in `addr`. |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 64 | virtual void Start(const rtc::SocketAddress& addr, |
Harald Alvestrand | 96e1882 | 2023-08-30 19:39:05 | [diff] [blame] | 65 | absl::AnyInvocable<void()> callback) = 0; |
Sameer Vijaykar | b787e26 | 2022-08-11 09:52:57 | [diff] [blame] | 66 | // Start address resolution of the hostname in `addr` matching `family`. |
| 67 | virtual void Start(const rtc::SocketAddress& addr, |
| 68 | int family, |
Harald Alvestrand | 96e1882 | 2023-08-30 19:39:05 | [diff] [blame] | 69 | absl::AnyInvocable<void()> callback) = 0; |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 70 | virtual const AsyncDnsResolverResult& result() const = 0; |
| 71 | }; |
| 72 | |
| 73 | // An abstract factory for creating AsyncDnsResolverInterfaces. This allows |
| 74 | // client applications to provide WebRTC with their own mechanism for |
| 75 | // performing DNS resolution. |
| 76 | class AsyncDnsResolverFactoryInterface { |
| 77 | public: |
| 78 | virtual ~AsyncDnsResolverFactoryInterface() = default; |
| 79 | |
| 80 | // Creates an AsyncDnsResolver and starts resolving the name. The callback |
| 81 | // will be called when resolution is finished. |
Harald Alvestrand | b7b306b | 2021-10-05 14:05:36 | [diff] [blame] | 82 | // The callback will be called on the sequence that the caller runs on. |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 83 | virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> CreateAndResolve( |
| 84 | const rtc::SocketAddress& addr, |
Harald Alvestrand | 96e1882 | 2023-08-30 19:39:05 | [diff] [blame] | 85 | absl::AnyInvocable<void()> callback) = 0; |
Sameer Vijaykar | b787e26 | 2022-08-11 09:52:57 | [diff] [blame] | 86 | // Creates an AsyncDnsResolver and starts resolving the name to an address |
| 87 | // matching the specified family. The callback will be called when resolution |
| 88 | // is finished. The callback will be called on the sequence that the caller |
| 89 | // runs on. |
| 90 | virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> CreateAndResolve( |
| 91 | const rtc::SocketAddress& addr, |
| 92 | int family, |
Harald Alvestrand | 96e1882 | 2023-08-30 19:39:05 | [diff] [blame] | 93 | absl::AnyInvocable<void()> callback) = 0; |
Harald Alvestrand | e6e2f28 | 2021-03-24 12:13:28 | [diff] [blame] | 94 | // Creates an AsyncDnsResolver and does not start it. |
| 95 | // For backwards compatibility, will be deprecated and removed. |
| 96 | // One has to do a separate Start() call on the |
| 97 | // resolver to start name resolution. |
| 98 | virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> Create() = 0; |
| 99 | }; |
| 100 | |
| 101 | } // namespace webrtc |
| 102 | |
| 103 | #endif // API_ASYNC_DNS_RESOLVER_H_ |