1 /* 2 * Copyright (c) 2023, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the platform DNS interface. 33 */ 34 35 #ifndef OPENTHREAD_PLATFORM_DNS_H_ 36 #define OPENTHREAD_PLATFORM_DNS_H_ 37 38 #include <openthread/instance.h> 39 #include <openthread/message.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup plat-dns 47 * 48 * @brief 49 * This module includes the platform abstraction for sending recursive DNS query to upstream DNS servers. 50 * 51 * @{ 52 */ 53 54 /** 55 * This opaque type represents an upstream DNS query transaction. 56 */ 57 typedef struct otPlatDnsUpstreamQuery otPlatDnsUpstreamQuery; 58 59 /** 60 * Starts an upstream query transaction. 61 * 62 * - In success case (and errors represented by DNS protocol messages), the platform is expected to call 63 * `otPlatDnsUpstreamQueryDone`. 64 * - The OpenThread core may cancel a (possibly timeout) query transaction by calling 65 * `otPlatDnsCancelUpstreamQuery`, the platform must not call `otPlatDnsUpstreamQueryDone` on a 66 * cancelled transaction. 67 * 68 * @param[in] aInstance The OpenThread instance structure. 69 * @param[in] aTxn A pointer to the opaque DNS query transaction object. 70 * @param[in] aQuery A message buffer of the DNS payload that should be sent to upstream DNS server. 71 */ 72 void otPlatDnsStartUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn, const otMessage *aQuery); 73 74 /** 75 * Cancels a transaction of upstream query. 76 * 77 * The platform must call `otPlatDnsUpstreamQueryDone` to release the resources. 78 * 79 * @param[in] aInstance The OpenThread instance structure. 80 * @param[in] aTxn A pointer to the opaque DNS query transaction object. 81 */ 82 void otPlatDnsCancelUpstreamQuery(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn); 83 84 /** 85 * The platform calls this function to finish DNS query. 86 * 87 * The transaction will be released, so the platform must not call on the same transaction twice. This function passes 88 * the ownership of `aResponse` to OpenThread stack. 89 * 90 * Platform can pass a nullptr to close a transaction without a response. 91 * 92 * @param[in] aInstance The OpenThread instance structure. 93 * @param[in] aTxn A pointer to the opaque DNS query transaction object. 94 * @param[in] aResponse A message buffer of the DNS response payload or `nullptr` to close a transaction without a 95 * response. 96 */ 97 extern void otPlatDnsUpstreamQueryDone(otInstance *aInstance, otPlatDnsUpstreamQuery *aTxn, otMessage *aResponse); 98 99 /** 100 * @} 101 */ 102 103 #ifdef __cplusplus 104 } 105 #endif 106 107 #endif 108
