// Copyright 2013 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.

#ifndef NET_TOOLS_BALSA_BUFFER_INTERFACE_H__
#define NET_TOOLS_BALSA_BUFFER_INTERFACE_H__

namespace net {

class BufferInterface {
 public:

  //   Returns the bytes which can be read from the buffer.  There is no
  //   guarantee that the bytes are contiguous.
  virtual int ReadableBytes() const = 0;

  // Summary:
  //   returns the size of this buffer
  // Returns:
  //   size of this buffer.
  virtual int BufferSize() const = 0;

  // Summary:
  //   returns the number of bytes free in this buffer.
  // Returns:
  //   number of bytes free.
  virtual int BytesFree() const = 0;

  // Summary:
  //   Returns true if empty.
  // Returns:
  //   true - if empty
  //   false - otherwise
  virtual bool Empty() const = 0;

  // Summary:
  //   Returns true if the buffer is full.
  virtual bool Full() const = 0;

  // Summary:
  //   returns the number of characters written.
  //   appends up-to-'size' bytes to the buffer.
  // Args:
  //   bytes - bytes which are read, and copied into the buffer.
  //   size  - number of bytes which are read and copied.
  //           this number shall be >= 0.
  virtual int Write(const char* bytes, int size) = 0;

  // Summary:
  //   Gets a pointer which can be written to (assigned to).
  //   this pointer (and size) can be used in functions like
  //   recv() or read(), etc.
  //   If *size is zero upon returning from this function, that it
  //   is unsafe to dereference *ptr.
  // Args:
  //   ptr - assigned a pointer to which we can write
  //   size - the amount of data (in bytes) that it is safe to write to ptr.
  virtual void GetWritablePtr(char **ptr, int* size) const = 0;

  // Summary:
  //   Gets a pointer which can be read from
  //   this pointer (and size) can be used in functions like
  //   send() or write(), etc.
  //   If *size is zero upon returning from this function, that it
  //   is unsafe to dereference *ptr.
  // Args:
  //   ptr - assigned a pointer from which we may read
  //   size - the amount of data (in bytes) that it is safe to read
  virtual void GetReadablePtr(char **ptr, int* size) const = 0;

  // Summary:
  //   Reads bytes out of the buffer, and writes them into 'bytes'.
  //   Returns the number of bytes read.
  //   Consumes bytes from the buffer (possibly, but not necessarily
  //   rendering them free)
  // Args:
  //   bytes - the pointer into which bytes are read from this buffer
  //           and written into
  //   size  - number of bytes which are read and copied.
  //           this number shall be >= 0.
  // Returns:
  //   the number of bytes read from 'bytes'
  virtual int Read(char* bytes, int size) = 0;

  // Summary:
  //   removes all data from the buffer
  virtual void Clear() = 0;

  // Summary:
  //   reserves contiguous writable empty space in the buffer of size bytes.
  //   Returns true if the reservation is successful.
  //   If a derive class chooses not to implement reservation, its
  //   implementation should return false.
  virtual bool Reserve(int size) = 0;

  // Summary:
  //   removes the oldest 'amount_to_consume' characters from this buffer,
  // Args:
  //   amount_to_advance - .. this should be self-explanatory =)
  //                       this number shall be >= 0.
  virtual void AdvanceReadablePtr(int amount_to_advance) = 0;

  // Summary:
  //   Moves the internal pointers around such that the
  //   amount of data specified here is expected to
  //   already be resident (as if it was Written)
  // Args:
  //   amount_to_advance - self explanatory.
  //                       this number shall be >= 0.
  virtual void AdvanceWritablePtr(int amount_to_advance) = 0;

  virtual ~BufferInterface() {}

 protected:
  BufferInterface() {}
};

}  // namespace net

#endif  // NET_TOOLS_BALSA_BUFFER_INTERFACE__H__