Home | History | Annotate | Line # | Download | only in mDNSShared 
      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