moved comments to the header file

TinyFrame.c

@@ -56,13 +56,6 @@ static struct TinyFrameStruct {
     char sendbuf[TF_MAX_PAYLOAD+1];
 } tf;
 
-
-/**
- * Initialize the TinyFrame engine.
- * This can also be used to completely reset it (removing all listeners etc)
- *
- * @param peer_bit - peer bit to use for self
- */
 void TF_Init(bool peer_bit)
 {
     memset(&tf, 0, sizeof(struct TinyFrameStruct));
@@ -70,24 +63,12 @@ void TF_Init(bool peer_bit)
     tf.peer_bit = peer_bit;
 }
 
-
-/**
- * Reset the frame parser state machine.
- */
 void TF_ResetParser(void)
 {
     tf.state = TFState_SOF;
     tf.cksum = 0;
 }
 
-
-/**
- * Register a frame type listener.
- *
- * @param frame_type - frame ID to listen for
- * @param cb - callback
- * @return slot index (for removing), or TF_ERROR (-1)
- */
 int TF_AddIdListener(unsigned int frame_id, TinyFrameListener cb)
 {
     int i;
@@ -103,14 +84,6 @@ int TF_AddIdListener(unsigned int frame_id, TinyFrameListener cb)
     return TF_ERROR;
 }
 
-
-/**
- * Register a frame type listener.
- *
- * @param frame_type - frame type to listen for
- * @param cb - callback
- * @return slot index (for removing), or TF_ERROR (-1)
- */
 int TF_AddTypeListener(unsigned char frame_type, TinyFrameListener cb)
 {
     int i;
@@ -126,13 +99,6 @@ int TF_AddTypeListener(unsigned char frame_type, TinyFrameListener cb)
     return TF_ERROR;
 }
 
-
-/**
- * Register a generic listener.
- *
- * @param cb - callback
- * @return slot index (for removing), or TF_ERROR (-1)
- */
 int TF_AddGenericListener(TinyFrameListener cb)
 {
     int i;
@@ -147,12 +113,6 @@ int TF_AddGenericListener(TinyFrameListener cb)
     return TF_ERROR;
 }
 
-
-/**
- * Remove a rx callback function by the index received when registering it
- *
- * @param index - index in the callbacks table
- */
 void TF_RemoveListener(unsigned int index)
 {
     // all listener arrays share common "address space"
@@ -187,12 +147,6 @@ void TF_RemoveTypeListener(unsigned char type)
     }
 }
 
-
-/**
- * Remove a callback by the function pointer
- *
- * @param cb - callback function to remove
- */
 void TF_RemoveListenerFn(TinyFrameListener cb)
 {
     int i;
@@ -216,13 +170,6 @@ void TF_RemoveListenerFn(TinyFrameListener cb)
     }
 }
 
-
-/**
- * Accept incoming bytes & parse frames
- *
- * @param buffer - byte buffer to process
- * @param count - nr of bytes in the buffer
- */
 void TF_Accept(const unsigned char *buffer, unsigned int count)
 {
     unsigned int i;
@@ -232,12 +179,6 @@ void TF_Accept(const unsigned char *buffer, unsigned int count)
     }
 }
 
-
-/**
- * Process a single received character
- *
- * @param c - rx character
- */
 void TF_AcceptChar(unsigned char c)
 {
     int i;
@@ -323,17 +264,6 @@ void TF_AcceptChar(unsigned char c)
     tf.cksum ^= c;
 }
 
