[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    branches/work/kdelibs-phonon/phonon
From:       Matthias Kretz <kretz () kde ! org>
Date:       2006-01-19 20:58:17
Message-ID: 1137704297.668860.3522.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 500263 by mkretz:

add apidox


 M  +88 -3     bytestream.h  


--- branches/work/kdelibs-phonon/phonon/bytestream.h #500262:500263
@@ -33,14 +33,72 @@
 		class ByteStream;
 	}
 
+	/**
+	 * \short Send media data to be decoded and played back.
+	 *
+	 * This class allows you to send arbitrary media data (well, any media data
+	 * format that the backend can decode) to the mediaframework used by the
+	 * backend. MediaObject uses the facilities of this class internally when
+	 * the mediaframework cannot handle an URL using KIO to fetch the data and
+	 * ByteStream to stream it to the backend.
+	 *
+	 * To use it you need to provide a constant (fast enough) datastream via
+	 * writeData. The signals needData and enoughData tell when the stream is
+	 * about to drop out or when the internal buffer is sufficently filled. The
+	 * backend should be able to buffer whatever you throw at it (of course,
+	 * depending on the available memory of the computer).
+	 *
+	 * This allows your data provider to use a push method (calling writeData
+	 * and waiting when enoughData is emitted) or a pull method (call writeData
+	 * whenever needData is emitted).
+	 *
+	 * If your datastream is seekable you can tell the ByteStream object via
+	 * setStreamSeekable. When a seek is called and the ByteStream needs data at
+	 * a different position it will tell you with the seekStream signal. This
+	 * signal passes the offset from the beginning of the datastream where the
+	 * next array of data passed to writeData should start from.
+	 *
+	 * When the datastream is complete written you need to call endOfData, else
+	 * ByteStream will not emit the finished signal, but go into the
+	 * BufferingState.
+	 *
+	 * As soon as you know the size of the stream (in bytes) you should call
+	 * setStreamSize. This could be usefull for the ByteStream object to
+	 * correctly emit the aboutToFinish signal. If the size is not known the
+	 * aboutToFinish signal will still work, but you should not depend on it
+	 * being emitted at the correct time.
+	 *
+	 * \author Matthias Kretz <kretz@kde.org>
+	 * \since 4.0
+	 */
 	class PHONON_EXPORT ByteStream : public AbstractMediaProducer
 	{
 		Q_OBJECT
 		PHONON_HEIR( ByteStream )
 		public:
+			/**
+			 * \copydoc MediaObject::totalTime()
+			 */
 			long totalTime() const;
+
+			/**
+			 * \copydoc MediaObject::totalTime()
+			 */
 			long remainingTime() const;
+
+			/**
+			 * \copydoc MediaObject::totalTime()
+			 */
 			long aboutToFinishTime() const;
+
+			/**
+			 * Returns the size of the stream in bytes. If the size is unknown
+			 * \c -1 is returned.
+			 *
+			 * \return \c -1 if the size is unknown, otherwise the size in bytes
+			 *
+			 * \see setStreamSize
+			 */
 			long streamSize() const;
 
 			/**
@@ -51,6 +109,8 @@
 			 * seekStream is emitted.
 			 * \return \c false You only have to write the stream to writeData
 			 * in one sequence.
+			 *
+			 * \see setStreamSeekable
 			 */
 			bool streamSeekable() const;
 
@@ -69,12 +129,27 @@
 			 */
 			void setStreamSeekable( bool seekable );
 
+			/**
+			 * Passes media data to the mediaframework used by the backend. The
+			 * data should be written in chunks of at least 512 bytes to not
+			 * become too inefficient.
+			 *
+			 * \todo Actually I have no idea what array size should be used.
+			 * Some tests would be good.
+			 *
+			 * \data A QByteArray holding the data. After this call you are free
+			 * to dispose of the array.
+			 *
+			 * \see needData
+			 * \see enoughData
+			 * \see seekStream
+			 */
 			void writeData( const QByteArray& data );
 
 			/**
-			 * Sets how many bytes the stream has. The Size is counted from the
-			 * start of the stream until the end and not from the point in time
-			 * when the slot is called.
+			 * Sets how many bytes the complete datastream has. The Size is
+			 * counted from the start of the stream until the end and not from
+			 * the point in time when the slot is called.
 			 *
 			 * \param streamSize The size of the stream in bytes. The special
 			 * value \c -1 is used for "unknown size".
@@ -96,9 +171,16 @@
 			 * \see setStreamSize
 			 */
 			void endOfData();
+
+			/**
+			 * \copydoc MediaObject::setAboutToFinishTime( long )
+			 */
 			void setAboutToFinishTime( long newAboutToFinishTime );
 
 		signals:
+			/**
+			 * \copydoc MediaObject::finished()
+			 */
 			void finished();
 
 			/**
@@ -111,6 +193,9 @@
 			 */
 			void aboutToFinish( long msec );
 
+			/**
+			 * \copydoc MediaObject::finished()
+			 */
 			void length( long length );
 
 			/**
[prev in list] [next in list] [prev in thread] [next in thread]