ARES_LIBRARY_INIT_ANDROID(3)

💖 ARES_LIBRARY_INIT_ANDROID 💖

okay so bestie, welcome to the Library Functions Manual, section 3, where we talk about ares_library_init_android — the c-ares library Android initialization. this is the page where Android and c-ares finally get introduced to each other 🫶

---

🌸 NAME 🌸

ares_library_init_android — c-ares library Android initialization

---

✨ SYNOPSIS ✨

#include <ares.h>

int ares_library_init_android(jobject connectivity_manager)

int ares_library_android_initialized();

void ares_library_init_jvm(JavaVM *jvm)

---

💅 DESCRIPTION 💅

so the ares_library_init_android(3) function does all the initializations that the c-ares library needs internally when you're running on Android. it can happen any time after ares_library_init(3), no rush, but it must happen after ares_library_init_jvm. and lowkey important: ares_library_init_android has to be called before DNS resolution will even work on Android 8 (Oreo) or newer when targetSdkVersion is set to 26+. no init, no DNS, periodt. 💀

starting with Android 8 (API level 26), getting DNS server information got way more restrictive and it can only be accessed using the Connectivity Manager. so you gotta pass the connectivity manager over to c-ares via JNI. also, the ACCESS_NETWORK_STATE permission has to be present in the Android application. not optional, bestie. 🎀

Android older than 8? they don't need to be initialized because they're less restrictive. BUT — and this is the plot twist — this is a run time limitation, not a compile time one. proper Android initialization should happen regardless of the targeted Android version. like, just do it. it's giving responsible. ✨

deinitialization happens through ares_library_cleanup(3), so it all comes full circle. 🌈

the ares_library_init_jvm function is what lets the caller register the JVM with c-ares. it's meant to be called during JNI_OnLoad because that's the function where you're guaranteed to have the JVM. the JVM is required in order to use the Connectivity Manager registered using ares_library_init_android(3). and yes, this must be called before ares_library_init_android(3). order matters, queen. 👑

the ares_library_android_initialized function is your lil vibe check — use it to see whether c-ares has been initialized for use with Android. 👀

---

🔥 RETURN VALUES 🔥

ARES_SUCCESS gets returned on success. otherwise you get an error code. simple as that. 🍓

---

👑 THREAD SAFETY 👑

these init functions are not thread safe. you have to call them once the program has started, but that call must be done before the program starts any other thread. this is required to avoid potential race conditions in library initialization, and also because these might call functions from other libraries that are thread unsafe, and could conflict with any other thread that's already using these other libraries. so like… call it first, call it alone, and then go live your life. 💅

no cap, do NOT be out here calling these from multiple threads. it's giving chaos and we don't do chaos in library init. 🙈

---

🦋 JNI 🦋

accessing the Connectivity Manager through Java, step by step:

register the ares_library_android_init.

static JNINativeMethod funcs[] = {
{ "initialize_native",     "(Landroid/net/ConnectivityManager;)I",
  (void *)&ares_library_init_android}
};

JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
{
  JNIEnv *env = NULL;
  jclass  cls = NULL;
  jint    res;

  if ((*vm)->GetEnv(vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK)
    return -1;

  cls = (*env)->FindClass(env, JNIT_CLASS);
  if (cls == NULL)
    return -1;

  res = (*env)->RegisterNatives(env, cls, funcs, sizeof(funcs)/sizeof(funcs[0]));
  if (res != 0)
    return -1;

  ares_library_init_jvm(vm);
  return JNI_VERSION_1_6;
}

calling the registered function from Java:

public class MyObject {
  static {
    System.loadLibrary("cares");
  }

  private static native boolean initialize_native(ConnectivityManager
    connectivity_manager);

  public static boolean initialize(Context context) {
    initialize_native((ConnectivityManager)context.getSystemService(Context.CONNECTIVITY_SERVICE));
  }
}

initializing the Connectivity Manager in JNI directly using an Android Context. it's assumed the JVM has already been registered through JNI_OnLoad.

void initialize(jobject android_context)
{
  jclass obj_cls = jni_get_class(env, "android/content/Context");
  jmethodID obj_mid = jni_get_method_id(env, obj_cls, "getSystemService", "(Ljava/lang/String;)Ljava/lang/Object;");
  jfieldID fid = (*env)->GetStaticFieldID(env, obj_cls, "CONNECTIVITY_SERVICE", "Ljava/lang/String;");
  jstring str = (*env)->GetStaticObjectField(env, obj_cls, fid);
  connectivity_manager = (*env)->CallObjectMethod(env, android_context, obj_mid, str);
  if (connectivity_manager == NULL)
    return;
  ares_library_init_android(connectivity_manager);
}

---

🌟 AVAILABILITY 🌟

this function was first introduced in c-ares version 1.15.0. so if your c-ares is older than that… yeah, she's not showing up to the party. 😭

---

🧚 SEE ALSO 🧚

• ares_library_init(3)
• ares_library_cleanup(3)

---

and that's the whole page, bestie!! 💜 this was the Library Functions Manual entry for ARES_LIBRA...NIT_ANDROID(3), last touched 13 Sept 2017. slay, go initialize responsibly ✨🎀💖