docs: clarify the pull_range functions

Clarify the gst_pad_pull_range(), GstBaseSrc::create(), gst_pad_get_range()
and GstPadGetRange functions a little.

Fixes #617733

3 files changed, 15 insertions, 5 deletions

diff --git a/gst/gstpad.c b/gst/gstpad.c
index 17fc0cc460..00dca74af8 100644
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -4588,7 +4588,7 @@ not_connected:
  * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
  *
  * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
- * immediatly.
+ * immediatly and @buffer is %NULL.
  *
  * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
  * description of a getrange function. If @pad has no getrange function
diff --git a/gst/gstpad.h b/gst/gstpad.h
index 9fc556874e..56e4320b01 100644
--- a/gst/gstpad.h
+++ b/gst/gstpad.h
@@ -291,8 +291,9 @@ typedef GstFlowReturn		(*GstPadChainListFunction)	(GstPad *pad, GstBufferList *l
  * #GST_FLOW_UNEXPECTED, which corresponds to EOS. In this case @buffer does not
  * contain a valid buffer.
  *
- * The buffer size of @buffer might be smaller than @length when @offset is near
- * the end of the stream.
+ * The buffer size of @buffer will only be smaller than @length when @offset is
+ * near the end of the stream. In all other cases, the size of @buffer must be
+ * exactly the requested size.
  *
  * It is allowed to call this function with a 0 @length and valid @offset, in
  * which case @buffer will contain a 0-sized buffer and the function returns
@@ -305,7 +306,8 @@ typedef GstFlowReturn		(*GstPadChainListFunction)	(GstPad *pad, GstBufferList *l
  * optimal length is returned in @buffer. The length might depend on the value
  * of @offset.
  *
- * Returns: #GST_FLOW_OK for success
+ * Returns: #GST_FLOW_OK for success and a valid buffer in @buffer. Any other
+ * return value leaves @buffer undefined.
  */
 typedef GstFlowReturn		(*GstPadGetRangeFunction)	(GstPad *pad, guint64 offset,
 		                                                 guint length, GstBuffer **buffer);
diff --git a/libs/gst/base/gstbasesrc.h b/libs/gst/base/gstbasesrc.h
index d9f39d9a74..854cf6b9b5 100644
--- a/libs/gst/base/gstbasesrc.h
+++ b/libs/gst/base/gstbasesrc.h
@@ -132,11 +132,19 @@ struct _GstBaseSrc {
  * @get_size: Return the total size of the resource, in the configured format.
  * @is_seekable: Check if the source can seek
  * @unlock: Unlock any pending access to the resource. Subclasses should
- *    unblock any blocked function ASAP
+ *    unblock any blocked function ASAP. In particular, any create() function in
+ *    progress should be unblocked and should return GST_FLOW_WRONG_STATE. Any
+ *    future create() function call should also return GST_FLOW_WRONG_STATE
+ *    until the unlock_stop() function has been called.
  * @unlock_stop: Clear the previous unlock request. Subclasses should clear
  *    any state they set during unlock(), such as clearing command queues.
  * @event: Override this to implement custom event handling.
  * @create: Ask the subclass to create a buffer with offset and size.
+ *   When the subclass returns GST_FLOW_OK, it MUST return a buffer of the
+ *   requested size unless fewer bytes are available because an EOS condition
+ *   is near. No buffer should be returned when the return value is different
+ *   from GST_FLOW_OK. A return value of GST_FLOW_UNEXPECTED signifies that the
+ *   end of stream is reached.
  * @do_seek: Perform seeking on the resource to the indicated segment.
  * @prepare_seek_segment: Prepare the GstSegment that will be passed to the
  *   do_seek vmethod for executing a seek request. Sub-classes should override