Version 4.4.0

include/InetWvIn.h

@@ -1,3 +1,14 @@
+#ifndef STK_INETWVIN_H
+#define STK_INETWVIN_H
+
+#include "WvIn.h"
+#include "TcpServer.h"
+#include "UdpSocket.h"
+#include "Thread.h"
+#include "Mutex.h"
+
+namespace stk {
+
 /***************************************************/
 /*! \class InetWvIn
     \brief STK internet streaming input class.
@@ -8,10 +19,10 @@
     supported.
 
     InetWvIn supports multi-channel data.  It is important to
-    distinguish the tick() methods, which return samples produced by
-    averaging across sample frames, from the tickFrame() methods,
-    which return references or pointers to multi-channel sample
-    frames.
+    distinguish the tick() method that computes a single frame (and
+    returns only the specified sample of a multi-channel frame) from
+    the overloaded one that takes an StkFrames object for
+    multi-channel and/or multi-frame data.
 
     This class implements a socket server.  When using the TCP
     protocol, the server "listens" for a single remote connection
@@ -20,19 +31,10 @@
     data type for the incoming stream is signed 16-bit integers,
     though any of the defined StkFormats are permissible.
 
-    by Perry R. Cook and Gary P. Scavone, 1995 - 2007.
+    by Perry R. Cook and Gary P. Scavone, 1995 - 2009.
 */
 /***************************************************/
 
-#ifndef STK_INETWVIN_H
-#define STK_INETWVIN_H
-
-#include "WvIn.h"
-#include "TcpServer.h"
-#include "UdpSocket.h"
-#include "Thread.h"
-#include "Mutex.h"
-
 typedef struct {
   bool finished;
   void *object;
@@ -69,9 +71,46 @@ public:
   */
   bool isConnected( void );
 
+  //! Return the specified channel value of the last computed frame.
+  /*!
+    For multi-channel files, use the lastFrame() function to get
+    all values from the last computed frame.  If no connection exists,
+    the returned value is 0.0.  The \c channel argument must be less
+    than the number of channels in the data stream (the first channel
+    is specified by 0).  However, range checking is only performed if
+    _STK_DEBUG_ is defined during compilation, in which case an
+    out-of-range value will trigger an StkError exception.
+  */
+  StkFloat lastOut( unsigned int channel = 0 );
+
+  //! Compute a sample frame and return the specified \c channel value.
+  /*!
+    For multi-channel files, use the lastFrame() function to get
+    all values from the computed frame.  If no connection exists, the
+    returned value is 0.0 (and a warning will be issued if _STK_DEBUG_
+    is defined during compilation).  The \c channel argument must be
+    less than the number of channels in the data stream (the first
+    channel is specified by 0).  However, range checking is only
+    performed if _STK_DEBUG_ is defined during compilation, in which
+    case an out-of-range value will trigger an StkError exception.
+  */
+  StkFloat tick( unsigned int channel = 0 );
+
+  //! Fill the StkFrames argument with computed frames and return the same reference.
+  /*!
+    The number of channels in the StkFrames argument must equal the
+    number of channels specified in the listen() function.  However,
+    this is only checked if _STK_DEBUG_ is defined during compilation,
+    in which case an incompatibility will trigger an StkError
+    exception.  If no connection exists, the function does
+    nothing (a warning will be issued if _STK_DEBUG_ is defined during
+    compilation).
+  */
+  StkFrames& tick( StkFrames& frames );
+
   // Called by the thread routine to receive data via the socket connection
   // and fill the socket buffer.  This is not intended for general use but
-  // had to be made public for access from the thread.
+  // must be public for access from the thread.
   void receive( void );
 
 protected:
@@ -79,8 +118,6 @@ protected:
   // Read buffered socket data into the data buffer ... will block if none available.
   int readData( void );
 
-  void computeFrame( void );
-
   Socket *soket_;
   Thread thread_;
   Mutex mutex_;
@@ -100,4 +137,21 @@ protected:
 
 };
 
+inline StkFloat InetWvIn :: lastOut( unsigned int channel )
+{
+#if defined(_STK_DEBUG_)
+  if ( channel >= data_.channels() ) {
+    errorString_ << "InetWvIn::lastOut(): channel argument and data stream are incompatible!";
+    handleError( StkError::FUNCTION_ARGUMENT );
+  }
+#endif
+
+  // If no connection and we've output all samples in the queue, return.
+  if ( !connected_ && bytesFilled_ == 0 && bufferCounter_ == 0 ) return 0.0;
+
+  return lastFrame_[channel];
+}
+
+} // stk namespace
+
 #endif