quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

ares_library_init_android.3 (4549B)

      1 .\"
      2 .\" Copyright (C) 2017 by John Schember
      3 .\" SPDX-License-Identifier: MIT
      4 .\"
      5 .TH ARES_LIBRARY_INIT_ANDROID 3 "13 Sept 2017"
      6 .SH NAME
      7 ares_library_init_android \- c-ares library Android initialization
      8 .SH SYNOPSIS
      9 .nf
     10 #include <ares.h>
     11 
     12 int ares_library_init_android(jobject \fIconnectivity_manager\fP)
     13 
     14 int ares_library_android_initialized();
     15 
     16 void ares_library_init_jvm(JavaVM *\fIjvm\fP)
     17 
     18 .fi
     19 .SH DESCRIPTION
     20 The \fIares_library_init_android(3)\fP function performs initializations
     21 internally required by the c-ares library when used on Android. This can take
     22 place anytime after \fIares_library_init(3)\fP. It must take place after
     23 \fIares_library_init_jvm\fP. ares_library_init_android must be called before
     24 DNS resolution will work on Android 8 (Oreo) or newer when targetSdkVersion is
     25 set to 26+.
     26 
     27 As of Android 8 (API level 26) getting DNS server information has
     28 becomei more restrictive and can only be accessed using the
     29 Connectivity Manager. It is necessary to pass the connectivity
     30 manager to c-ares via JNI. Also, the ACCESS_NETWORK_STATE permission
     31 must be present in the Android application.
     32 
     33 Android older than 8 do not need to to be initialized as they
     34 are less restrictive. However, this is a run time not compile time
     35 limitation. Proper Android initialization should take place regardless
     36 of the targeted Android version.
     37 
     38 Deinitialization will take place though \fIares_library_cleanup(3)\fP.
     39 
     40 The \fBares_library_init_jvm\fP function allows the caller to register the JVM
     41 with c-ares.  It's meant to be called during JNI_OnLoad because you're
     42 guaranteed to have the JVM in that function. The JVM is required in order to
     43 use the Connectivity Manager registered using
     44 \fIares_library_init_android(3)\fP. This must be call before
     45 \fIares_library_init_android(3)\fP.
     46 
     47 The \fBares_library_android_initialized\fP function can be used to check
     48 whether c-ares has been initialized for use with Android.
     49 .SH RETURN VALUES
     50 ARES_SUCCESS will be returned on success otherwise an error code will be
     51 returned.
     52 .SH THREAD SAFETY
     53 .B These init functions are not thread safe.
     54 You have to call it once the program has started, but this call must be done
     55 before the program starts any other thread. This is required to avoid
     56 potential race conditions in library initialization, and also due to the fact
     57 these might call functions from other libraries that
     58 are thread unsafe, and could conflict with any other thread that is already
     59 using these other libraries.
     60 .SH JNI
     61 Accessing the Connectivity Manager though Java:
     62 
     63 Register the \fIares_library_android_init\fP.
     64 .nf
     65   static JNINativeMethod funcs[] = {
     66   { "initialize_native",     "(Landroid/net/ConnectivityManager;)I",
     67     (void *)&ares_library_init_android}
     68   };
     69 
     70   JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
     71   {
     72     JNIEnv *env = NULL;
     73     jclass  cls = NULL;
     74     jint    res;
     75   
     76     if ((*vm)->GetEnv(vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK)
     77       return -1;
     78   
     79     cls = (*env)->FindClass(env, JNIT_CLASS);
     80     if (cls == NULL)
     81       return -1;
     82   
     83     res = (*env)->RegisterNatives(env, cls, funcs, sizeof(funcs)/sizeof(funcs[0]));
     84     if (res != 0)
     85       return -1;
     86   
     87     ares_library_init_jvm(vm);
     88     return JNI_VERSION_1_6;
     89   }
     90 .fi
     91 Calling the registered function from Java:
     92 .nf
     93   public class MyObject {
     94     static {
     95       System.loadLibrary("cares");
     96     }
     97   
     98     private static native boolean initialize_native(ConnectivityManager
     99       connectivity_manager);
    100   
    101     public static boolean initialize(Context context) {
    102       initialize_native((ConnectivityManager)context.getSystemService(Context.CONNECTIVITY_SERVICE));
    103     }
    104   }
    105 .fi
    106 Initializing the Connectivity Manager in JNI directly using an Android
    107 Context. It is assumed the JVM has already been registered through
    108 \fIJNI_OnLoad\fP.
    109 .nf
    110   void initialize(jobject android_context)
    111   {
    112     jclass obj_cls = jni_get_class(env, "android/content/Context");
    113     jmethodID obj_mid = jni_get_method_id(env, obj_cls, "getSystemService", "(Ljava/lang/String;)Ljava/lang/Object;");
    114     jfieldID fid = (*env)->GetStaticFieldID(env, obj_cls, "CONNECTIVITY_SERVICE", "Ljava/lang/String;");
    115     jstring str = (*env)->GetStaticObjectField(env, obj_cls, fid);
    116     connectivity_manager = (*env)->CallObjectMethod(env, android_context, obj_mid, str);
    117     if (connectivity_manager == NULL)
    118       return;
    119     ares_library_init_android(connectivity_manager);
    120   }
    121 .fi
    122 .SH AVAILABILITY
    123 This function was first introduced in c-ares version 1.15.0.
    124 .SH SEE ALSO
    125 .BR ares_library_init (3),
    126 .BR ares_library_cleanup (3),
    127