-
-/**
- * Compose a frame
- *
- * @param outbuff - buffer to store the result in
- * @param msgid - message ID is stored here, if not NULL
- * @param payload - data buffer
- * @param len - payload size in bytes, 0 to use strlen
- * @param explicit_id - ID to use, -1 to chose next free
- * @return nr of bytes in outbuff used by the frame, -1 on failure
- */
 int TF_Compose(unsigned char *outbuff, unsigned int *msgid,
                const unsigned char *payload, unsigned int payload_len,
                int explicit_id
@@ -377,17 +307,10 @@ int TF_Compose(unsigned char *outbuff, unsigned int *msgid,
     return payload_len + 4;
 }
 
-
-/**
- * Send a frame, and optionally attach an ID listener for response.
- *
- * @param payload - data to send
- * @param payload_len - nr of bytes to send
- * @return listener ID if listener was attached, else -1 (FT_ERROR)
- */
 int TF_Send(const unsigned char *payload,
              unsigned int payload_len,
-			 TinyFrameListener listener)
+             TinyFrameListener listener,
+             unsigned int *id_ptr)
 {
     unsigned int msgid;
     int len;
@@ -395,20 +318,15 @@ int TF_Send(const unsigned char *payload,
     len = TF_Compose(tf.sendbuf, &msgid, payload, payload_len, TF_NEXT_ID);
     if (listener) lstid = TF_AddIdListener(msgid, listener);
     TF_WriteImpl(tf.sendbuf, len);
+
+    if (id_ptr) *id_ptr = msgid;
+
     return lstid;
 }
 
-
-/**
- * Send a response to a received message.
- *
- * @param payload - data to send
- * @param payload_len - nr of bytes to send
- * @param frame_id - ID of the original frame
- */
 void TF_Respond(const unsigned char *payload,
                unsigned int payload_len,
-			   int frame_id)
+               unsigned int frame_id)
 {
     int len;
     len = TF_Compose(tf.sendbuf, NULL, payload, payload_len, frame_id);
@@ -417,17 +335,19 @@ void TF_Respond(const unsigned char *payload,
 
 
 int TF_Send1(const unsigned char b0,
-			 TinyFrameListener listener)
+             TinyFrameListener listener,
+             unsigned int *id_ptr)
 {
     unsigned char b[] = {b0};
-	return TF_Send(b, 1, listener);
+    return TF_Send(b, 1, listener, id_ptr);
 }
 
 
 int TF_Send2(const unsigned char b0,
              const unsigned char b1,
-			 TinyFrameListener listener)
+             TinyFrameListener listener,
+             unsigned int *id_ptr)
 {
     unsigned char b[] = {b0, b1};
-	return TF_Send(b, 2, listener);
+    return TF_Send(b, 2, listener, id_ptr);
 }

TinyFrame.h

@@ -20,64 +20,148 @@
 # define TF_MAX_GEN_LST  4
 #endif
 
+#define TF_NEXT_ID -1
+#define TF_ERROR -1
+
 /**
  * TinyFrame receive callback type.
- *
  * @param frame_id - ID of the received frame
  * @param buff - byte buffer with the payload
  * @param len - number of bytes in the buffer
  * @return true if the frame was consumed
  */
-typedef bool (*TinyFrameListener)(
+typedef bool (*TinyFrameListener)(unsigned int frame_id,
-	unsigned int frame_id,
                                   const unsigned char *buff,
-	unsigned int len
+                                  unsigned int len);
-);
 
-// Forward declarations (comments in .c)
+/**
+ * Initialize the TinyFrame engine.
+ * This can also be used to completely reset it (removing all listeners etc)
+ * @param peer_bit - peer bit to use for self
+ */
+void TF_Init(bool peer_bit);
 
+/**
+ * Reset the frame parser state machine.
+ */
 void TF_ResetParser(void);
-void TF_Init(bool peer_bit);
 
+/**
+ * Accept incoming bytes & parse frames
+ * @param buffer - byte buffer to process
+ * @param count - nr of bytes in the buffer
+ */
 void TF_Accept(const unsigned char *buffer, unsigned int count);
+
+/**
+ * Accept a single incoming byte
+ * @param c - a received char
+ */
 void TF_AcceptChar(unsigned char c);
 
-// Add?Listener all return a unique listener ID
+/**
+ * Register a frame type listener.
+ * @param frame_type - frame ID to listen for
+ * @param cb - callback
+ * @return slot index (for removing), or TF_ERROR (-1)
+ */
 int TF_AddIdListener(unsigned int frame_id, TinyFrameListener cb);
+
+/**
+ * Register a frame type listener.
+ * @param frame_type - frame type to listen for
+ * @param cb - callback
+ * @return slot index (for removing), or TF_ERROR (-1)
+ */
 int TF_AddTypeListener(unsigned char frame_type, TinyFrameListener cb);
