diff options
23 files changed, 624 insertions, 19 deletions
@@ -48,3 +48,4 @@ java/obj/ java/libs/ java/bin/ java/classes/ +java/doc/ diff --git a/java/build.xml b/java/build.xml index af05cd00..c81f48de 100644 --- a/java/build.xml +++ b/java/build.xml @@ -25,6 +25,13 @@ <jar destfile="bin/ZeroTierOneSDK.jar" basedir="classes"/> </target> + <target name="docs"> + <echo message="Generating Javadocs"/> + <mkdir dir="doc/"/> + <javadoc sourcepath="src/" + destdir="doc/"/> + </target> + <!-- <target name="android" depends="build"> <echo message="OS is Android, installing..."/> <copy file="libs/armeabi/libZeroTierOneJNI.so" diff --git a/java/jni/ZT1_jniutils.cpp b/java/jni/ZT1_jniutils.cpp index 8d1a25c4..af7a58bc 100644 --- a/java/jni/ZT1_jniutils.cpp +++ b/java/jni/ZT1_jniutils.cpp @@ -785,7 +785,7 @@ jobject newNetworkConfig(JNIEnv *env, const ZT1_VirtualNetworkConfig &vnetConfig if(portErrorField == NULL) { - portErrorField == env->GetFieldID(vnetConfigClass, "portError", "Z"); + portErrorField == env->GetFieldID(vnetConfigClass, "portError", "I"); if(portErrorField == NULL) { return NULL; @@ -855,7 +855,7 @@ jobject newNetworkConfig(JNIEnv *env, const ZT1_VirtualNetworkConfig &vnetConfig env->SetBooleanField(vnetConfigObj, dhcpField, vnetConfig.dhcp); env->SetBooleanField(vnetConfigObj, bridgeField, vnetConfig.bridge); env->SetBooleanField(vnetConfigObj, broadcastEnabledField, vnetConfig.broadcastEnabled); - env->SetBooleanField(vnetConfigObj, portErrorField, vnetConfig.portError); + env->SetIntField(vnetConfigObj, portErrorField, vnetConfig.portError); jobject mcastSubsArrayObj = newArrayList(env); diff --git a/java/jni/com_zerotierone_sdk_Node.cpp b/java/jni/com_zerotierone_sdk_Node.cpp index fdbe0368..fef9b4d6 100644 --- a/java/jni/com_zerotierone_sdk_Node.cpp +++ b/java/jni/com_zerotierone_sdk_Node.cpp @@ -443,7 +443,7 @@ namespace { if(ref->packetSenderCallbackMethod == NULL) { ref->packetSenderCallbackMethod = env->GetMethodID(ref->packetSenderClass, - "onSendPacketRequested", "(Ljava/lang/String;I[B)I"); + "onSendPacketRequested", "(Ljava/net/InetAddress;I[B)I"); if(ref->packetSenderCallbackMethod == NULL) { return -2; diff --git a/java/src/com/zerotierone/sdk/DataStoreGetListener.java b/java/src/com/zerotierone/sdk/DataStoreGetListener.java index 703b153b..eaf35f18 100644 --- a/java/src/com/zerotierone/sdk/DataStoreGetListener.java +++ b/java/src/com/zerotierone/sdk/DataStoreGetListener.java @@ -29,6 +29,29 @@ package com.zerotierone.sdk; import java.nio.ByteBuffer; public interface DataStoreGetListener { + + /** + * Function to get an object from the data store + * + * <p>Object names can contain forward slash (/) path separators. They will + * never contain .. or backslash (\), so this is safe to map as a Unix-style + * path if the underlying storage permits. For security reasons we recommend + * returning errors if .. or \ are used.</p> + * + * <p>The function must return the actual number of bytes read. If the object + * doesn't exist, it should return -1. -2 should be returned on other errors + * such as errors accessing underlying storage.</p> + * + * <p>If the read doesn't fit in the buffer, the max number of bytes should be + * read. The caller may call the function multiple times to read the whole + * object.</p> + * + * @param name Name of the object in the data store + * @param out_buffer buffer to put the object in + * @param bufferIndex index in the object to start reading + * @param out_objectSize long[1] to be set to the actual size of the object if it exists. + * @return the actual number of bytes read. + */ public long onDataStoreGet( String name, byte[] out_buffer, diff --git a/java/src/com/zerotierone/sdk/DataStorePutListener.java b/java/src/com/zerotierone/sdk/DataStorePutListener.java index bc884667..26ab1928 100644 --- a/java/src/com/zerotierone/sdk/DataStorePutListener.java +++ b/java/src/com/zerotierone/sdk/DataStorePutListener.java @@ -29,11 +29,33 @@ package com.zerotierone.sdk; import java.nio.ByteBuffer; public interface DataStorePutListener { + + /** + * Function to store an object in the data store + * + * <p>If secure is true, the file should be set readable and writable only + * to the user running ZeroTier One. What this means is platform-specific.</p> + * + * <p>Name semantics are the same as {@link DataStoreGetListener}. This must return + * zero on success. You can return any OS-specific error code on failure, as these + * may be visible in logs or error messages and might aid in debugging.</p> + * + * @param name Object name + * @param buffer data to store + * @param secure set to user read/write only. + * @return 0 on success. + */ public int onDataStorePut( String name, byte[] buffer, boolean secure); + /** + * Function to delete an object from the data store + * + * @param name Object name + * @return 0 on success. + */ public int onDelete( String name); } diff --git a/java/src/com/zerotierone/sdk/Event.java b/java/src/com/zerotierone/sdk/Event.java index c5558676..382fbf48 100644 --- a/java/src/com/zerotierone/sdk/Event.java +++ b/java/src/com/zerotierone/sdk/Event.java @@ -28,11 +28,89 @@ package com.zerotierone.sdk; public enum Event { + /** + * Node has been initialized + * + * This is the first event generated, and is always sent. It may occur + * before Node's constructor returns. + */ EVENT_UP, + + /** + * Node is offline -- network does not seem to be reachable by any available strategy + */ EVENT_OFFLINE, + + /** + * Node is shutting down + * + * <p>This is generated within Node's destructor when it is being shut down. + * It's done for convenience, since cleaning up other state in the event + * handler may appear more idiomatic.</p> + */ EVENT_DOWN, + + /** + * Your identity has collided with another node's ZeroTier address + * + * <p>This happens if two different public keys both hash (via the algorithm + * in Identity::generate()) to the same 40-bit ZeroTier address.</p> + * + * <p>This is something you should "never" see, where "never" is defined as + * once per 2^39 new node initializations / identity creations. If you do + * see it, you're going to see it very soon after a node is first + * initialized.</p> + * + * <p>This is reported as an event rather than a return code since it's + * detected asynchronously via error messages from authoritative nodes.</p> + * + * <p>If this occurs, you must shut down and delete the node, delete the + * identity.secret record/file from the data store, and restart to generate + * a new identity. If you don't do this, you will not be able to communicate + * with other nodes.</p> + * + * <p>We'd automate this process, but we don't think silently deleting + * private keys or changing our address without telling the calling code + * is good form. It violates the principle of least surprise.</p> + * + * <p>You can technically get away with not handling this, but we recommend + * doing so in a mature reliable application. Besides, handling this + * condition is a good way to make sure it never arises. It's like how + * umbrellas prevent rain and smoke detectors prevent fires. They do, right?</p> + */ EVENT_FATAL_ERROR_IDENTITY_COLLISION, + + /** + * A more recent version was observed on the network + * + * <p>Right now this is only triggered if a hub or supernode reports a + * more recent version, and only once. It can be used to trigger a + * software update check.</p> + * + * <p>Meta-data: {@link Version}, more recent version number</p> + */ + EVENT_SAW_MORE_RECENT_VERSION, + + /** + * A packet failed authentication + * + * <p>Meta-data: {@link InetAddress} containing origin address of packet</p> + */ EVENT_AUTHENTICATION_FAILURE, + + /** + * A received packet was not valid + * + * <p>Meta-data: {@link InetAddress} containing origin address of packet</p> + */ EVENT_INVALID_PACKET, + + /** + * Trace (debugging) message + * + * <p>These events are only generated if this is a TRACE-enabled build.</p> + * + * <p>Meta-data: {@link String}, TRACE message</p> + */ EVENT_TRACE }
\ No newline at end of file diff --git a/java/src/com/zerotierone/sdk/EventListener.java b/java/src/com/zerotierone/sdk/EventListener.java index 63030dfd..dedd271a 100644 --- a/java/src/com/zerotierone/sdk/EventListener.java +++ b/java/src/com/zerotierone/sdk/EventListener.java @@ -30,12 +30,38 @@ package com.zerotierone.sdk; import java.net.InetAddress; import java.lang.String; +/** + * Interface to handle callbacks for ZeroTier One events. + */ public interface EventListener { + /** + * Callback for events with no other associated metadata + * + * @param event {@link Event} enum + */ public void onEvent(Event event); + /** + * Callback for network error events: {@link Event.EVENT_AUTHENTICATION_FAILUER}, {link Event.EVENT_INVALID_PACKET} + * + * @param event {@link Event} enum + * @param source {@link InetAddress} containing the origin address of the packet + */ public void onNetworkError(Event event, InetAddress source); + /** + * Callback when the node detects that it's out of date. + * + * @param newVersion {@link Version} object with the latest version of ZeroTier One + */ public void onOutOfDate(Version newVersion); + /** + * Trace messages + * + * <p>These events are only generated if the underlying ZeroTierOne SDK is a TRACE-enabled build.</p> + * + * @param message the trace message + */ public void onTrace(String message); } diff --git a/java/src/com/zerotierone/sdk/MulticastGroup.java b/java/src/com/zerotierone/sdk/MulticastGroup.java index 89ba206f..aa75ab85 100644 --- a/java/src/com/zerotierone/sdk/MulticastGroup.java +++ b/java/src/com/zerotierone/sdk/MulticastGroup.java @@ -27,9 +27,23 @@ package com.zerotierone.sdk; -public class MulticastGroup { +public final class MulticastGroup { private MulticastGroup() {} private long mac; private long adi; + + /** + * MAC address (least significant 48 bits) + */ + public final long getMacAddress() { + return mac; + } + + /** + * Additional distinguishing information (usually zero) + */ + public final long getAdi() { + return adi; + } } diff --git a/java/src/com/zerotierone/sdk/Node.java b/java/src/com/zerotierone/sdk/Node.java index 649f84a8..318f0701 100644 --- a/java/src/com/zerotierone/sdk/Node.java +++ b/java/src/com/zerotierone/sdk/Node.java @@ -32,6 +32,9 @@ import java.lang.Long; import java.net.InetAddress; import java.util.ArrayList; +/** + * A ZeroTier One node + */ public class Node { static { System.loadLibrary("ZeroTierOneJNI"); @@ -54,6 +57,20 @@ public class Node { private final VirtualNetworkFrameListener frameListener; private final VirtualNetworkConfigListener configListener; + /** + * Create a new ZeroTier One node + * + * <p>Note that this can take a few seconds the first time it's called, as it + * will generate an identity.</p> + * + * @param now Current clock in milliseconds + * @param getListener User written instance of the {@link DataStoreGetListener} interface called to get objects from persistent storage. This instance must be unique per Node object. + * @param putListener User written intstance of the {@link DataStorePutListener} interface called to put objects in persistent storage. This instance must be unique per Node object. + * @param sender + * @param eventListener User written instance of the {@link EventListener} interface to receive status updates and non-fatal error notices. This instance must be unique per Node object. + * @param frameListener + * @param configListener User written instance of the {@link VirtualNetworkConfigListener} interface to be called when virtual LANs are created, deleted, or their config parameters change. This instance must be unique per Node object. + */ public Node(long now, DataStoreGetListener getListener, DataStorePutListener putListener, @@ -78,6 +95,11 @@ public class Node { } } + /** + * Close this Node. + * + * <p>The Node object can no longer be used once this method is called.</p> + */ public void close() { if(nodeId != -1) { node_delete(nodeId); @@ -90,6 +112,19 @@ public class Node { close(); } + /** + * Process a frame from a virtual network port + * + * @param now Current clock in milliseconds + * @param nwid ZeroTier 64-bit virtual network ID + * @param sourceMac Source MAC address (least significant 48 bits) + * @param destMac Destination MAC address (least significant 48 bits) + * @param etherType 16-bit Ethernet frame type + * @param vlanId 10-bit VLAN ID or 0 if none + * @param frameData Frame payload data + * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks() + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode processVirtualNetworkFrame( long now, long nwid, @@ -104,6 +139,16 @@ public class Node { frameData, nextBackgroundTaskDeadline); } + /** + * Process a packet received from the physical wire + * + * @param now Current clock in milliseconds + * @param remoteAddress Origin of packet + * @param linkDesperation Link desperation metric for link or protocol over which packet arrived + * @param packetData Packet data + * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks() + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode processWirePacket( long now, InetAddress remoteAddress, @@ -115,24 +160,96 @@ public class Node { nextBackgroundTaskDeadline); } + /** + * Perform periodic background operations + * + * @param now Current clock in milliseconds + * @param nextBackgroundTaskDeadline Value/result: set to deadline for next call to processBackgroundTasks() + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode processBackgroundTasks(long now, long[] nextBackgroundTaskDeadline) { return processBackgroundTasks(nodeId, now, nextBackgroundTaskDeadline); } + /** + * Join a network + * + * <p>This may generate calls to the port config callback before it returns, + * or these may be deffered if a netconf is not available yet.</p> + * + * <p>If we are already a member of the network, nothing is done and OK is + * returned.</p> + * + * @param nwid 64-bit ZeroTier network ID + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode join(long nwid) { return join(nodeId, nwid); } + /** + * Leave a network + * + * <p>If a port has been configured for this network this will generate a call + * to the port config callback with a NULL second parameter to indicate that + * the port is now deleted.</p> + * + * @param nwid 64-bit network ID + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode leave(long nwid) { return leave(nodeId, nwid); } + /** + * Subscribe to an Ethernet multicast group + * + * <p>For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the + * broadcast address) but with an ADI equal to each IPv4 address in host + * byte order. This converts ARP from a non-scalable broadcast protocol to + * a scalable multicast protocol with perfect address specificity.</p> + * + * <p>If this is not done, ARP will not work reliably.</p> + * + * <p>Multiple calls to subscribe to the same multicast address will have no + * effect. It is perfectly safe to do this.</p> + * + * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p> + * + * @param nwid 64-bit network ID + * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits) + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode multicastSubscribe( long nwid, long multicastGroup) { return multicastSubscribe(nodeId, nwid, multicastGroup, 0); } + /** + * Subscribe to an Ethernet multicast group + * + * <p>ADI stands for additional distinguishing information. This defaults to zero + * and is rarely used. Right now its only use is to enable IPv4 ARP to scale, + * and this must be done.</p> + * + * <p>For IPv4 ARP, the implementation must subscribe to 0xffffffffffff (the + * broadcast address) but with an ADI equal to each IPv4 address in host + * byte order. This converts ARP from a non-scalable broadcast protocol to + * a scalable multicast protocol with perfect address specificity.</p> + * + * <p>If this is not done, ARP will not work reliably.</p> + * + * <p>Multiple calls to subscribe to the same multicast address will have no + * effect. It is perfectly safe to do this.</p> + * + * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p> + * + * @param nwid 64-bit network ID + * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits) + * @param multicastAdi Multicast ADI (least significant 32 bits only, default: 0) + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode multicastSubscribe( long nwid, long multicastGroup, @@ -140,12 +257,42 @@ public class Node { return multicastSubscribe(nodeId, nwid, multicastGroup, multicastAdi); } + + /** + * Unsubscribe from an Ethernet multicast group (or all groups) + * + * <p>If multicastGroup is zero (0), this will unsubscribe from all groups. If + * you are not subscribed to a group this has no effect.</p> + * + * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p> + * + * @param nwid 64-bit network ID + * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits) + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode multicastUnsubscribe( long nwid, long multicastGroup) { return multicastUnsubscribe(nodeId, nwid, multicastGroup, 0); } + /** + * Unsubscribe from an Ethernet multicast group (or all groups) + * + * <p>If multicastGroup is zero (0), this will unsubscribe from all groups. If + * you are not subscribed to a group this has no effect.</p> + * + * <p>This does not generate an update call to the {@link VirtualNetworkConfigListener#onNetworkConfigurationUpdated} method.</p> + * + * <p>ADI stands for additional distinguishing information. This defaults to zero + * and is rarely used. Right now its only use is to enable IPv4 ARP to scale, + * and this must be done.</p> + * + * @param nwid 64-bit network ID + * @param multicastGroup Ethernet multicast or broadcast MAC (least significant 48 bits) + * @param multicastAdi Multicast ADI (least significant 32 bits only, default: 0) + * @return OK (0) or error code if a fatal error condition has occurred + */ public ResultCode multicastUnsubscribe( long nwid, long multicastGroup, @@ -153,33 +300,64 @@ public class Node { return multicastUnsubscribe(nodeId, nwid, multicastGroup, multicastAdi); } + /** + * Get this node's 40-bit ZeroTier address + * + * @return ZeroTier address (least significant 40 bits of 64-bit int) + */ public long address() { return address(nodeId); } + /** + * Get the status of this node + * + * @return @{link NodeStatus} struct with the current node status. + */ public NodeStatus status() { return status(nodeId); } + /** + * Get a list of known peer nodes + * + * @return List of known peers or NULL on failure + */ public ArrayList<Peer> peers() { return peers(nodeId); } + /** + * Get the status of a virtual network + * + * @param nwid 64-bit network ID + * @return {@link VirtualNetworkConfig} or NULL if we are not a member of this network + */ public VirtualNetworkConfig networkConfig(long nwid) { return networkConfig(nodeId, nwid); } + /** + * Enumerate and get status of all networks + * + * @return List of networks or NULL on failure + */ public ArrayList<VirtualNetworkConfig> networks() { return networks(nodeId); } + /** + * Get ZeroTier One version + * + * @return {@link Version} object with ZeroTierOne version information. + */ public Version getVersion() { return version(); } - /** - * function declarations for JNI - */ + // + // function declarations for JNI + // private native ResultCode node_init(long now); private native void node_delete(long nodeId); diff --git a/java/src/com/zerotierone/sdk/NodeStatus.java b/java/src/com/zerotierone/sdk/NodeStatus.java index fdf5284e..163e3056 100644 --- a/java/src/com/zerotierone/sdk/NodeStatus.java +++ b/java/src/com/zerotierone/sdk/NodeStatus.java @@ -27,7 +27,7 @@ package com.zerotierone.sdk; -public class NodeStatus { +public final class NodeStatus { private long address; private String publicIdentity; private String secretIdentity; @@ -35,18 +35,34 @@ public class NodeStatus { private NodeStatus() {} + /** + * 40-bit ZeroTier address of this node + */ public final long getAddres() { return address; } + /** + * Public identity in string-serialized form (safe to send to others) + * + * <p>This identity will remain valid as long as the node exists.</p> + */ public final String getPublicIdentity() { return publicIdentity; } + /** + * Full identity including secret key in string-serialized form + * + * <p>This identity will remain valid as long as the node exists.</p> + */ public final String getSecretIdentity() { return secretIdentity; } + /** + * True if some kind of connectivity appears available + */ public final boolean isOnline() { return online; } diff --git a/java/src/com/zerotierone/sdk/PacketSender.java b/java/src/com/zerotierone/sdk/PacketSender.java index 572e1807..0c1cd83e 100644 --- a/java/src/com/zerotierone/sdk/PacketSender.java +++ b/java/src/com/zerotierone/sdk/PacketSender.java @@ -26,12 +26,24 @@ */ package com.zerotierone.sdk; -import java.nio.ByteBuffer; +import java.net.InetAddress; public interface PacketSender { + /** + * Function to send a ZeroTier packet out over the wire + * + * <p>The function must return zero on success and may return any error code + * on failure. Note that success does not (of course) guarantee packet + * delivery. It only means that the packet appears to have been sent.</p> + * + * @param addr {@link InetAddress} to send to + * @param linkDesperation + * @param packetData data to send + * @return 0 on success, any error code on failure. + */ public int onSendPacketRequested( - String addr, - int linkDesparation, + InetAddress addr, + int linkDesperation, byte[] packetData); } diff --git a/java/src/com/zerotierone/sdk/Peer.java b/java/src/com/zerotierone/sdk/Peer.java index cd2268b4..60b9ff4b 100644 --- a/java/src/com/zerotierone/sdk/Peer.java +++ b/java/src/com/zerotierone/sdk/Peer.java @@ -29,7 +29,10 @@ package com.zerotierone.sdk; import java.util.ArrayList; -public class Peer { +/** + * Peer status result + */ +public final class Peer { private long address; private long lastUnicastFrame; private long lastMulticastFrame; @@ -42,38 +45,65 @@ public class Peer { private Peer() {} + /** + * ZeroTier address (40 bits) + */ public final long address() { return address; } + /** + * Time we last received a unicast frame from this peer + */ public final long lastUnicastFrame() { return lastUnicastFrame; } + /** + * Time we last received a multicast rame from this peer + */ public final long lastMulticastFrame() { return lastMulticastFrame; } + /** + * Remote major version or -1 if not known + */ public final int versionMajor() { return versionMajor; } + /** + * Remote minor version or -1 if not known + */ public final int versionMinor() { return versionMinor; } + /** + * Remote revision or -1 if not known + */ public final int versionRev() { return versionRev; } + /** + * Last measured latency in milliseconds or zero if unknown + */ public final int latency() { return latency; } + /** + * What trust hierarchy role does this device have? + */ public final PeerRole role() { return role; } + /** + * Known network paths to peer + */ public final ArrayList<PhysicalPeerPath> paths() { return paths; } diff --git a/java/src/com/zerotierone/sdk/PeerPhysicalPath.java b/java/src/com/zerotierone/sdk/PeerPhysicalPath.java index d7b2fad1..17b0ff8b 100644 --- a/java/src/com/zerotierone/sdk/PeerPhysicalPath.java +++ b/java/src/com/zerotierone/sdk/PeerPhysicalPath.java @@ -29,7 +29,10 @@ package com.zerotierone.sdk; import java.net.InetAddress; -public class PeerPhysicalPath { +/** + * Physical network path to a peer + */ +public final class PeerPhysicalPath { private InetAddress address; private long lastSend; private long lastReceive; @@ -39,26 +42,44 @@ public class PeerPhysicalPath { private PeerPhysicalPath() {} + /** + * Address of endpoint + */ public final InetAddress address() { return address; } + /** + * Time of last send in milliseconds or 0 for never + */ public final long lastSend() { return lastSend; } + /** + * Time of last receive in milliseconds or 0 for never + */ public final long lastReceive() { return lastReceive; } + /** + * Is path fixed? (i.e. not learned, static) + */ public final boolean isFixed() { return fixed; } + /** + * Is path active? + */ public final boolean isActive() { return active; } + /** + * Is path preferred? + */ public final boolean isPreferred() { return preferred; } diff --git a/java/src/com/zerotierone/sdk/PeerRole.java b/java/src/com/zerotierone/sdk/PeerRole.java index 979b1a98..7f507f6d 100644 --- a/java/src/com/zerotierone/sdk/PeerRole.java +++ b/java/src/com/zerotierone/sdk/PeerRole.java @@ -28,7 +28,18 @@ package com.zerotierone.sdk; public enum PeerRole { + /** + * An ordinary node + */ PEER_ROLE_LEAF, + + /** + * Locally federated hub + */ PEER_ROLE_HUB, + + /** + * planetary supernode + */ PEER_ROLE_SUPERNODE }
\ No newline at end of file diff --git a/java/src/com/zerotierone/sdk/ResultCode.java b/java/src/com/zerotierone/sdk/ResultCode.java index 7597c0f2..bb73f68c 100644 --- a/java/src/com/zerotierone/sdk/ResultCode.java +++ b/java/src/com/zerotierone/sdk/ResultCode.java @@ -27,12 +27,41 @@ package com.zerotierone.sdk; +/** + * Function return code: OK (0) or error results + * + * <p>Use {@link ResultCode#isFatal) to check for a fatal error. If a fatal error + * occurs, the node should be considered to not be working correctly. These + * indicate serious problems like an inaccessible data store or a compile + * problem.</p> + */ public enum ResultCode { - + /** + * Operation completed normally + */ RESULT_OK(0), + + // Fatal errors (> 0, < 1000) + /** + * Ran out of memory + */ RESULT_FATAL_ERROR_OUT_OF_MEMORY(1), + + /** + * Data store is not writable or has failed + */ RESULT_FATAL_ERROR_DATA_STORE_FAILED(2), + + /** + * Internal error (e.g. unexpected exception indicating bug or build problem) + */ RESULT_FATAL_ERROR_INTERNAL(3), + + // non-fatal errors + + /** + * Network ID not valid + */ RESULT_ERROR_NETWORK_NOT_FOUND(1000); private final int id; diff --git a/java/src/com/zerotierone/sdk/Version.java b/java/src/com/zerotierone/sdk/Version.java index abdaab9e..14e9f152 100644 --- a/java/src/com/zerotierone/sdk/Version.java +++ b/java/src/com/zerotierone/sdk/Version.java @@ -27,8 +27,8 @@ package com.zerotierone.sdk; -public class Version { - public Version() {} +public final class Version { + private Version() {} public int major = 0; public int minor = 0; diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java b/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java index 5e06b55f..037fd802 100644 --- a/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java +++ b/java/src/com/zerotierone/sdk/VirtualNetworkConfig.java @@ -31,7 +31,7 @@ import java.lang.String; import java.util.ArrayList; import java.net.InetAddress; -public class VirtualNetworkConfig { +public final class VirtualNetworkConfig { public static final int MAX_MULTICAST_SUBSCRIPTIONS = 4096; public static final int ZT1_MAX_ZT_ASSIGNED_ADDRESSES = 16; @@ -44,7 +44,7 @@ public class VirtualNetworkConfig { private boolean dhcp; private boolean bridge; private boolean broadcastEnabled; - private boolean portError; + private int portError; private boolean enabled; private long netconfRevision; private ArrayList<MulticastGroup> multicastSubscriptions; @@ -54,57 +54,116 @@ public class VirtualNetworkConfig { } + /** + * 64-bit ZeroTier network ID + */ public final long networkId() { return nwid; } + + /** + * Ethernet MAC (40 bits) that should be assigned to port + */ public final long macAddress() { return mac; } + /** + * Network name (from network configuration master) + */ public final String name() { return name; } + /** + * Network configuration request status + */ public final VirtualNetworkStatus networkStatus() { return status; } + /** + * Network type + */ public final VirtualNetworkType networkType() { return type; } + /** + * Maximum interface MTU + */ public final int mtu() { return mtu; } + /** + * If the network this port belongs to indicates DHCP availability + * + * <p>This is a suggestion. The underlying implementation is free to ignore it + * for security or other reasons. This is simply a netconf parameter that + * means 'DHCP is available on this network.'</p> + */ public final boolean isDhcpAvailable() { return dhcp; } + /** + * If this port is allowed to bridge to other networks + * + * <p>This is informational. If this is false, bridged packets will simply + * be dropped and bridging won't work.</p> + */ public final boolean isBridgeEnabled() { return bridge; } + /** + * If true, this network supports and allows broadcast (ff:ff:ff:ff:ff:ff) traffic + */ public final boolean broadcastEnabled() { return broadcastEnabled; } - public final boolean portError() { + /** + * If the network is in PORT_ERROR state, this is the error most recently returned by the port config callback + */ + public final int portError() { return portError; } + /** + * Is this network enabled? If not, all frames to/from are dropped. + */ public final boolean isEnabled() { return enabled; } + /** + * Network config revision as reported by netconf master + * + * <p>If this is zero, it means we're still waiting for our netconf.</p> + */ public final long netconfRevision() { return netconfRevision; } + /** + * Multicast group subscriptions + */ public final ArrayList<MulticastGroup> multicastSubscriptions() { return multicastSubscriptions; } + /** + * ZeroTier-assigned addresses (in {@link java.net.InetAddress} objects) + * + * For IP, the port number of the sockaddr_XX structure contains the number + * of bits in the address netmask. Only the IP address and port are used. + * Other fields like interface number can be ignored. + * + * This is only used for ZeroTier-managed address assignments sent by the + * virtual network's configuration master. + */ public final ArrayList<InetAddress> assignedAddresses() { return assignedAddresses; } diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java b/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java index 9378b6c9..2a26d79d 100644 --- a/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java +++ b/java/src/com/zerotierone/sdk/VirtualNetworkConfigListener.java @@ -30,6 +30,29 @@ package com.zerotierone.sdk; public interface VirtualNetworkConfigListener { + /** + * Callback called to update virtual network port configuration + * + * <p>This can be called at any time to update the configuration of a virtual + * network port. The parameter after the network ID specifies whether this + * port is being brought up, updated, brought down, or permanently deleted. + * + * This in turn should be used by the underlying implementation to create + * and configure tap devices at the OS (or virtual network stack) layer.</P> + * + * This should not call {@link Node#multicastSubscribe} or other network-modifying + * methods, as this could cause a deadlock in multithreaded or interrupt + * driven environments. + * + * This must return 0 on success. It can return any OS-dependent error code + * on failure, and this results in the network being placed into the + * PORT_ERROR state. + * + * @param nwid network id + * @param op {@link VirtualNetworkConfigOperation} enum describing the configuration operation + * @param config {@link VirtualNetworkConfig} object with the new configuration + * @return 0 on success + */ public int onNetworkConfigurationUpdated( long nwid, VirtualNetworkConfigOperation op, diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java b/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java index 2bf6ce09..989961b3 100644 --- a/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java +++ b/java/src/com/zerotierone/sdk/VirtualNetworkConfigOperation.java @@ -27,8 +27,23 @@ package com.zerotierone.sdk; public enum VirtualNetworkConfigOperation { + /** + * Network is coming up (either for the first time or after service restart) + */ VIRTUAL_NETWORK_CONFIG_OPERATION_UP, + + /** + * Network configuration has been updated + */ VIRTUAL_NETWORK_CONFIG_OPERATION_CONFIG_UPDATE, + + /** + * Network is going down (not permanently) + */ VIRTUAL_NETWORK_CONFIG_OPERATION_DOWN, + + /** + * Network is going down permanently (leave/delete) + */ VIRTUAL_NETWORK_CONFIG_OPERATION_DESTROY } diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java b/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java index a38cd722..0b85cab1 100644 --- a/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java +++ b/java/src/com/zerotierone/sdk/VirtualNetworkFrameListener.java @@ -30,6 +30,16 @@ package com.zerotierone.sdk; import java.nio.ByteBuffer; public interface VirtualNetworkFrameListener { + /** + * Function to send a frame out to a virtual network port + * + * @param nwid ZeroTier One network ID + * @param srcMac source MAC address + * @param destMac destination MAC address + * @param ethertype + * @param vlanId + * @param frameData data to send + */ void onVirtualNetworkFrame( long nwid, long srcMac, diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java b/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java index 1102d2ea..78df06b9 100644 --- a/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java +++ b/java/src/com/zerotierone/sdk/VirtualNetworkStatus.java @@ -27,10 +27,33 @@ package com.zerotierone.sdk; public enum VirtualNetworkStatus { + /** + * Waiting for network configuration (also means revision == 0) + */ NETWORK_STATUS_REQUESTING_CONFIGURATION, + + /** + * Configuration received and we are authorized + */ NETWORK_STATUS_OK, + + /** + * Netconf master told us 'nope' + */ NETWORK_STATUS_ACCESS_DENIED, + + /** + * Netconf master exists, but this virtual network does not + */ NETWORK_STATUS_NOT_FOUND, + + /** + * Initialization of network failed or other internal error + */ NETWORK_STATUS_PORT_ERROR, + + /** + * ZeroTier One version too old + */ NETWORK_STATUS_CLIENT_TOO_OLD } diff --git a/java/src/com/zerotierone/sdk/VirtualNetworkType.java b/java/src/com/zerotierone/sdk/VirtualNetworkType.java index b4a8ce2f..adc2eaff 100644 --- a/java/src/com/zerotierone/sdk/VirtualNetworkType.java +++ b/java/src/com/zerotierone/sdk/VirtualNetworkType.java @@ -27,6 +27,13 @@ package com.zerotierone.sdk; public enum VirtualNetworkType { + /** + * Private networks are authorized via certificates of membership + */ NETWORK_TYPE_PRIVATE, + + /** + * Public networks have no access control -- they'll always be AUTHORIZED + */ NETWORK_TYPE_PUBLIC } |