* @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
* #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
* 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);
* @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