HTTPDNS:Integrate the C SDK

Step 1: Prepare the environment

SDK integration requires the following build tools and third-party libraries. Install these dependencies on your build machine before you proceed.

1. Install build tools

The build process uses Git, CMake, and gcc/g++. Make sure these CLI tools are installed on your local machine. If not, run the following commands to install them:

• Ubuntu/Debian

  sudo  apt update
  sudo  apt install -y git cmake gcc g++

• Alibaba Cloud Linux/CentOS Stream/Fedora

  sudo yum check-update
  sudo yum install -y git cmake  gcc  gcc-c++

• OpenSUSE

  sudo zypper refresh
  sudo zypper install -y git cmake  gcc  gcc-c++

• macOS

  export HOMEBREW_NO_AUTO_UPDATE=1
  brew install git gcc cmake

  Note

  Homebrew is not a built-in package manager for macOS. Before you install packages, install Homebrew.

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• Windows

  • Download and install Git

  • Download and install Visual Studio (Select the "Desktop development with C++" workload)

2. Install dependency libraries

The SDK depends on libcurl (7.33.0 or later) for network operations, apr/apr-util (1.5.2 or later) for memory management and cross-platform compatibility, and cjson for parsing server responses. These libraries are not bundled with the SDK. Install them and add their header file and library file directories to your project. You can use VCPKG or install them manually.

2.1 VCPKG installation

• Install VCPKG

• Install the SDK dependency libraries

  • macOS/Linux

     ./vcpkg install apr apr-util curl[openssl,http2] cjson

  • Windows

    .\vcpkg.exe install apr apr-util curl[openssl,http2] cjson

    Note

    VCPKG installs libraries for the current platform by default. To cross-compile, such as compiling an x86 library in a Windows x64 environment, specify a triplet. Example:

    ./vcpkg.exe install apr:x86-windows apr-util:x86-windows curl[openssl,http2]:x86-windows cjson:x86-windows

2.2 Manual installation

• Ubuntu/Debian

  sudo  apt update
  sudo apt install -y libcurl4-openssl-dev libapr1-dev libaprutil1-dev libcjson-dev

• Alibaba Cloud Linux/CentOS Stream/Fedora

  sudo yum check-update
  sudo yum install -y libcurl-devel apr-devel apr-util-devel cjson-devel

• OpenSUSE

  sudo zypper refresh
  sudo zypper install -y libcurl-devel libapr1-devel libapr-util1-devel cJSON-devel

• macOS

  brew install curl apr apr-util cjson

• Windows

  • Download and install cjson

  • Download and install OpenSSL

  • Download curl

  • Install curl

  • Download and install apr/apr-util

git clone https://github.com/DaveGamble/cJSON.git && cd cJSON && mkdir build && cd build && cmake  ../ && sudo make install && cd ../../ && rm -rf cJSON

Step 2: Install the SDK

• Linux/macOS

  git clone https://github.com/aliyun/alibabacloud-httpdns-c-sdk.git
  cd alibabacloud-httpdns-c-sdk
  mkdir build
  cd build
  # If you installed the dependency libraries using VCPKG, add the CMake parameter -DVCPKG_ROOT=${path_to_vcpkg} when you build the SDK.
  cmake -DCMAKE_BUILD_TYPE=Release ../ 
  make hdns_unite_test
  sudo make install
  sudo ldconfig

• Windows

  • Download the project.

  • Open the CMake project in Visual Studio.

  • In the configuration manager, set the CMake command parameter to -DVCPKG_ROOT=${path_to_vcpkg}

Step 3: Integrate the SDK

For details, see C integration example. The following steps describe the integration procedure.

3.1 Import the SDK

Add the installed libraries and header files to your project. For a CMake project, add the following commands to the CMakeLists.txt file:

find_library(HTTPDNS_LIBRARY httpdns_c_sdk_static)
include_directories(${CMAKE_INSTALL_PREFIX}/include/httpdns)

3.2 Initialize the SDK

Initialize the SDK runtime environment.

 if (hdns_sdk_init() != HDNS_OK) {
        hdns_sdk_cleanup();
  }
   
  // Use the SDK API.
  
  

3.3 Create a client

 hdns_client_t *client = hdns_client_create(HTTPDNS_ACCOUNT, HTTPDNS_SECRET);
 if (client == NULL) {
    hdns_sdk_cleanup();
  }
 // Use the HTTPDNS client.

