doh.h

/*
 * Copyright (C) 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// This file can be autogenerated by the following command, but the generated file
// may not pass clang-format check.
//   cbindgen --config cbindgen.toml doh/doh.rs -o doh.h

#pragma once

#include <stdint.h>
#include <sys/types.h>

/// The return code of doh_query means that there is no answer.
static const ssize_t DOH_RESULT_INTERNAL_ERROR = -1;

/// The return code of doh_query means that query can't be sent.
static const ssize_t DOH_RESULT_CAN_NOT_SEND = -2;

/// The return code of doh_query to indicate that the query timed out.
static const ssize_t DOH_RESULT_TIMEOUT = -255;

/// The error log level.
static const uint32_t DOH_LOG_LEVEL_ERROR = 0;

/// The warning log level.
static const uint32_t DOH_LOG_LEVEL_WARN = 1;

/// The info log level.
static const uint32_t DOH_LOG_LEVEL_INFO = 2;

/// The debug log level.
static const uint32_t DOH_LOG_LEVEL_DEBUG = 3;

/// The trace log level.
static const uint32_t DOH_LOG_LEVEL_TRACE = 4;

/// Context for a running DoH engine.
struct DohDispatcher;

struct FeatureFlags {
    uint64_t probe_timeout_ms;
    uint64_t idle_timeout_ms;
    bool use_session_resumption;
    bool enable_early_data;
};

using ValidationCallback = void (*)(uint32_t net_id, bool success, const char* ip_addr,
                                    const char* host);

using TagSocketCallback = void (*)(int32_t sock);

extern "C" {

/// Performs static initialization for android logger.
/// If an invalid level is passed, defaults to logging errors only.
/// If called more than once, it will have no effect on subsequent calls.
void doh_init_logger(uint32_t level);

/// Set the log level.
/// If an invalid level is passed, defaults to logging errors only.
void doh_set_log_level(uint32_t level);

/// Performs the initialization for the DoH engine.
/// Creates and returns a DoH engine instance.
DohDispatcher* doh_dispatcher_new(ValidationCallback validation_fn,
                                  TagSocketCallback tag_socket_fn);

/// Deletes a DoH engine created by doh_dispatcher_new().
/// # Safety
/// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()`
/// and not yet deleted by `doh_dispatcher_delete()`.
void doh_dispatcher_delete(DohDispatcher* doh);

/// Probes and stores the DoH server with the given configurations.
/// Use the negative errno-style codes as the return value to represent the result.
/// # Safety
/// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()`
/// and not yet deleted by `doh_dispatcher_delete()`.
/// `url`, `domain`, `ip_addr`, `cert_path` are null terminated strings.
int32_t doh_net_new(DohDispatcher* doh, uint32_t net_id, const char* url, const char* domain,
                    const char* ip_addr, uint32_t sk_mark, const char* cert_path,
                    const FeatureFlags* flags);

/// Sends a DNS query via the network associated to the given |net_id| and waits for the response.
/// The return code should be either one of the public constant RESULT_* to indicate the error or
/// the size of the answer.
/// # Safety
/// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()`
/// and not yet deleted by `doh_dispatcher_delete()`.
/// `dns_query` must point to a buffer at least `dns_query_len` in size.
/// `response` must point to a buffer at least `response_len` in size.
ssize_t doh_query(DohDispatcher* doh, uint32_t net_id, uint8_t* dns_query, size_t dns_query_len,
                  uint8_t* response, size_t response_len, uint64_t timeout_ms);

/// Clears the DoH servers associated with the given |netid|.
/// # Safety
/// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()`
/// and not yet deleted by `doh_dispatcher_delete()`.
void doh_net_delete(DohDispatcher* doh, uint32_t net_id);

}  // extern "C"