From 01aa0ff0fcac3f98df54bf2f55002b00f0afda2d Mon Sep 17 00:00:00 2001
From: Russell Bryant <russellbryant@users.sourceforge.net>
Date: Sun, 6 Jan 2008 14:30:28 +0000
Subject: (Merge the rest of my changes from issue #1848356)

When I first starting looking into different ways to stream audio into Pd, I
spent a little bit of time looking at streamin~/streamout~.  While looking at
it, I fixed the security issue from the previous commit, and made the following
updates to stream.h.

 - Adding doxygen style comments.
 - Add an ifdef to prevent against multiple or recursive includes of the header.
 - Document most of the fields in the defined data structures.
 - Fix potential alignment bugs (at least on platforms using GNUC) by using the
   packed attribute for structures defining network frames.
     See http://gcc.gnu.org/onlinedocs/gcc-4.2.2/gcc/Variable-Attributes.html#Variable%20Attributes
 - Point out the fact that this code is not endianness-safe, and that it should
   eventually be updated to respect network byte order.
 - Point out that the version field of the frame header is ignored when parsing
   incoming frames.
 - Change a list of #defines to an enum.
 - Instead of using "int" in the frame header structure, use int32_t to explicitly
   state that the field is 32-bits.

svn path=/trunk/externals/ggee/; revision=9134
---
 signal/stream.h | 83 ++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 64 insertions(+), 19 deletions(-)

(limited to 'signal')

diff --git a/signal/stream.h b/signal/stream.h
index 3ccc205..8872165 100755
--- a/signal/stream.h
+++ b/signal/stream.h
@@ -1,29 +1,74 @@
 /* (C) Guenter Geiger 1999 */
 
-#define SF_FLOAT  1
-#define SF_DOUBLE 2
-#define SF_8BIT   10
-#define SF_16BIT  11
-#define SF_32BIT  12
-#define SF_ALAW   20
-#define SF_MP3    30
+/*!
+ * \file
+ * \author Guenter Geiger
+ *
+ * \brief Definitions used by both streamin~ and streamout~
+ *
+ * \todo This code does not honor network byte order.
+ */
 
-#define SF_SIZEOF(a) (a == SF_FLOAT ? sizeof(t_float) : a == SF_16BIT ? sizeof(short) : 1)
+#ifndef __PD_STREAM_H
+#define __PD_STREAM_H
+
+#include <inttypes.h>
 
+/*!
+ * \brief Format identifiers for frames
+ */
+enum tag_format {
+    SF_FLOAT  = 1,
+    SF_DOUBLE = 2,
+    SF_8BIT   = 10,
+    SF_16BIT  = 11,
+    SF_32BIT  = 12,
+    SF_ALAW   = 20,
+    SF_MP3    = 30
+};
 
+#define SF_SIZEOF(a) (a == SF_FLOAT ? sizeof(t_float) : a == SF_16BIT ? sizeof(short) : 1)
 
-typedef struct _tag {      /* size (bytes) */
-     char version;         /*    1         */
-     char format;          /*    1         */
-     int count;            /*    4         */
-     char channels;        /*    1         */
-     int framesize;        /*    4         */
-     char  extension[5];   /*    5         */
-} t_tag;                   /*--------------*/
-                           /*   16         */
+#ifdef __GNUC__
+#define PACKED __attribute__ ((packed))
+#endif
 
+/*!
+ * \brief 16-byte frame header
+ *
+ * \note Version 1
+ */
+typedef struct _tag {
+     /*! Frame header version.  Currently ignored in streamin, but always set
+      *  to 1 for streamout.
+      *
+      *  \todo Add version checking on incoming frames.  However, this could
+      *        break existing uses of the external. */
+     char version;
+     /*! This field identifies the type of data is in the frame payload */
+     char format;
+     /*! ??? */
+     int32_t count;
+     /*! ??? */
+     char channels;
+     /*! This indicates the full size of the frame.  It is basically
+      *  ( sizeof(t_tag) + payload length ). */
+     int32_t framesize;
+     /*! ??? */
+     char extension[5];
+} PACKED t_tag;
 
+
+/*!
+ * \brief A complete frame
+ */
 typedef struct _frame {
-     t_tag  tag;
-     char*  data;
+     /*! This is the frame header that contains the metadata about the frame */
+     t_tag tag;
+     /*! This buffer stores the frame data payload.  The amount of data in this
+      *  buffer is the tag.framesize - sizeof(t_tag).  Its contents can be
+      *  interpreted according to the tag.version. */
+     char *data;
 } t_frame;
+
+#endif /* __PD_STREAM_H */
-- 
cgit v1.2.1