libtizplatform: add 'tiz_buffer_seek', 'tiz_buffer_offset' and 'tiz_buffer_overwrite_mode' apis

[juanrubio]

/* The possibilities for the third argument to 'tiz_buffer_seek'.
   These values should not be changed.  */
#define TIZ_BUFFER_SEEK_SET 0 /** Seek from beginning of buffer.  */
#define TIZ_BUFFER_SEEK_CUR 1 /** Seek from current position.  */
#define TIZ_BUFFER_SEEK_END 2 /** Seek from end of data.  */

/* The possibilities for the third argument to 'tiz_buffer_overwrite_mode'.
   These values should not be changed.  */
#define TIZ_BUFFER_OVERWRITE_ON_PUSH \
  0 /** During push operations, data behind the current position marker gets
        lost. This is the default mode of operation. */
#define TIZ_BUFFER_OVERWRITE_NEVER \
  1 /** Data behind the current position marker is not lost. */

/**
 * @brief Retrieve the current position marker.
 *
 * @ingroup tizbuffer
 * @param ap_buf The  buffer handle.
 * @return The offset in bytes that marks the current position in the buffer.
 */
int
tiz_buffer_offset (const tiz_buffer_t * ap_buf);

/**
 * Set a new overwrite mode.
 *
 * @ingroup tizbuffer
 * @param ap_buf The dynamic buffer handle.
 * @param a_overwrite_mode TIZ_BUFFER_OVERWRITE_ON_PUSH (default) or
 * TIZ_BUFFER_OVERWRITE_NEVER.
 * @return The old overwrite mode, or -1 on error.
 */
int
tiz_buffer_overwrite_mode (tiz_buffer_t * ap_buf, const int a_overwrite_mode);


/**
 * @brief Re-position the buffer marker.
 *
 * The new position, measured in bytes, is obtained by adding offset bytes to
 * the position specified by whence. If whence is set to TIZ_BUFFER_SEEK_SET,
 * TIZ_BUFFER_SEEK_CUR, or TIZ_BUFFER_SEEK_END, the offset is relative to the
 * start of the buffer, the current position indicator, or end-of-data marker,
 * respectively.
 *
 * @ingroup tizbuffer
 * @param ap_buf The dynamic buffer handle.
 * @param a_offset The new position is obtained by adding a_offset bytes to the
 * position specified by a_whence.
 * @param a_whence TIZ_BUFFER_SEEK_SET, TIZ_BUFFER_SEEK_CUR, or
 * TIZ_BUFFER_SEEK_END.
 * @return 0 on success, -1 on error (e.g. the whence argument was not
 * TIZ_BUFFER_SEEK_SET, TIZ_BUFFER_SEEK_END, or TIZ_BUFFER_SEEK_CUR.  Or the
 * resulting buffer offset would be negative).
 */
int
tiz_buffer_seek (tiz_buffer_t * ap_buf, const long a_offset,
                 const int a_whence);