3.4 Configure the client

After you create a client instance, customize the HTTPDNS client configuration:

// Set the server-side request timeout period in milliseconds.
hdns_client_set_timeout(client, 2000);
// Specify whether to enable the local cache.
hdns_client_set_using_cache(client, true);
// Specify whether to use HTTPS to access the HTTPDNS server.
hdns_client_set_using_https(client, true);
// Specify whether to add a signature to the request.
hdns_client_set_using_sign(client,  true);
// Set the number of retries for server-side requests.
hdns_client_set_retry_times(client, 1);
// Set the HTTPDNS resolution service cluster.
hdns_client_set_region(client, "global");
// Set the HTTPDNS scheduling cluster.
hdns_client_set_schedule_center_region(client, "cn");
// Specify whether to update the local cache after the network changes.
hdns_client_enable_update_cache_after_net_change(client, true);
// Specify whether to allow retrieval of expired cache.
hdns_client_enable_expired_ip(client, true);
// Specify whether to automatically fall back to LocalDNS.
hdns_client_enable_failover_localdns(client, true);
// Add a domain name for pre-resolution.
hdns_client_add_pre_resolve_host(client, "www.aliyun.com");
// Add an IP address for sniffing attacks.
hdns_client_add_ip_probe_item(client, "www.aliyun.com", 443);
// Customize the time-to-live (TTL).
hdns_client_add_custom_ttl_item(client, "www.aliyun.com", 120);

3.5 Start the client

   hdns_client_start(client);

3.6 Resolve a domain name

After the client starts, call the SDK API operations to resolve domain names. The following example performs synchronous resolution of a single domain name:

    hdns_list_head_t *results = NULL;
    hdns_status_t status = hdns_get_result_for_host_sync_with_cache(client,
                                                                    MOCK_BUSINESS_HOST,
                                                                    HDNS_QUERY_AUTO,
                                                                    NULL, &results);

3.7 Select an IP address

After you obtain the resolution result, use a resolved IP address to access your service.

 if (hdns_status_is_ok(&status)) {
        char ip[HDNS_IP_ADDRESS_STRING_LENGTH];
        if (hdns_select_ip_randomly(results, HDNS_QUERY_AUTO, ip) == HDNS_OK) {
            mock_access_business_web_server(ip);
        }
  }
  if (hdns_status_is_ok(&status)) {
        char ip[HDNS_IP_ADDRESS_STRING_LENGTH];
        if (hdns_select_ip_randomly(results, HDNS_QUERY_AUTO, ip) == HDNS_OK) {
            mock_access_business_web_server(ip);
        }
  }
  hdns_list_free(results);

3.8 Access the service

static void mock_access_business_web_server(const char *dst_ip) {
    CURL *curl;
    CURLcode res;
    curl = curl_easy_init();
    if (curl) {
        // Concatenate the service URL.
        char url[256];
        strcpy(url, "https://");
        strcat(url, MOCK_BUSINESS_HOST);
        curl_easy_setopt(curl, CURLOPT_URL, url);
        curl_easy_setopt(curl, CURLOPT_TIMEOUT, 30);

        // Set the pre-resolved host and IP address for HTTPS.
        struct curl_slist *dns;
        char sni[256];
        strcpy(sni, MOCK_BUSINESS_HOST);
        strcat(sni, ":443:");
        strcat(sni, dst_ip);
        dns = curl_slist_append(NULL, sni);
        curl_easy_setopt(curl, CURLOPT_RESOLVE, dns);
        // Set the response result callback.
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_data_callback);
#if defined(_WIN32)
        curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, CURLSSLOPT_NATIVE_CA);
#endif
        // Initiate an HTTP request.
        res = curl_easy_perform(curl);
        if (res != CURLE_OK) {
            fprintf(stderr, "curl_easy_perform() failed, url=%s, ip=%s, error=%s\n",
                    url,
                    dst_ip,
                    curl_easy_strerror(res));
        }
        // Release resources related to service access.
        curl_slist_free_all(dns);
        /* always cleanup */
        curl_easy_cleanup(curl);
    }
}

3.9 Clean up the client

When the client is no longer in use, release it.

hdns_client_cleanup(client);

3.10 Clean up the SDK

When the SDK is no longer in use, release it.

hdns_sdk_cleanup();