Protocol: more code and a tutorial.

Signed-off-by: Ramūnas Mažeikis <ramunasnezinomas@gmail.com>

1 files changed, 60 insertions, 46 deletions

diff --git a/include/protocol.h b/include/protocol.h
index e15ef6a..387424f 100644
--- a/include/protocol.h
+++ b/include/protocol.h
@@ -21,6 +21,41 @@
 #ifndef USURPATION_PROTOCOL_H_INCLUDED
 #define USURPATION_PROTOCOL_H_INCLUDED
 
+#if 0
+
+ How do we use this API(?), I hear you say. Well, here is a self-contained
+ example complete with tedious comments:
+
+-------------------------------------------------------------------------------
+  1 |	void functy_the_function(void)
+  2 |	{
+  3 |		struct tlv tlv_packet;				/* A packet made of tlv's */
+  4 |		struct tlv text;				/* Actually useful data */
+  5 |		char *packet;					/* Raw bytes to be pushed via UDP */
+  6 |		size_t packet_size;				/* Raw packet size */
+  7 |		char message[] = "Get jacked!";			/* Duh! */
+  9 |
+ 10 |		tlv_init(&tlv_packet, REGURAL);			/* Initialise tlv_packet to regular */
+ 11 |		tlv_init(&text, TEXT);				/* Initialise text packet */
+ 12 |		tlv_push_data(&text, message, sizeof(message));	/* Push text to appropriate tlv */
+ 13 |		tlv_push_tlv(&tlv_packet, &text);		/* Push the tlv into tlv packet */
+ 14 |
+ 15 |		packet_size = tlv_raw_size(&tlv_packet);	/* Get raw size required to push entire tlv_packet as bytes */
+ 16 |		packet = (char *)malloc(packet_size);		/* Allocate buffer for outgoing packet */
+ 17 |		tlv_get_raw(&tlv_packet, packet);		/* Flash tlv_packet to buffer */
+ 19 |		udp_push(packet, packet_size);			/* Push packet via UDP */
+ 20 |		udp_flush();					/* Flush to the other side*/
+ 21 |
+ 22 |		tlv_destroy(&text);				/* Free text tlv */
+ 23 |		tlv_destroy(&tlv_packet);			/* Free tlv_packet */
+ 24 |		free(packet);					/* Free packet itself */
+ 25 |		return;						/* GTFO and save stack space */
+ 26 |	}
+-------------------------------------------------------------------------------
+
+#endif
+
+
 #include <errno.h>
 
 #define E_TLV_OVERFLOW		(1 << 0)
@@ -30,19 +65,6 @@
 #define TLV_SZ_MAX_RAW		(MTU - 64)
 
 /**
- * Regular packets contain tlv's defined by tlv_type.
- *
- * Hearbeat packet tell daemon that device is still alive and listening.
- *
- * Discovery packets are used for what they say.
- */
-enum packet_type {
-	REGURAL,
-	HEARTBEAT,
-	DISCOVERY
-};
-
-/**
  * Message sequence number since beggining of sesssion.
  *
  * Mainly used for identifying lost messages.
@@ -77,20 +99,24 @@ enum tlv_type {
 	/**
 	 * UUID that represents a particular device.
 	 */
-	UUID
-};
+	UUID,
 
-/**
- * Packet data itself is a special type of tlv. A packet is either regular,
- * hearbeat or discovery.
- *
- * May be used to send data.
- */
-struct tlv_packet {
-	enum packet_type type;
-	size_t size;
-	size_t offset;
-	char *data;	/* Bytes representing tlv's */
+/* Data of the following types are other tlv's! */
+
+	/**
+	 * Just a TLV container.
+	 */
+	REGURAL,
+
+	/**
+	 * Says "I'm not dead yet.".
+	 */
+	HEARTBEAT,
+
+	/**
+	 * Says "Bring out yer dead!".
+	 */
+	DISCOVERY
 };
 
 /**
@@ -122,24 +148,6 @@ struct tlv_parser {
 int tlv_get(struct tlv_parser *parser, struct tlv *ret);
 
 /**
- * Appends data to the next packet to be sent. Type of data is determined by
- * enum tlv_type.
- *
- * In case of overflow return E_TLV_OVERFLOW.
- *
- * On next call after retreiving last packet returns END_OF_PACKET.
- *
- * Overflow can be detected after forming tlv header. This means that the
- * packet may have changes.
- * */
-int tlv_push_data(struct tlv_packet *packet, enum tlv_type type, char *data);
-
-/**
- * Resets offset to 0 and set entire buffer to 0.
- */
-void tlv_clear_data(struct tlv_packet *packet);
-
-/**
  * Initialises tlv to sane values.
  */
 void tlv_init(struct tlv *t, enum tlv_type type);
@@ -153,7 +161,7 @@ void tlv_destroy(struct tlv *t);
 /**
  * Tells amount of bytes needed to push tlv to a buffer
  */
-size_t tlv_raw_size(struct tlv *t);
+size_t tlv_raw_size(const struct tlv *t);
 
 /**
  * Pushes tlv to buffer as contiguous data. Check tlv size with tlv_raw_size
@@ -166,6 +174,12 @@ int tlv_get_raw(struct tlv *t, char *buf);
  * final size to be greater than TLV_SZ_MAX_RAW. In case of such error the data is left
  * untouched.
  */
-int tlv_push(struct tlv *t, const char *data, size_t size);
+int tlv_push_data(struct tlv *t, const char *data, size_t size);
+
+/**
+ * Pushes a sub-tlv into the packet. 't' can only be REGURAL, HEARTBEAT or
+ * DISCOVERY.
+ */
+int tlv_push_tlv(struct tlv *t, const struct tlv *other);
 
 #endif /* USURPATION_PROTOCOL_H_INCLUDED */