1 /* 2 * Copyright (c) 2020-2023 Apple Inc. All rights reserved. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * https://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 * 16 * This file contains the function declarations for discover_resolver.c, 17 * which will be called by mDNSCore code to set up the automatic browsing 18 * domain resolver. 19 */ 20 21 #ifndef __RESOLVER_DISCOVER_H__ 22 #define __RESOLVER_DISCOVER_H__ 23 24 #include "mDNSFeatures.h" // for MDNSRESPONDER_SUPPORTS(COMMON, LOCAL_DNS_RESOLVER_DISCOVERY) 25 26 #if MDNSRESPONDER_SUPPORTS(COMMON, LOCAL_DNS_RESOLVER_DISCOVERY) 27 28 //====================================================================================================================== 29 // MARK: - Headers 30 31 #include "mDNSEmbeddedAPI.h" 32 #include "general.h" 33 34 #include <stdbool.h> 35 36 #include "nullability.h" 37 38 MDNS_ASSUME_NONNULL_BEGIN 39 40 MDNS_C_DECLARATIONS_BEGIN 41 42 //====================================================================================================================== 43 // MARK: - Functions 44 45 /*! 46 * @brief 47 * Start the local DNS resolver discovery for the domain specified, by using reference counting to add/retain the discovery process. 48 * 49 * @param domain_to_discover 50 * The domain where the local DNS resolver should be discovered. 51 * 52 * @param grab_mdns_lock 53 * The boolean value of whether to grab the mDNS_Lock when doing query-related operation. 54 * 55 * @result 56 * True if the function succeeds, otherwise, false. 57 * 58 * @discussion 59 * When <code>resolver_discovery_add</code> is called, the discovery is not necessarily started on behalf of the caller. The discovery may have been 60 * started earlier by other caller. In which case, the same discovery activity will be retained and reused for the current caller. 61 */ 62 63 bool 64 resolver_discovery_add(const domainname *domain_to_discover, bool grab_mdns_lock); 65 66 /*! 67 * @brief 68 * Stop the local DNS resolver discovery for the domain specified, by using reference counting to remove/release the discovery process. 69 * 70 * @param domain_to_discover 71 * The domain where the local DNS resolver should be discovered. 72 * 73 * @param grab_mdns_lock 74 * The boolean value of whether to grab the mDNS_Lock when doing query-related operation. 75 * 76 * @result 77 * True if the function succeeds, otherwise, false. 78 * 79 * @discussion 80 * When <code>resolver_discovery_remove</code> is called, the discovery is not necessarily stopped on behalf of the caller. The discovery may be still used 81 * by other callers. In which case, the discovery will not be stopped, instead, it will be removed/released with reference counting. The resolver discovery will 82 * not be stopped until the last caller of <code>resolver_discovery_add</code> calls <code>resolver_discovery_remove</code>. 83 */ 84 85 bool 86 resolver_discovery_remove(const domainname *domain_to_discover, bool grab_mdns_lock); 87 88 /*! 89 * @brief 90 * Get the next time when mDNSCore should start processing the previously scheduled task for the resolver discovery. 91 * 92 * @result 93 * The next time to perform resolver discovery related tasks. 94 */ 95 mDNSs32 96 resolver_discovery_get_next_scheduled_event(void); 97 #define ResolverDiscovery_GetNextScheduledEvent(...) resolver_discovery_get_next_scheduled_event(__VA_ARGS__) 98 99 /*! 100 * @brief 101 * Perform resolver discovery related tasks. 102 */ 103 void 104 resolver_discovery_perform_periodic_tasks(void); 105 #define ResolverDiscovery_PerformPeriodicTasks(...) resolver_discovery_perform_periodic_tasks(__VA_ARGS__) 106 107 /*! 108 * @brief 109 * Check if the current DNS question is allowed to do resolve discovery, if so, return the domain that can do resolver discovery. 110 * 111 * @param q 112 * The DNS question. 113 * 114 * @param out_domain 115 * The pointer of the domain name to do resolver discovery when the DNS question is allowed to discover it. 116 * 117 * @result 118 * Returns true if the question is capable of doing resolver discovery and `out_domain` contains the domain, otherwise, false. 119 */ 120 bool 121 dns_question_requires_resolver_discovery(const DNSQuestion *q, const domainname * NULLABLE * NONNULL out_domain); 122 123 MDNS_C_DECLARATIONS_END 124 125 MDNS_ASSUME_NONNULL_END 126 127 #endif // MDNSRESPONDER_SUPPORTS(COMMON, LOCAL_DNS_RESOLVER_DISCOVERY) 128 129 #endif /* __RESOLVER_DISCOVER_H__ */ 130