blob: d055a5b7c8d2a5978286cf3e09d50d0eb1d1c6a7 [file] [log] [blame]
Harald Alvestrande6e2f282021-03-24 12:13:281/*
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 Alvestrande6e2f282021-03-24 12:13:2814#include <memory>
15
Harald Alvestrand96e18822023-08-30 19:39:0516#include "absl/functional/any_invocable.h"
Harald Alvestrande6e2f282021-03-24 12:13:2817#include "rtc_base/socket_address.h"
18#include "rtc_base/system/rtc_export.h"
19
20namespace 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
41class AsyncDnsResolverResult {
42 public:
43 virtual ~AsyncDnsResolverResult() = default;
Artem Titov0e61fdd2021-07-25 19:50:1444 // 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 Alvestrande6e2f282021-03-24 12:13:2848 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 Alvestrandb7b306b2021-10-05 14:05:3654// 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 Alvestrande6e2f282021-03-24 12:13:2859class RTC_EXPORT AsyncDnsResolverInterface {
60 public:
61 virtual ~AsyncDnsResolverInterface() = default;
62
Artem Titov0e61fdd2021-07-25 19:50:1463 // Start address resolution of the hostname in `addr`.
Harald Alvestrande6e2f282021-03-24 12:13:2864 virtual void Start(const rtc::SocketAddress& addr,
Harald Alvestrand96e18822023-08-30 19:39:0565 absl::AnyInvocable<void()> callback) = 0;
Sameer Vijaykarb787e262022-08-11 09:52:5766 // Start address resolution of the hostname in `addr` matching `family`.
67 virtual void Start(const rtc::SocketAddress& addr,
68 int family,
Harald Alvestrand96e18822023-08-30 19:39:0569 absl::AnyInvocable<void()> callback) = 0;
Harald Alvestrande6e2f282021-03-24 12:13:2870 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.
76class 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 Alvestrandb7b306b2021-10-05 14:05:3682 // The callback will be called on the sequence that the caller runs on.
Harald Alvestrande6e2f282021-03-24 12:13:2883 virtual std::unique_ptr<webrtc::AsyncDnsResolverInterface> CreateAndResolve(
84 const rtc::SocketAddress& addr,
Harald Alvestrand96e18822023-08-30 19:39:0585 absl::AnyInvocable<void()> callback) = 0;
Sameer Vijaykarb787e262022-08-11 09:52:5786 // 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 Alvestrand96e18822023-08-30 19:39:0593 absl::AnyInvocable<void()> callback) = 0;
Harald Alvestrande6e2f282021-03-24 12:13:2894 // 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_