+
+/**
+ * Register a generic listener.
+ * @param cb - callback
+ * @return slot index (for removing), or TF_ERROR (-1)
+ */
 int TF_AddGenericListener(TinyFrameListener cb);
 
+/**
+ * Remove any listener by the index received when registering it
+ * @param index - index in the callbacks table
+ */
 void TF_RemoveListener(unsigned int index);
+
+/**
+ * Remove a listener by the message ID it's registered for
+ * @param frame_id - the frame we're listening for
+ */
 void TF_RemoveIdListener(unsigned int frame_id);
+
+/**
+ * Remove a listener by type.
+ * @param type - the type it's registered for
+ */
 void TF_RemoveTypeListener(unsigned char type);
-void TF_RemoveListenerFn(TinyFrameListener cb); // search all listener types
 
-#define TF_NEXT_ID -1
+/**
-#define TF_ERROR -1
+ * Remove a callback by the function pointer
+ * @param cb - callback function to remove
+ */
+void TF_RemoveListenerFn(TinyFrameListener cb); // search all listener types
 
-// returns nr of bytes in the output buffer used, or TF_ERROR
+/**
+ * Compose a frame
+ *
+ * @param outbuff - buffer to store the result in
+ * @param msgid - message ID is stored here, if not NULL
+ * @param payload - data buffer
+ * @param len - payload size in bytes, 0 to use strlen
+ * @param explicit_id - ID to use, TF_NEXT_ID (-1) to chose next free
+ * @return nr of bytes in outbuff used by the frame, TF_ERROR (-1) on failure
+ */
 int TF_Compose(unsigned char *outbuff, unsigned int *msgid,
                const unsigned char *payload, unsigned int payload_len,
                int explicit_id);
 
-// returns listener ID (-1 if listener is NULL - does not indicate error)
+/**
+ * Send a frame, and optionally attach an ID listener for response.
+ *
+ * @param payload - data to send
+ * @param payload_len - nr of bytes to send
+ * @param id_ptr - store the ID here, NULL to don't store.
+ *                 The ID may be used to unbind the listener after a timeout.
+ * @return listener ID if listener was attached, else -1 (FT_ERROR).
+ *         If the listener arg was NULL, returned -1 does not indicate an error.
+ */
 int TF_Send(const unsigned char *payload,
              unsigned int payload_len,
-			 TinyFrameListener listener);
+             TinyFrameListener listener, unsigned int *id_ptr);
 
+/**
+ * A shorthand for TF_Send() with just one byte as the payload
+ */
 int TF_Send1(const unsigned char b0,
-			 TinyFrameListener listener);
+             TinyFrameListener listener, unsigned int *id_ptr);
 
+/**
+ * A shorthand for TF_Send() with just 2 bytes as the payload
+ */
 int TF_Send2(const unsigned char b0,
              const unsigned char b1,
-			 TinyFrameListener listener);
+             TinyFrameListener listener, unsigned int *id_ptr);
 
-// Respond with the same ID
+/**
+ * Send a response to a received message.
+ *
+ * @param payload - data to send
+ * @param payload_len - nr of bytes to send
+ * @param frame_id - ID of the original frame
+ */
 void TF_Respond(const unsigned char *payload,
                unsigned int payload_len,
-			   int frame_id);
+               unsigned int frame_id);
 
-/** Write implementation for TF, to be provided by user code */
+/**
+ * Write implementation for TF, to be provided by user code.
+ * This sends frames composed by TinyFrame to UART
+ */
 extern void TF_WriteImpl(const unsigned char *buff, unsigned int len);
 
 #endif

test.c

@@ -42,9 +42,10 @@ void main()
 
 	printf("------ Simulate sending a message --------\n");
 
-	// Send a message, not expecting any reply
+	// Send a message
-	// Returns Listener ID (if the listener is not NULL, like here)
+	//   args - payload, length (0 = strlen), listener, id_ptr (for storing the frame ID)
-	TF_Send("Hello TinyFrame", 0, NULL);
+	//   (see the .h file for details)
+	TF_Send("Hello TinyFrame", 0, NULL, NULL);
 	// This builds the frame in an internal buffer and sends it to
 	//   TF_WriteImpl()