media/base/seekable_buffer.h - chromium/src - Git at Google

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 // SeekableBuffer to support backward and forward seeking in a buffer for
 // reading a media data source.
 //
 // In order to support backward and forward seeking, this class buffers data in
 // both backward and forward directions, the current read position can be reset
 // to anywhere in the buffered data.
 //
 // The amount of data buffered is regulated by two variables at construction,
 // |backward_capacity| and |forward_capacity|.
 //
 // In the case of reading and seeking forward, the current read position
 // advances and there will be more data in the backward direction. If backward
 // bytes exceeds |backward_capacity|, the exceeding bytes are evicted and thus
 // backward_bytes() will always be less than or equal to |backward_capacity|.
 // The eviction will be caused by Read() and Seek() in the forward direction and
 // is done internally when the mentioned criteria is fulfilled.
 //
 // In the case of appending data to the buffer, there is an advisory limit of
 // how many bytes can be kept in the forward direction, regulated by
 // |forward_capacity|. The append operation (by calling Append()) that caused
 // forward bytes to exceed |forward_capacity| will have a return value that
 // advises a halt of append operation, further append operations are allowed but
 // are not advised. Since this class is used as a backend buffer for caching
 // media files downloaded from network we cannot afford losing data, we can
 // only advise a halt of further writing to this buffer.
 // This class is not inherently thread-safe. Concurrent access must be
 // externally serialized.

 #ifndef MEDIA_BASE_SEEKABLE_BUFFER_H_
 #define MEDIA_BASE_SEEKABLE_BUFFER_H_

 #include <stdint.h>

 #include <list>

 #include "base/macros.h"
 #include "base/memory/ref_counted.h"
 #include "base/time/time.h"
 #include "media/base/media_export.h"

 namespace media {

 class DataBuffer;

 class MEDIA_EXPORT SeekableBuffer {
  public:
   // Constructs an instance with |forward_capacity| and |backward_capacity|.
   // The values are in bytes.
   SeekableBuffer(int backward_capacity, int forward_capacity);

   ~SeekableBuffer();

   // Clears the buffer queue.
   void Clear();

   // Reads a maximum of |size| bytes into |data| from the current read
   // position. Returns the number of bytes read.
   // The current read position will advance by the amount of bytes read. If
   // reading caused backward_bytes() to exceed backward_capacity(), an eviction
   // of the backward buffer will be done internally.
   int Read(uint8_t* data, int size);

   // Copies up to |size| bytes from current position to |data|. Returns
   // number of bytes copied. Doesn't advance current position. Optionally
   // starts at a |forward_offset| from current position.
   int Peek(uint8_t* data, int size) { return Peek(data, size, 0); }
   int Peek(uint8_t* data, int size, int forward_offset);

   // Returns pointer to the current chunk of data that is being consumed.
   // If there is no data left in the buffer false is returned, otherwise
   // true is returned and |data| and |size| are updated. The returned
   // |data| value becomes invalid when Read(), Append() or Seek()
   // are called.
   bool GetCurrentChunk(const uint8_t** data, int* size) const;

   // Appends |buffer_in| to this buffer. Returns false if forward_bytes() is
   // greater than or equals to forward_capacity(), true otherwise. The data
   // is added to the buffer in any case.
   bool Append(const scoped_refptr<DataBuffer>& buffer_in);

   // Appends |size| bytes of |data| to the buffer. Result is the same
   // as for Append(Buffer*).
   bool Append(const uint8_t* data, int size);

   // Moves the read position by |offset| bytes. If |offset| is positive, the
   // current read position is moved forward. If negative, the current read
   // position is moved backward. A zero |offset| value will keep the current
   // read position stationary.
   // If |offset| exceeds bytes buffered in either direction, reported by
   // forward_bytes() when seeking forward and backward_bytes() when seeking
   // backward, the seek operation will fail and return value will be false.
   // If the seek operation fails, the current read position will not be updated.
   // If a forward seeking caused backward_bytes() to exceed backward_capacity(),
   // this method call will cause an eviction of the backward buffer.
   bool Seek(int32_t offset);

   // Returns the number of bytes buffered beyond the current read position.
   int forward_bytes() const { return forward_bytes_; }

   // Returns the number of bytes buffered that precedes the current read
   // position.
   int backward_bytes() const { return backward_bytes_; }

   // Sets the forward_capacity to |new_forward_capacity| bytes.
   void set_forward_capacity(int new_forward_capacity) {
     forward_capacity_ = new_forward_capacity;
   }

   // Sets the backward_capacity to |new_backward_capacity| bytes.
   void set_backward_capacity(int new_backward_capacity) {
     backward_capacity_ = new_backward_capacity;
   }

   // Returns the maximum number of bytes that should be kept in the forward
   // direction.
   int forward_capacity() const { return forward_capacity_; }

   // Returns the maximum number of bytes that should be kept in the backward
   // direction.
   int backward_capacity() const { return backward_capacity_; }

   // Returns the current timestamp, taking into account current offset. The
   // value calculated based on the timestamp of the current buffer. If
   // timestamp for the current buffer is set to 0 or the data was added with
   // Append(const uint*, int), then returns value that corresponds to the
   // last position in a buffer that had timestamp set.
   // kNoTimestamp is returned if no buffers we read from had timestamp set.
   base::TimeDelta current_time() const { return current_time_; }

  private:
   // Definition of the buffer queue.
   typedef std::list<scoped_refptr<DataBuffer> > BufferQueue;

   // A helper method to evict buffers in the backward direction until backward
   // bytes is within the backward capacity.
   void EvictBackwardBuffers();

   // An internal method shared by Read() and SeekForward() that actually does
   // reading. It reads a maximum of |size| bytes into |data|. Returns the number
   // of bytes read. The current read position will be moved forward by the
   // number of bytes read. If |data| is NULL, only the current read position
   // will advance but no data will be copied.
   int InternalRead(uint8_t* data,
                    int size,
                    bool advance_position,
                    int forward_offset);

   // A helper method that moves the current read position forward by |size|
   // bytes.
   // If the return value is true, the operation completed successfully.
   // If the return value is false, |size| is greater than forward_bytes() and
   // the seek operation failed. The current read position is not updated.
   bool SeekForward(int size);

   // A helper method that moves the current read position backward by |size|
   // bytes.
   // If the return value is true, the operation completed successfully.
   // If the return value is false, |size| is greater than backward_bytes() and
   // the seek operation failed. The current read position is not updated.
   bool SeekBackward(int size);

   // Updates |current_time_| with the time that corresponds to the
   // specified position in the buffer.
   void UpdateCurrentTime(BufferQueue::iterator buffer, int offset);

   BufferQueue::iterator current_buffer_;
   BufferQueue buffers_;
   int current_buffer_offset_;

   int backward_capacity_;
   int backward_bytes_;

   int forward_capacity_;
   int forward_bytes_;

   // Keeps track of the most recent time we've seen in case the |buffers_| is
   // empty when our owner asks what time it is.
   base::TimeDelta current_time_;

   DISALLOW_COPY_AND_ASSIGN(SeekableBuffer);
 };

 }  // namespace media

 #endif  // MEDIA_BASE_SEEKABLE_BUFFER_H_
	// Copyright (c) 2012 The Chromium Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	// SeekableBuffer to support backward and forward seeking in a buffer for
	// reading a media data source.
	//
	// In order to support backward and forward seeking, this class buffers data in
	// both backward and forward directions, the current read position can be reset
	// to anywhere in the buffered data.
	//
	// The amount of data buffered is regulated by two variables at construction,
	// \|backward_capacity\| and \|forward_capacity\|.
	//
	// In the case of reading and seeking forward, the current read position
	// advances and there will be more data in the backward direction. If backward
	// bytes exceeds \|backward_capacity\|, the exceeding bytes are evicted and thus
	// backward_bytes() will always be less than or equal to \|backward_capacity\|.
	// The eviction will be caused by Read() and Seek() in the forward direction and
	// is done internally when the mentioned criteria is fulfilled.
	//
	// In the case of appending data to the buffer, there is an advisory limit of
	// how many bytes can be kept in the forward direction, regulated by
	// \|forward_capacity\|. The append operation (by calling Append()) that caused
	// forward bytes to exceed \|forward_capacity\| will have a return value that
	// advises a halt of append operation, further append operations are allowed but
	// are not advised. Since this class is used as a backend buffer for caching
	// media files downloaded from network we cannot afford losing data, we can
	// only advise a halt of further writing to this buffer.
	// This class is not inherently thread-safe. Concurrent access must be
	// externally serialized.

	#ifndef MEDIA_BASE_SEEKABLE_BUFFER_H_
	#define MEDIA_BASE_SEEKABLE_BUFFER_H_

	#include <stdint.h>

	#include <list>

	#include "base/macros.h"
	#include "base/memory/ref_counted.h"
	#include "base/time/time.h"
	#include "media/base/media_export.h"

	namespace media {

	class DataBuffer;

	class MEDIA_EXPORT SeekableBuffer {
	public:
	// Constructs an instance with \|forward_capacity\| and \|backward_capacity\|.
	// The values are in bytes.
	SeekableBuffer(int backward_capacity, int forward_capacity);

	~SeekableBuffer();

	// Clears the buffer queue.
	void Clear();

	// Reads a maximum of \|size\| bytes into \|data\| from the current read
	// position. Returns the number of bytes read.
	// The current read position will advance by the amount of bytes read. If
	// reading caused backward_bytes() to exceed backward_capacity(), an eviction
	// of the backward buffer will be done internally.
	int Read(uint8_t* data, int size);

	// Copies up to \|size\| bytes from current position to \|data\|. Returns
	// number of bytes copied. Doesn't advance current position. Optionally
	// starts at a \|forward_offset\| from current position.
	int Peek(uint8_t* data, int size) { return Peek(data, size, 0); }
	int Peek(uint8_t* data, int size, int forward_offset);

	// Returns pointer to the current chunk of data that is being consumed.
	// If there is no data left in the buffer false is returned, otherwise
	// true is returned and \|data\| and \|size\| are updated. The returned
	// \|data\| value becomes invalid when Read(), Append() or Seek()
	// are called.
	bool GetCurrentChunk(const uint8_t** data, int* size) const;

	// Appends \|buffer_in\| to this buffer. Returns false if forward_bytes() is
	// greater than or equals to forward_capacity(), true otherwise. The data
	// is added to the buffer in any case.
	bool Append(const scoped_refptr<DataBuffer>& buffer_in);

	// Appends \|size\| bytes of \|data\| to the buffer. Result is the same
	// as for Append(Buffer*).
	bool Append(const uint8_t* data, int size);

	// Moves the read position by \|offset\| bytes. If \|offset\| is positive, the
	// current read position is moved forward. If negative, the current read
	// position is moved backward. A zero \|offset\| value will keep the current
	// read position stationary.
	// If \|offset\| exceeds bytes buffered in either direction, reported by
	// forward_bytes() when seeking forward and backward_bytes() when seeking
	// backward, the seek operation will fail and return value will be false.
	// If the seek operation fails, the current read position will not be updated.
	// If a forward seeking caused backward_bytes() to exceed backward_capacity(),
	// this method call will cause an eviction of the backward buffer.
	bool Seek(int32_t offset);

	// Returns the number of bytes buffered beyond the current read position.
	int forward_bytes() const { return forward_bytes_; }

	// Returns the number of bytes buffered that precedes the current read
	// position.
	int backward_bytes() const { return backward_bytes_; }

	// Sets the forward_capacity to \|new_forward_capacity\| bytes.
	void set_forward_capacity(int new_forward_capacity) {
	forward_capacity_ = new_forward_capacity;
	}

	// Sets the backward_capacity to \|new_backward_capacity\| bytes.
	void set_backward_capacity(int new_backward_capacity) {
	backward_capacity_ = new_backward_capacity;
	}

	// Returns the maximum number of bytes that should be kept in the forward
	// direction.
	int forward_capacity() const { return forward_capacity_; }

	// Returns the maximum number of bytes that should be kept in the backward
	// direction.
	int backward_capacity() const { return backward_capacity_; }

	// Returns the current timestamp, taking into account current offset. The
	// value calculated based on the timestamp of the current buffer. If
	// timestamp for the current buffer is set to 0 or the data was added with
	// Append(const uint*, int), then returns value that corresponds to the
	// last position in a buffer that had timestamp set.
	// kNoTimestamp is returned if no buffers we read from had timestamp set.
	base::TimeDelta current_time() const { return current_time_; }

	private:
	// Definition of the buffer queue.
	typedef std::list<scoped_refptr<DataBuffer> > BufferQueue;

	// A helper method to evict buffers in the backward direction until backward
	// bytes is within the backward capacity.
	void EvictBackwardBuffers();

	// An internal method shared by Read() and SeekForward() that actually does
	// reading. It reads a maximum of \|size\| bytes into \|data\|. Returns the number
	// of bytes read. The current read position will be moved forward by the
	// number of bytes read. If \|data\| is NULL, only the current read position
	// will advance but no data will be copied.
	int InternalRead(uint8_t* data,
	int size,
	bool advance_position,
	int forward_offset);

	// A helper method that moves the current read position forward by \|size\|
	// bytes.
	// If the return value is true, the operation completed successfully.
	// If the return value is false, \|size\| is greater than forward_bytes() and
	// the seek operation failed. The current read position is not updated.
	bool SeekForward(int size);

	// A helper method that moves the current read position backward by \|size\|
	// bytes.
	// If the return value is true, the operation completed successfully.
	// If the return value is false, \|size\| is greater than backward_bytes() and
	// the seek operation failed. The current read position is not updated.
	bool SeekBackward(int size);

	// Updates \|current_time_\| with the time that corresponds to the
	// specified position in the buffer.
	void UpdateCurrentTime(BufferQueue::iterator buffer, int offset);

	BufferQueue::iterator current_buffer_;
	BufferQueue buffers_;
	int current_buffer_offset_;

	int backward_capacity_;
	int backward_bytes_;

	int forward_capacity_;
	int forward_bytes_;

	// Keeps track of the most recent time we've seen in case the \|buffers_\| is
	// empty when our owner asks what time it is.
	base::TimeDelta current_time_;

	DISALLOW_COPY_AND_ASSIGN(SeekableBuffer);
	};

	} // namespace media

	#endif // MEDIA_BASE_SEEKABLE_BUFFER_H_