improve fstrm routine documentation.
@@ -225,29 +225,28 @@ struct dt_io_list_item {
#define DNSTAP_CONTENT_TYPE "protobuf:dnstap.Dnstap"
/**
- * routine for START message, with content type.
* This creates an FSTRM control frame of type START.
* @param contenttype: a zero delimited string with the content type.
- * eg. DNSTAP_CONTENT_TYPE, "protobuf:dnstap.Dnstap"
+ * eg. use the constant DNSTAP_CONTENT_TYPE, which is defined as
+ * "protobuf:dnstap.Dnstap", for a dnstap frame stream.
* @param len: if a buffer is returned this is the length of that buffer.
* @return NULL on malloc failure. Returns a malloced buffer with the
- * protocol message. The buffer starts with the 4byte 0 that indicates
+ * protocol message. The buffer starts with the 4 bytes of 0 that indicate
* a control frame. The buffer should be sent without preceding it with
- * the 'len' variable, but straight the 0 start zeroes, and then the
- * length of the control frame itself is embedded next in the buffer,
- * with the control frame after that in the buffer.
+ * the 'len' variable (like data frames are), but straight the content of the
+ * buffer, because the lengths are included in the buffer. This is so that
+ * the zero control indicator can be included before the control frame length.
*/
void* fstrm_create_control_frame_start(char* contenttype, size_t* len);
/**
- * routine for STOP message.
* This creates an FSTRM control frame of type STOP.
* @param len: if a buffer is returned this is the length of that buffer.
* @return NULL on malloc failure. Returns a malloced buffer with the
- * protocol message. The buffer starts with the 4byte 0 that indicates
+ * protocol message. The buffer starts with the 4 bytes of 0 that indicate
* a control frame. The buffer should be sent without preceding it with
- * the 'len' variable, but straight the 0 start zeroes, and then the
- * length of the control frame itself is embedded next in the buffer,
- * with the control frame after that in the buffer.
+ * the 'len' variable (like data frames are), but straight the content of the
+ * buffer, because the lengths are included in the buffer. This is so that
+ * the zero control indicator can be included before the control frame length.
*/
void* fstrm_create_control_frame_stop(size_t* len);
