android integration docs update

10 years ago · fdf78b8ea7
6 changed files with 31 additions and 344 deletions
--- a/docs/android_zt_sdk.md
+++ b/docs/android_zt_sdk.md
@ -14,13 +14,13 @@ If you want to skip the following steps and just take a look at the project, go
 - Specify the target architectures you want to build in [Application.mk](android/java/jni/Application.mk). By default it will build `arm64-v8a`, `armeabi`, `armeabi-v7a`, `mips`, `mips64`, `x86`, and `x86_64`.
 - Specify your SDK/NDK path in `android_jni_lib/proj/local.properties`. For example:
 ```
- sdk.dir=/Users/Joseph/Library/Android/sdk
+ sdk.dir=/Users/Name/Library/Android/sdk
- ndk.dir=/Users/Joseph/Library/Android/ndk-r10e
+ ndk.dir=/Users/Name/Library/Android/ndk-r10e
 ```
 **Step 2: Build Shared Library**
 - `make android_jni_lib`
- - The resultant `build/android_jni_lib_YOUR_ARCH/libZeroTierOneJNI.so` is what you want to import into your own project to provide the API to your app. Select your architecture and copy the shared library into your project's JNI directory, possibly `/src/main/jniLibs/YOUR_ARCH/`. Selecting only the architectures you need will *significantly* reduce overall build time.
+ - The resultant `build/android_jni_lib_YOUR_ARCH/libZeroTierOneJNI.so` is what you want to import into your own project to provide the API to your app. Select your architecture and copy the shared library `libZeroTierOneJNI.so` into your project's JNI directory, possibly `/src/main/jniLibs/YOUR_ARCH/libZeroTierOneJNI.so`. Selecting only the architectures you need will *significantly* reduce overall build time.
 **Step 3: App permissions**
@ -32,46 +32,28 @@ If you want to skip the following steps and just take a look at the project, go
 ```
 **Step 4: App Code Modifications**
- - Create new package called `ZeroTierSDK` in your project and add a new file called `ZeroTierSDK.java` containing:
+ - In your project, create a new package called `ZeroTier` and class file within called `ZTSDK.java` and copy contents from `src/SDK_JavaWrapper.java`
-
+ 
 ```
 package ZeroTier;
 public class ZeroTierSDK {
    public native void startOneService(String homeDir);
    public native void joinNetwork(String nwid);
    public native void leaveNetwork(String nwid);
    public native boolean isRunning();
    static { System.loadLibrary("ZeroTierOneJNI"); } // Loads JNI code
 }
 ```
 - Start the service
 ```
-final SDK zt = new SDK();
+String nwid = "8056c2e21c000001";
 // Set up service
 final ZTSDK zt = new ZTSDK();
 final String homeDir = getApplicationContext().getFilesDir() + "/zerotier";
 new Thread(new Runnable() {
    public void run() {
        // Calls to JNI code
-        zt.zt_start_service(homeDir);
+        zt.start_service(homeDir);
    }
 }).start();
 while(!zt.running()) { }
 ```
- - Join network and perform network call
+ - Join network and start doing network stuff!
 ```
-while(!zt.zt_running()) { }
+zt.join_network("XXXXXXXXXXXXXXXX");
-zt.zt_join_network("XXXXXXXXXXXXXXXX");
+int sock = zt.socket(zt.AF_INET, zt.SOCK_STREAM, 0);
-
+int err = zt.connect(sock, "10.9.9.203", 8080);
-// Create ZeroTier socket
+```
 int sock = zt.zt_socket(zt.AF_INET, zt.SOCK_STREAM, 0);
 // Connect to remote host
 int err = zt.zt_connect(sock, "10.9.9.203", 8080);
 ```
 ***
 *Note for the curious on JNI naming conventions: In order to reference a symbol in the JNI library you need to structure the package and class in your Android Studio project in a very particular way. For example, in the ZeroTierSDK we define a function called `Java_ZeroTier_SDK_zt_1start_1service`, the name can be broken down as follows: `Java_PACKAGENAME_CLASSNAME_zt_1start_1service`, so as we've defined it, you must create a package called `ZeroTier` and add a class called `SDK`.*
