From 6fb602d57bba9fe1a0976f3d6553305be13ac55a Mon Sep 17 00:00:00 2001 From: "W.C.A. Wijngaards" Date: Wed, 22 Jan 2020 11:57:15 +0100 Subject: [PATCH] improve fstrm routine documentation. --- dnstap/dtstream.h | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/dnstap/dtstream.h b/dnstap/dtstream.h index 19d1667ff..94c6b698d 100644 --- a/dnstap/dtstream.h +++ b/dnstap/dtstream.h @@ -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); -- 2.47.3