[vlc-commits] stream: clarify seeking documentation

[Rémi Denis-Courmont]

vlc/vlc-3.0 | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Thu Nov 30 18:30:23 2017 +0200| [c4a667202a1b3a0d3db8d138242c3066c1c250bc] | committer: Jean-Baptiste Kempf

stream: clarify seeking documentation

(cherry picked from commit ad303c60a766c417ccdc8968e83a181ce6a7d963)
Signed-off-by: Jean-Baptiste Kempf <jb at videolan.org>

> http://git.videolan.org/gitweb.cgi/vlc/vlc-3.0.git/?a=commit;h=c4a667202a1b3a0d3db8d138242c3066c1c250bc
---

 include/vlc_stream.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/include/vlc_stream.h b/include/vlc_stream.h
index badee554dc..789545e16e 100644
--- a/include/vlc_stream.h
+++ b/include/vlc_stream.h
@@ -238,6 +238,11 @@ VLC_API block_t *vlc_stream_ReadBlock(stream_t *) VLC_USED;
 /**
  * Tells the current stream position.
  *
+ * This function tells the current read offset (in bytes) from the start of
+ * the start of the stream.
+ * @note The read offset may be larger than the stream size, either because of
+ * a seek past the end, or because the stream shrank asynchronously.
+ *
  * @return the byte offset from the beginning of the stream (cannot fail)
  */
 VLC_API uint64_t vlc_stream_Tell(const stream_t *) VLC_USED;
@@ -267,6 +272,11 @@ VLC_API bool vlc_stream_Eof(const stream_t *) VLC_USED;
 /**
  * Sets the current stream position.
  *
+ * This function changes the read offset within a stream, if the stream
+ * supports seeking. In case of error, the read offset is not changed.
+ *
+ * @note It is possible (but not useful) to seek past the end of a stream.
+ *
  * @param offset byte offset from the beginning of the stream
  * @return zero on success, a negative value on error
  */