--- a/docs/integrations.md
+++ b/docs/integrations.md
@ -18,7 +18,6 @@ For more support on these integrations, or if you'd like help creating a new int
 - `SDK_DEBUG_LOGFILE=1` - Used in conjunction with `SDK_DEBUG`, this will write all SDK debug chatter to a log file. To use this, set `make SDK_DEBUG_LOGFILE=1` then `export ZT_SDK_LOGFILE=debug.log`. 
 - `SDK_LWIP_DEBUG=1` - Turns on debug output for the lwIP library.
 - `SDK_BUNDLED=1` - Builds the SDK as a single bundled target including a the RPC mechanism, the lwIP library, and the ZeroTier service.
 - `SDK_SOCKS_PROXY=1` - Enables the SOCK5 Proxy. This flag is enabled by default on must builds, especially mobile.
 ***
 ## Current Integrations
--- a/integrations/README.md
+++ b/integrations/README.md
@ -18,7 +18,6 @@ For more support on these integrations, or if you'd like help creating a new int
 - `SDK_DEBUG_LOGFILE=1` - Used in conjunction with `SDK_DEBUG`, this will write all SDK debug chatter to a log file. To use this, set `make SDK_DEBUG_LOGFILE=1` then `export ZT_SDK_LOGFILE=debug.log`. 
 - `SDK_LWIP_DEBUG=1` - Turns on debug output for the lwIP library.
 - `SDK_BUNDLED=1` - Builds the SDK as a single bundled target including a the RPC mechanism, the lwIP library, and the ZeroTier service.
 - `SDK_SOCKS_PROXY=1` - Enables the SOCK5 Proxy. This flag is enabled by default on must builds, especially mobile.
 ***
 ## Current Integrations
--- a/integrations/android/README.md
+++ b/integrations/android/README.md
@ -14,13 +14,13 @@ If you want to skip the following steps and just take a look at the project, go
 - Specify the target architectures you want to build in [Application.mk](android/java/jni/Application.mk). By default it will build `arm64-v8a`, `armeabi`, `armeabi-v7a`, `mips`, `mips64`, `x86`, and `x86_64`.
 - Specify your SDK/NDK path in `android_jni_lib/proj/local.properties`. For example:
 ```
- sdk.dir=/Users/Joseph/Library/Android/sdk
+ sdk.dir=/Users/Name/Library/Android/sdk
- ndk.dir=/Users/Joseph/Library/Android/ndk-r10e
+ ndk.dir=/Users/Name/Library/Android/ndk-r10e
 ```
 **Step 2: Build Shared Library**
 - `make android_jni_lib`
- - The resultant `build/android_jni_lib_YOUR_ARCH/libZeroTierOneJNI.so` is what you want to import into your own project to provide the API to your app. Select your architecture and copy the shared library into your project's JNI directory, possibly `/src/main/jniLibs/YOUR_ARCH/`. Selecting only the architectures you need will *significantly* reduce overall build time.
+ - The resultant `build/android_jni_lib_YOUR_ARCH/libZeroTierOneJNI.so` is what you want to import into your own project to provide the API to your app. Select your architecture and copy the shared library `libZeroTierOneJNI.so` into your project's JNI directory, possibly `/src/main/jniLibs/YOUR_ARCH/libZeroTierOneJNI.so`. Selecting only the architectures you need will *significantly* reduce overall build time.
 **Step 3: App permissions**
@ -32,46 +32,28 @@ If you want to skip the following steps and just take a look at the project, go
 ```
 **Step 4: App Code Modifications**
- - Create new package called `ZeroTierSDK` in your project and add a new file called `ZeroTierSDK.java` containing:
+ - In your project, create a new package called `ZeroTier` and class file within called `ZTSDK.java` and copy contents from `src/SDK_JavaWrapper.java`
-
+ 
 ```
 package ZeroTier;
 public class ZeroTierSDK {
    public native void startOneService(String homeDir);
    public native void joinNetwork(String nwid);
    public native void leaveNetwork(String nwid);
    public native boolean isRunning();
    static { System.loadLibrary("ZeroTierOneJNI"); } // Loads JNI code
 }
 ```
 - Start the service
 ```
-final SDK zt = new SDK();
+String nwid = "8056c2e21c000001";
 // Set up service
 final ZTSDK zt = new ZTSDK();
 final String homeDir = getApplicationContext().getFilesDir() + "/zerotier";
 new Thread(new Runnable() {
    public void run() {
        // Calls to JNI code
-        zt.zt_start_service(homeDir);
+        zt.start_service(homeDir);
    }
 }).start();
 while(!zt.running()) { }
 ```
- - Join network and perform network call
+ - Join network and start doing network stuff!
 ```
