+Protocol documentation

diff --git a/src/packet.c b/src/packet.c
index 8be08de..0e71136 100644 (file)
--- a/src/packet.c
+++ b/src/packet.c
@@ -17,6 +17,53 @@
  */
 
 
+/* Protocol documentation:
+ * 8 bytes: "UDPGate0" (55 44 50 47 61 74 65 30) = Packet identifier
+ * Follows arbitrary number of elements in no particular order.
+ * Structure of each such element:
+ * 4 bytes: element identifier; network byte order
+ *     bit 31 (0x80000000) means mandatory element:
+ *         If the element is not recognized the packet must be dropped.
+ *     bits 0..30 (0x7FFFFFFF) specify element id.
+ * 4 bytes: element data length; network byte order
+ * X bytes: element data; minimal data alignment is 1 byte (=no alignment)
+ * Known elements; see: http://cvs.jankratochvil.net/viewcvs/udpgate/src/packet.h?rev=HEAD
+ *     PROGRAM_VERSION: data=string (no zero terminator); currently "1.0"
+ *         This element is currently ignored.
+ *     CLIENT_INADDR: Client IPv4 address; network byte order; length=4B
+ *     CLIENT_PORT: Client IPv4 port; network byte order; length=2B
+ *     DATA_GUINT32: Session unique number; network byte order; length=4B
+ *         Reply packet will copy this element intact.
+ * Step 1:
+ *     Client sends from port A (35545 here) to port 8201 (probe port) packet:
+ *         PROGRAM_VERSION (of the client udpgate)
+ *         CLIENT_PORT (chosen port; default is 9201)
+ *         DATA_GUINT32 (chosen random number)
+ *     Example:
+ *         09:07:01.966123 127.0.0.1.35545 > 127.0.0.1.8201: udp 44 (DF)
+ *            16=$0010: <UDP packet headers................> 55 44 50 47 |             UDPG
+ *            32=$0020: 61 74 65 30 80 00 00 01  00 00 00 06 31 2E 30 63 | ate0........1.0c
+ *            48=$0030: 76 73 80 00 00 03 00 00  00 02 1A 0A 80 00 00 04 | vs..............
+ *            64=$0040: 00 00 00 04 99 E1 4B 04                          | ......K.
+ * Step 2:
+ *     Probe server replies from port B (currently always 8201) to the packet
+ *             originating address CLIENT_INADDR and the received CLIENT_PORT:
+ *         PROGRAM_VERSION (of the probe server)
+ *         CLIENT_INADDR (detected from the originating packet address)
+ *         DATA_GUINT32 (copied from the request packet)
+ *     Example:
+ *         09:07:01.970252 127.0.0.1.8201 > 127.0.0.1.6666: udp 46 (DF)
+ *            16=$0010: <UDP packet headers................> 55 44 50 47 |             UDPG
+ *            32=$0020: 61 74 65 30 80 00 00 01  00 00 00 06 31 2E 30 63 | ate0........1.0c
+ *            48=$0030: 76 73 80 00 00 02 00 00  00 04 7F 00 00 01 80 00 | vs..............
+ *            64=$0040: 00 04 00 00 00 04 99 E1  4B 04                   | ........K.
+ * Step 3:
+ *     Client must ignore probe replies with nonmatching DATA_GUINT32.
+ *     Client will stop if no probe reply is received in PROBE_TIMEOUT_SEC.
+ *     Client displays the received CLIENT_INADDR to the user.
+ */
+
+
 #include "config.h"
 
 #include <glib/gmessages.h>