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