Work on new simplified C API -- required for embedded, language bindings, mobile (language bindings again), etc.

1 files changed, 369 insertions, 5 deletions

diff --git a/include/ZeroTierOne.h b/include/ZeroTierOne.h
index 0808a750..1707174a 100644
--- a/include/ZeroTierOne.h
+++ b/include/ZeroTierOne.h
@@ -35,6 +35,372 @@
 
 #include <stdint.h>
 
+#ifndef ZT_SOCKADDR_STORAGE
+
+#if defined(_WIN32) || defined(_WIN64)
+
+#include <WinSock2.h>
+#include <WS2tcpip.h>
+#include <Windows.h>
+
+#else // not Windows
+
+#include <netinet/in.h>
+
+#endif // Windows or not
+
+#define ZT_SOCKADDR_STORAGE struct sockaddr_storage
+
+#endif // !ZT_SOCKADDR_STORAGE
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Function return values: OK or various error conditions
+ */
+enum ZT1_ReturnValue
+{
+	ZT1_OK = 0,
+
+	/**
+	 * Our identity collides with another on the network
+	 *
+	 * This is profoundly unlikely: once in about 2^39 identities. If this
+	 * happens to you, delete identity.public and identity.secret from your
+	 * data store / home path and restart. You might also avoid shark infested
+	 * waters, hide during thunderstorms, and consider playing the lottery.
+	 */
+	ZT1_FATAL_ERROR_IDENTITY_COLLISION = 1,
+
+	/**
+	 * Ran out of memory
+	 */
+	ZT1_FATAL_ERROR_OUT_OF_MEMORY = 2,
+
+	/**
+	 * Home path is not writable
+	 */
+	ZT1_FATAL_ERROR_DATA_STORE_NOT_WRITABLE = 3
+};
+
+/**
+ * Status codes
+ */
+enum ZT1_StatusCode
+{
+	/**
+	 * Node is online
+	 */
+	ZT1_STATUS_ONLINE = 1,
+
+	/**
+	 * Node is offline -- nothing is reachable
+	 */
+	ZT1_STATUS_OFFLINE = 2,
+
+	/**
+	 * The desperation level has changed
+	 *
+	 * 'extra' will point to an int containing the new level.
+	 */
+	ZT1_STATUS_DESPERATION_CHANGE = 3
+};
+
+/**
+ * A message to or from a physical address (e.g. IP or physical Ethernet)
+ */
+struct ZT1_WireMessage
+{
+	/**
+	 * Remote socket address
+	 */
+	ZT_SOCKADDR_STORAGE remoteAddress;
+
+	/**
+	 * Link desperation -- higher equals "worse" or "slower"
+	 *
+	 * This is very similar to an interface metric. Higher values indicate
+	 * worse links. For incoming wire messages, it should be sent to the
+	 * desperation metric for the originating socket. For outgoing wire
+	 * messages, ZeroTier will increment this from zero as it grows more
+	 * and more desperate to communicate.
+	 *
+	 * In other words, this value controls fallback to things like TCP
+	 * tunnels to relays. As desperation increases, ZeroTier becomes
+	 * more and more willing to use these links.
+	 *
+	 * Desperation values shouldn't be arbitrary. They should be tied to
+	 * specific transport types. For example: 0 might be UDP, 1 might be
+	 * TCP, and 2 might be HTTP relay via a ZeroTier relay server. There
+	 * should be no gaps. Negative values are permitted and may refer to
+	 * better-than-normal links such as direct raw Ethernet framing over
+	 * a trusted backplane.
+	 */
+	int desperation;
+
+	/**
+	 * If nonzero (true), spam this message across paths up to 'desperation'
+	 *
+	 * This works with 'desperation' to allow fall-forward to less desperate
+	 * paths. When this flag is set, this message should be sent across all
+	 * applicable transports up to and including the specified level of
+	 * desperation.
+	 *
+	 * For example, if spam==1 and desperation==2 the packet might be sent
+	 * via both UDP and HTTP tunneling.
+	 */
+	int spam;
+
+	/**
+	 * Packet data
+	 */
+	const void *packetData;
+
+	/**
+	 * Length of packet
+	 */
+	unsigned int packetLength;
+};
+
+/**
+ * A message to or from a virtual LAN port
+ */
+struct ZT1_VirtualLanFrame
+{
+	/**
+	 * ZeroTier network ID of virtual LAN port
+	 */
+	uint64_t networkId;
+
+	/**
+	 * Source MAC address
+	 */
+	uint64_t sourceMac;
+
+	/**
+	 * Destination MAC address
+	 */
+	uint64_t destMac;
+
+	/**
+	 * 16-bit Ethernet frame type
+	 */
+	unsigned int etherType;
+
+	/**
+	 * 10-bit VLAN ID or 0 for none
+	 */
+	unsigned int vlanId;
+
+	/**
+	 * Ethernet frame data
+	 */
+	const void *frameData;
+
+	/**
+	 * Ethernet frame length
+	 */
+	unsigned int frameLength;
+};
+
+/**
+ * Virtual LAN configuration
+ */
+struct ZT1_VirtualPortConfig
+{
+	/**
+	 * 64-bit ZeroTier network ID
+	 */
+	uint64_t networkId;
+
+	/**
+	 * Ethernet MAC (40 bits) that should be assigned to port
+	 */
+	uint64_t mac;
+
+	/**
+	 * Network configuration request status
+	 */
+	enum {
+		/**
+		 * Waiting for network configuration
+		 */
+		ZT1_VirtualPortConfig_STATUS_WAITING = 0,
+
+		/**
+		 * Configuration received and we are authorized
+		 */
+		ZT1_VirtualPortConfig_STATUS_AUTHORIZED = 1,
+
+		/**
+		 * Netconf master told us 'nope'
+		 */
+		ZT1_VirtualPortConfig_STATUS_ACCESS_DENIED = 2,
+
+		/**
+		 * Netconf master exists, but this virtual network does not
+		 */
+		ZT1_VirtualPortConfig_STATUS_NOT_FOUND = 3
+	} status;
+
+	/**
+	 * Network type
+	 */
+	enum {
+		/**
+		 * Private networks are authorized via certificates of membership
+		 */
+		ZT1_VirtualPortConfig_NETWORK_TYPE_PRIVATE = 0,
+
+		/**
+		 * Public networks have no access control -- they'll always be AUTHORIZED
+		 */
+		ZT1_VirtualPortConfig_NETWORK_TYPE_PUBLIC = 1
+	} type;
+
+	/**
+	 * Desired interface MTU
+	 */
+	unsigned int mtu;
+
+	/**
+	 * If nonzero, DHCP should be used if allowed by security constraints
+	 */
+	int dhcp;
+
+	/**
+	 * If nonzero, this port is allowed to bridge to other networks
+	 */
+	int bridge;
+
+	/**
+	 * Network config revision as reported by netconf master
+	 *
+	 * If this is zero, it means we're still waiting for our netconf.
+	 */
+	unsigned long netconfRevision;
+
+	/**
+	 * ZeroTier-assigned addresses (in sockaddr_storage structures)
+	 *
+	 * 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.
+	 */
+	const ZT_SOCKADDR_STORAGE *assignedAddresses;
+
+	/**
+	 * Number of assigned addresses
+	 */
+	unsigned int assignedAddressCount;
+
+	/**
+	 * Network name (from network configuration master)
+	 */
+	const char *networkName;
+};
+
+/**
+ * Opaque instance of ZeroTier One node
+ */
+typedef void ZT1_Node;
+
+/**
+ * Callback called to update virtual port configuration
+ *
+ * This can be called at any time to update the configuration of a virtual
+ * network port. If a port is deleted (via leave() or otherwise) this is
+ * called with a NULL config parameter.
+ */
+typedef void (*ZT1_VirtualPortConfigCallback)(uint64_t,const struct ZT1_VirtualPortConfig *);
+
+/**
+ * Callback for status messages
+ *
+ * Status messages indicate changes in network status, minor problems or
+ * errors, and other events. The second parameter is a human-readable
+ * detail message, and can be NULL. The third parameter is reserved for any
+ * special structures that might be attached to certain message types, and
+ * is usually NULL.
+ */
+typedef void (*ZT1_StatusCallback)(enum ZT1_StatusCode,const char *,const void *);
+
+/**
+ * Create a new ZeroTier One node
+ *
+ * Note that this can take a few seconds the first time it's called, as it
+ * will generate an identity.
+ *
+ * @param node Result parameter: pointer to set to new node instance
+ * @param homePath ZeroTier home path for storing state information
+ * @param lanConfigUpdateCallback Function to be called when virtual LANs are created, deleted, or their config parameters change
+ * @param statusCallback Function to receive status updates and non-fatal error notices
+ * @return OK (0) or error code if a fatal error condition has occurred
+ */
+enum ZT1_ReturnValue ZT1_Node_new(
+	ZT1_Node **node,
+	const char *homePath,
+	ZT1_VirtualLanConfigCallback *lanConfigUpdateCallback,
+	ZT1_StatusCallback *statusCallback);
+
+/**
+ * Enable network configuration master services for this node
+ *
+ * The supplied instance must be a C++ object that inherits from the
+ * NetworkConfigMaster base class in node/. No type checking is performed,
+ * so a pointer to anything else will result in a crash.
+ *
+ * Normal nodes should not need to use this.
+ *
+ * @param node ZertTier One node
+ * @param networkConfigMasterInstance Instance of NetworkConfigMaster C++ class or NULL to disable
+ * @return OK (0) or error code if a fatal error condition has occurred
+ */
+enum ZT1_ReturnValue ZT1_Node_enableNetconfMaster(
+	ZT1_Node *node,
+	void *networkConfigMasterInstance);
+
+/**
+ * Process wire messages and/or LAN frames
+ *
+ * This runs the ZeroTier core loop once with input packets and frames and
+ * returns zero or more resulting packets or frames. It also sets a max
+ * interval value. The calling code must call run() again after no more
+ * than this many milliseconds of inactivity. If no packets have been
+ * received, it's fine to call run() with no inputs after the inactivity
+ * timeout.
+ *
+ * In addition to normal inputs and outputs, any callbacks registered
+ * with the ZeroTier One core may also be called such as virtual network
+ * endpoint configuration update or diagnostic message handlers.
+ *
+ * @param inputWireMessages ZeroTier transport packets from the wire
+ * @param inputWireMessageCount Number of packets received
+ * @param inputLanFrames Frames read from virtual LAN tap device
+ * @param inputLanFrameCount Number of frames read
+ * @param outputWireMessages Result: set to array of wire messages to be sent
+ * @param outputWireMessageCount Result: set to size of *outputWireMessages[]
+ * @param outputLanFrames Result: set to array of LAN frames to post to tap device
+ * @param outputLanFrameCount Result: set to size of outputLanFrames[]
+ * @param maxNextInterval Result: maximum number of milliseconds before next call to run() is needed
+ * @return OK (0) or error code if a fatal error condition has occurred
+ */
+enum ZT1_ReturnValue ZT1_Node_run(
+	const struct ZT1_WireMessage *inputWireMessages,
+	unsigned int inputWireMessageCount,
+	const struct ZT1_VirtualLanFrame *inputLanFrames,
+	unsigned int inputLanFrameCount,
+	const struct ZT1_WireMessage **outputWireMessages,
+	unsigned int *outputWireMessageCount,
+	const struct ZT1_VirtualLanFrame **outputLanFrames,
+	unsigned int *outputLanFrameCount,
+	unsigned long *maxNextInterval);
+
 /* ------------------------------------------------------------------------ */
 /* Query result buffers                                                     */
 /* ------------------------------------------------------------------------ */
@@ -354,10 +720,8 @@ struct ZT1_Node_NetworkList
 	unsigned int numNetworks;
 };
 
-/* ------------------------------------------------------------------------ */
-/* ZeroTier One C API                                                       */
-/* ------------------------------------------------------------------------ */
-
-/* coming soon... */
+#ifdef __cplusplus
+}
+#endif
 
 #endif