-while(!zt.zt_running()) { }
+zt.join_network("XXXXXXXXXXXXXXXX");
-zt.zt_join_network("XXXXXXXXXXXXXXXX");
+int sock = zt.socket(zt.AF_INET, zt.SOCK_STREAM, 0);
-
+int err = zt.connect(sock, "10.9.9.203", 8080);
-// Create ZeroTier socket
+```
 int sock = zt.zt_socket(zt.AF_INET, zt.SOCK_STREAM, 0);
 // Connect to remote host
 int err = zt.zt_connect(sock, "10.9.9.203", 8080);
 ```
 ***
 *Note for the curious on JNI naming conventions: In order to reference a symbol in the JNI library you need to structure the package and class in your Android Studio project in a very particular way. For example, in the ZeroTierSDK we define a function called `Java_ZeroTier_SDK_zt_1start_1service`, the name can be broken down as follows: `Java_PACKAGENAME_CLASSNAME_zt_1start_1service`, so as we've defined it, you must create a package called `ZeroTier` and add a class called `SDK`.*
--- a/src/SDK_JNI_Java_Wapper.java
+++ b/src/SDK_JNI_Java_Wapper.java
@ -1,275 +0,0 @@
 /*
 * ZeroTier One - Network Virtualization Everywhere
 * Copyright (C) 2011-2015  ZeroTier, Inc.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * --
 *
 * ZeroTier may be used and distributed under the terms of the GPLv3, which
 * are available at: http://www.gnu.org/licenses/gpl-3.0.html
 *
 * If you would like to embed ZeroTier into a commercial application or
 * redistribute it in a modified binary form, please contact ZeroTier Networks
 * LLC. Start here: http://www.zerotier.com/
 */
 package ZeroTier;
 import java.io.FileDescriptor;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.util.ArrayList;
 import java.util.zip.ZipError;
 import android.os.ParcelFileDescriptor;
 import android.util.Log;
 import android.util.Pair;
 public class SDK {
    // Socket families
    public static int AF_UNIX = 1;
    public static int AF_INET = 2;
    // Socket types
    public static int SOCK_STREAM = 1;
    public static int SOCK_DGRAM = 2;
    // fcntl flags
    public static int O_APPEND = 1024;
    public static int O_NONBLOCK = 2048;
    public static int O_ASYNC = 8192;
    public static int O_DIRECT = 65536;
    public static int O_NOATIME = 262144;
    // fcntl cmds
    public static int F_GETFL = 3;
    public static int F_SETFL = 4;
    // Loads JNI code
    static { System.loadLibrary("ZeroTierOneJNI"); }
    // ZeroTier service controls
    public native void zt_start_service(String homeDir);
    public void start_service(String homeDir) {
        zt_start_service(homeDir);
    }
    public native void zt_join_network(String nwid);
    public void join_network(String nwid) {
        zt_join_network(nwid);
    }
    public native void zt_leave_network(String nwid);
    public void leave_network(String nwid) {
        zt_leave_network(nwid);
    }
    // ------------------------------------------------------------------------------
    // ------------------------------- get_addresses() ------------------------------
    // ------------------------------------------------------------------------------
    public native ArrayList<String> zt_get_addresses(String nwid);
    public ArrayList<String> get_addresses(String nwid) {
        int err = -1;
        ArrayList<String> addresses;
        while (err < 0) {
            try {
                Thread.sleep(100);
            } catch (InterruptedException e) {
            }
            addresses = zt_get_addresses(nwid);
            if (addresses.size() > 0) {
                return addresses;
            }
        }
        return null;
    }
    public native int zt_get_proxy_port(String nwid);
    public int get_proxy_port(String nwid) {
        return zt_get_proxy_port(nwid);
    }
    public native boolean zt_running();
    public boolean running() {
        return zt_running();
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- socket() ---------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_socket(int family, int type, int protocol);
    public int socket(int family, int type, int protocol) {
        return zt_socket(family, type, protocol);
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- connect() --------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_connect(int fd, String addr, int port);
    public int connect(int sock, ZTAddress zaddr, String nwid) {
        return connect(sock, zaddr.Address(), zaddr.Port(), nwid);
    }
    public int connect(int sock, String addr, int port, String nwid)
    {
        int err = -1;
        ArrayList<String> addresses;
        while (err < 0) {
            try {
                Thread.sleep(100);
            } catch (InterruptedException e) {
            }
            addresses = zt_get_addresses(nwid);
            if (addresses.size() > 0) {
                if(!addresses.get(0).startsWith("-1.-1.-1.-1/-1")) {
                    err = zt_connect(sock, addr, port);
                }
            }
        }
        return err;
    }
    // ------------------------------------------------------------------------------
    // ------------------------------------ bind() ----------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_bind(int fd, String addr, int port);
    public int bind(int sock, ZTAddress zaddr, String nwid) {
        return bind(sock, zaddr.Address(), zaddr.Port(), nwid);
    }
    public int bind(int sock, String addr, int port, String nwid) {
        int err = -1;
        ArrayList<String> addresses;
        while (err < 0) {
            try {
                Thread.sleep(100);
            } catch (InterruptedException e) {
            }
            addresses = zt_get_addresses(nwid);
            if (addresses.size() > 0) {
                if(!addresses.get(0).startsWith("-1.-1.-1.-1/-1")) {
                    err = zt_bind(sock, addr, port);
                }
            }
        }
        return err;
    }
    // ------------------------------------------------------------------------------
    // ---------------------------------- accept4() ---------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_accept4(int fd, String addr, int port);
    public int accept4(int fd, String addr, int port) {
        return zt_accept4(fd,addr,port);
    }
    // ------------------------------------------------------------------------------
    // ---------------------------------- accept() ----------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_accept(int fd, ZeroTier.ZTAddress addr);
    public int accept(int fd, ZeroTier.ZTAddress addr) {
        return zt_accept(fd, addr);
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- listen() ---------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_listen(int fd, int backlog);
    public int listen(int fd, int backlog) {
        return zt_listen(fd,backlog);
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- close() ----------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_close(int fd);
    public int close(int fd) {
        return close(fd);
    }
    // ------------------------------------------------------------------------------
    // ------------------------------------ read() ----------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_read(int fd, byte[] buf, int len);
    public int read(int fd, byte[] buf, int len) {
        return zt_read(fd, buf, len);
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- write() ----------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_write(int fd, byte[] buf, int len);
    public int write(int fd, byte[] buf, int len) {
        return zt_write(fd, buf, len);
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- sendto() ---------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_sendto(int fd, byte[] buf, int len, int flags, ZeroTier.ZTAddress addr);
    public int sendto(int fd, byte[] buf, int len, int flags, ZeroTier.ZTAddress addr){
        return zt_sendto(fd,buf,len,flags,addr);
    }
    // ------------------------------------------------------------------------------
    // ----------------------------------- send() -----------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_send(int fd, byte[] buf, int len, int flags);
    public int send(int fd, byte[] buf, int len, int flags) {
        return zt_send(fd, buf, len, flags);
    }
    // ------------------------------------------------------------------------------
    // ---------------------------------- recvfrom() --------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_recvfrom(int fd, byte[] buf, int len, int flags, ZeroTier.ZTAddress addr);
    public int recvfrom(int fd, byte[] buf, int len, int flags, ZeroTier.ZTAddress addr){
        return zt_recvfrom(fd,buf,len,flags,addr);
    }
    // ------------------------------------------------------------------------------
    // ---------------------------------- recvfrom() --------------------------------
    // ------------------------------------------------------------------------------
    public native int zt_fcntl(int sock, int cmd, int flag);
    public int fcntl(int sock, int cmd, int flag) {
        return  zt_fcntl(sock, F_SETFL, O_NONBLOCK);
    }
    //public static native int zt_getsockopt(int fd, int type, int protocol);
    //public static native int zt_setsockopt(int fd, int type, int protocol);
    //public static native int zt_getsockname(int fd, int type, int protocol);
 }
--- a/src/SDK_JavaWrapper.java
+++ b/src/SDK_JavaWrapper.java
@ -36,7 +36,7 @@ import android.os.ParcelFileDescriptor;
 import android.util.Log;
 import android.util.Pair;
-public class SDK {
+public class ZTSDK {
    // Socket families
    public static int AF_UNIX = 1;