#include <gst/gstobject.h>
#include <gst/gstbuffer.h>
+#include <gst/gstbufferlist.h>
#include <gst/gstcaps.h>
#include <gst/gstevent.h>
#include <gst/gstquery.h>
typedef struct _GstPad GstPad;
+typedef struct _GstPadPrivate GstPadPrivate;
typedef struct _GstPadClass GstPadClass;
/**
/**
* GstFlowReturn:
- * @GST_FLOW_CUSTOM_SUCCESS: Elements can use values starting from
- * this to define custom success codes.
- * Since 0.10.7.
* @GST_FLOW_RESEND: Resend buffer, possibly with new caps (not
* sent yet) (unused/unimplemented).
* @GST_FLOW_OK: Data passing was ok.
* this error should post an error message with more
* details.
* @GST_FLOW_NOT_SUPPORTED: This operation is not supported.
+ * @GST_FLOW_CUSTOM_SUCCESS: Elements can use values starting from
+ * this (and higher) to define custom success
+ * codes. Since 0.10.7.
+ * @GST_FLOW_CUSTOM_SUCCESS_1: Pre-defined custom success code (define your
+ * custom success code to this to avoid compiler
+ * warnings). Since 0.10.29.
+ * @GST_FLOW_CUSTOM_SUCCESS_2: Pre-defined custom success code. Since 0.10.29.
* @GST_FLOW_CUSTOM_ERROR: Elements can use values starting from
- * this to define custom error codes. Since 0.10.7.
+ * this (and lower) to define custom error codes.
+ * Since 0.10.7.
+ * @GST_FLOW_CUSTOM_ERROR_1: Pre-defined custom error code (define your
+ * custom error code to this to avoid compiler
+ * warnings). Since 0.10.29.
+ * @GST_FLOW_CUSTOM_ERROR_2: Pre-defined custom error code. Since 0.10.29.
*
* The result of passing data to a pad.
*
* Note that the custom return values should not be exposed outside of the
* element scope and are available since 0.10.7.
*/
+/* FIXME 0.11: remove custom flow returns */
typedef enum {
/* custom success starts here */
+ GST_FLOW_CUSTOM_SUCCESS_2 = 102,
+ GST_FLOW_CUSTOM_SUCCESS_1 = 101,
GST_FLOW_CUSTOM_SUCCESS = 100,
/* core predefined */
GST_FLOW_NOT_SUPPORTED = -6,
/* custom error starts here */
- GST_FLOW_CUSTOM_ERROR = -100
+ GST_FLOW_CUSTOM_ERROR = -100,
+ GST_FLOW_CUSTOM_ERROR_1 = -101,
+ GST_FLOW_CUSTOM_ERROR_2 = -102
} GstFlowReturn;
/**
* whether an error message should be posted on the bus. Note that such
* elements may also need to post an error message in the #GST_FLOW_NOT_LINKED
* case which is not caught by this macro.
+ *
+ * Deprecated: This macro is badly named and can't be used in any real
+ * scenarios without additional checks.
*/
+#ifndef GST_DISABLE_DEPRECATED
#define GST_FLOW_IS_FATAL(ret) ((ret) <= GST_FLOW_UNEXPECTED)
+#endif
/**
* GST_FLOW_IS_SUCCESS:
* @ret: a #GstFlowReturn value
*
* Macro to test if the given #GstFlowReturn value indicates a
- * successfull result
+ * successful result
* This macro is mainly used in elements to decide if the processing
- * of a buffer was successfull.
+ * of a buffer was successful.
*
* Since: 0.10.7
+ *
+ * Deprecated: This macro is badly named and can't be used in any real
+ * scenarios without additional checks.
*/
+#ifndef GST_DISABLE_DEPRECATED
#define GST_FLOW_IS_SUCCESS(ret) ((ret) >= GST_FLOW_OK)
+#endif
-G_CONST_RETURN gchar* gst_flow_get_name (GstFlowReturn ret);
+const gchar* gst_flow_get_name (GstFlowReturn ret);
GQuark gst_flow_to_quark (GstFlowReturn ret);
/**
+ * GstPadLinkCheck:
+ * @GST_PAD_LINK_CHECK_NOTHING: Don't check hierarchy or caps compatibility.
+ * @GST_PAD_LINK_CHECK_HIERARCHY: Check the pads have same parents/grandparents.
+ * Could be omitted if it is already known that the two elements that own the
+ * pads are in the same bin.
+ * @GST_PAD_LINK_CHECK_TEMPLATE_CAPS: Check if the pads are compatible by using
+ * their template caps. This is much faster than @GST_PAD_LINK_CHECK_CAPS, but
+ * would be unsafe e.g. if one pad has %GST_CAPS_ANY.
+ * @GST_PAD_LINK_CHECK_CAPS: Check if the pads are compatible by comparing the
+ * caps returned by gst_pad_get_caps().
+ *
+ * The amount of checking to be done when linking pads. @GST_PAD_LINK_CHECK_CAPS
+ * and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are
+ * specified, expensive but safe @GST_PAD_LINK_CHECK_CAPS are performed.
+ *
+ * <warning><para>
+ * Only disable some of the checks if you are 100% certain you know the link
+ * will not fail because of hierarchy/caps compatibility failures. If uncertain,
+ * use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods
+ * for linking the pads.
+ * </para></warning>
+ *
+ * Since: 0.10.30
+ */
+
+typedef enum {
+ GST_PAD_LINK_CHECK_NOTHING = 0,
+ GST_PAD_LINK_CHECK_HIERARCHY = 1 << 0,
+ GST_PAD_LINK_CHECK_TEMPLATE_CAPS = 1 << 1,
+ GST_PAD_LINK_CHECK_CAPS = 1 << 2
+} GstPadLinkCheck;
+
+/**
+ * GST_PAD_LINK_CHECK_DEFAULT:
+ *
+ * The default checks done when linking pads (i.e. the ones used by
+ * gst_pad_link()).
+ *
+ * Since: 0.10.30
+ */
+#define GST_PAD_LINK_CHECK_DEFAULT ((GstPadLinkCheck) (GST_PAD_LINK_CHECK_HIERARCHY | GST_PAD_LINK_CHECK_CAPS))
+
+/**
* GstActivateMode:
* @GST_ACTIVATE_NONE: Pad will not handle dataflow
* @GST_ACTIVATE_PUSH: Pad handles dataflow in downstream push mode
* gst_buffer_unref() when the buffer is no longer needed.
*
* When a chain function detects an error in the data stream, it must post an
- * error on the buffer and return an appropriate #GstFlowReturn value.
+ * error on the bus and return an appropriate #GstFlowReturn value.
*
* Returns: #GST_FLOW_OK for success
*/
typedef GstFlowReturn (*GstPadChainFunction) (GstPad *pad, GstBuffer *buffer);
+
+/**
+ * GstPadChainListFunction:
+ * @pad: the sink #GstPad that performed the chain.
+ * @list: the #GstBufferList that is chained, not %NULL.
+ *
+ * A function that will be called on sinkpads when chaining buffer lists.
+ * The function typically processes the data contained in the buffer list and
+ * either consumes the data or passes it on to the internally linked pad(s).
+ *
+ * The implementer of this function receives a refcount to @list and
+ * should gst_buffer_list_unref() when the list is no longer needed.
+ *
+ * When a chainlist function detects an error in the data stream, it must
+ * post an error on the bus and return an appropriate #GstFlowReturn value.
+ *
+ * Returns: #GST_FLOW_OK for success
+ */
+typedef GstFlowReturn (*GstPadChainListFunction) (GstPad *pad, GstBufferList *list);
+
/**
* GstPadGetRangeFunction:
* @pad: the src #GstPad to perform the getrange on.
* #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);
*
* The signature of the internal pad link function.
*
- * Returns: a newly allocated #GList of pads that are linked to the given pad on
+ * Returns: (element-type Gst.Pad) (transfer container): a newly allocated #GList of pads that are linked to the given pad on
* the inside of the parent element.
*
* The caller must call g_list_free() on it after use.
*
* Deprecated: use the threadsafe #GstPadIterIntLinkFunction instead.
*/
+#ifndef GST_DISABLE_DEPRECATED
typedef GList* (*GstPadIntLinkFunction) (GstPad *pad);
+#endif
+
/**
* GstPadIterIntLinkFunction:
* @pad: a #GstPad
* @caps: the #GstCaps to fixate
*
- * Given possibly unfixed caps @caps, let @pad use its default prefered
+ * Given possibly unfixed caps @caps, let @pad use its default preferred
* format to make a fixed caps. @caps should be writable. By default this
* function will pick the first value of any ranges or lists in the caps but
* elements can override this function to perform other behaviour.
* @unlinkfunc: function called when pad is unlinked
* @peer: the pad this pad is linked to
* @sched_private: private storage for the scheduler
- * @chainfunc: function to chain data to pad
+ * @chainfunc: function to chain buffer to pad
* @checkgetrangefunc: function to check if pad can operate in pull mode
* @getrangefunc: function to get a range of data from a pad
* @eventfunc: function to send an event to a pad
* @do_buffer_signals: counter counting installed buffer signals
* @do_event_signals: counter counting installed event signals
* @iterintlinkfunc: get the internal links iterator of this pad
+ * @block_destroy_data: notify function for gst_pad_set_blocked_async_full()
*
* The #GstPad structure. Use the functions to update the variables.
*/
GstPadQueryFunction queryfunc;
/* internal links */
+#ifndef GST_DISABLE_DEPRECATED
GstPadIntLinkFunction intlinkfunc;
+#else
+#ifndef __GTK_DOC_IGNORE__
+ gpointer intlinkfunc;
+#endif
+#endif
GstPadBufferAllocFunction bufferallocfunc;
/* iterate internal links */
GstPadIterIntLinkFunction iterintlinkfunc;
+ /* free block_data */
+ GDestroyNotify block_destroy_data;
+
/*< private >*/
- gpointer _gst_reserved[GST_PADDING - 1];
+ union {
+ struct {
+ gboolean block_callback_called;
+ GstPadPrivate *priv;
+ } ABI;
+ gpointer _gst_reserved[GST_PADDING - 2];
+ } abidata;
};
struct _GstPadClass {
#define GST_PAD_EVENTFUNC(pad) (GST_PAD_CAST(pad)->eventfunc)
#define GST_PAD_QUERYTYPEFUNC(pad) (GST_PAD_CAST(pad)->querytypefunc)
#define GST_PAD_QUERYFUNC(pad) (GST_PAD_CAST(pad)->queryfunc)
+#ifndef GST_DISABLE_DEPRECATED
#define GST_PAD_INTLINKFUNC(pad) (GST_PAD_CAST(pad)->intlinkfunc)
+#endif
#define GST_PAD_ITERINTLINKFUNC(pad) (GST_PAD_CAST(pad)->iterintlinkfunc)
#define GST_PAD_PEER(pad) (GST_PAD_CAST(pad)->peer)
gboolean gst_pad_set_blocked (GstPad *pad, gboolean blocked);
gboolean gst_pad_set_blocked_async (GstPad *pad, gboolean blocked,
GstPadBlockCallback callback, gpointer user_data);
+gboolean gst_pad_set_blocked_async_full (GstPad *pad, gboolean blocked,
+ GstPadBlockCallback callback, gpointer user_data,
+ GDestroyNotify destroy_data);
gboolean gst_pad_is_blocked (GstPad *pad);
gboolean gst_pad_is_blocking (GstPad *pad);
void gst_pad_set_activatepull_function (GstPad *pad, GstPadActivateModeFunction activatepull);
void gst_pad_set_activatepush_function (GstPad *pad, GstPadActivateModeFunction activatepush);
void gst_pad_set_chain_function (GstPad *pad, GstPadChainFunction chain);
+void gst_pad_set_chain_list_function (GstPad *pad, GstPadChainListFunction chainlist);
void gst_pad_set_getrange_function (GstPad *pad, GstPadGetRangeFunction get);
void gst_pad_set_checkgetrange_function (GstPad *pad, GstPadCheckGetRangeFunction check);
void gst_pad_set_event_function (GstPad *pad, GstPadEventFunction event);
void gst_pad_set_link_function (GstPad *pad, GstPadLinkFunction link);
void gst_pad_set_unlink_function (GstPad *pad, GstPadUnlinkFunction unlink);
+gboolean gst_pad_can_link (GstPad *srcpad, GstPad *sinkpad);
GstPadLinkReturn gst_pad_link (GstPad *srcpad, GstPad *sinkpad);
+GstPadLinkReturn gst_pad_link_full (GstPad *srcpad, GstPad *sinkpad, GstPadLinkCheck flags);
gboolean gst_pad_unlink (GstPad *srcpad, GstPad *sinkpad);
gboolean gst_pad_is_linked (GstPad *pad);
void gst_pad_set_fixatecaps_function (GstPad *pad, GstPadFixateCapsFunction fixatecaps);
void gst_pad_set_setcaps_function (GstPad *pad, GstPadSetCapsFunction setcaps);
-G_CONST_RETURN GstCaps* gst_pad_get_pad_template_caps (GstPad *pad);
+const GstCaps* gst_pad_get_pad_template_caps (GstPad *pad);
/* capsnego function for linked/unlinked pads */
+GstCaps * gst_pad_get_caps_reffed (GstPad * pad);
GstCaps * gst_pad_get_caps (GstPad * pad);
void gst_pad_fixate_caps (GstPad * pad, GstCaps *caps);
gboolean gst_pad_accept_caps (GstPad * pad, GstCaps *caps);
gboolean gst_pad_set_caps (GstPad * pad, GstCaps *caps);
+GstCaps * gst_pad_peer_get_caps_reffed (GstPad * pad);
GstCaps * gst_pad_peer_get_caps (GstPad * pad);
gboolean gst_pad_peer_accept_caps (GstPad * pad, GstCaps *caps);
/* data passing functions to peer */
GstFlowReturn gst_pad_push (GstPad *pad, GstBuffer *buffer);
+GstFlowReturn gst_pad_push_list (GstPad *pad, GstBufferList *list);
gboolean gst_pad_check_pull_range (GstPad *pad);
GstFlowReturn gst_pad_pull_range (GstPad *pad, guint64 offset, guint size,
GstBuffer **buffer);
/* data passing functions on pad */
GstFlowReturn gst_pad_chain (GstPad *pad, GstBuffer *buffer);
+GstFlowReturn gst_pad_chain_list (GstPad *pad, GstBufferList *list);
GstFlowReturn gst_pad_get_range (GstPad *pad, guint64 offset, guint size,
GstBuffer **buffer);
gboolean gst_pad_send_event (GstPad *pad, GstEvent *event);
gboolean gst_pad_stop_task (GstPad *pad);
/* internal links */
+#ifndef GST_DISABLE_DEPRECATED
void gst_pad_set_internal_link_function (GstPad *pad, GstPadIntLinkFunction intlink);
GList* gst_pad_get_internal_links (GstPad *pad);
GList* gst_pad_get_internal_links_default (GstPad *pad);
+#endif
void gst_pad_set_iterate_internal_links_function (GstPad * pad,
GstPadIterIntLinkFunction iterintlink);
/* generic query function */
void gst_pad_set_query_type_function (GstPad *pad, GstPadQueryTypeFunction type_func);
-G_CONST_RETURN GstQueryType*
- gst_pad_get_query_types (GstPad *pad);
-G_CONST_RETURN GstQueryType*
- gst_pad_get_query_types_default (GstPad *pad);
+const GstQueryType* gst_pad_get_query_types (GstPad *pad);
+const GstQueryType* gst_pad_get_query_types_default (GstPad *pad);
gboolean gst_pad_query (GstPad *pad, GstQuery *query);
gboolean gst_pad_peer_query (GstPad *pad, GstQuery *query);
gboolean gst_pad_dispatcher (GstPad *pad, GstPadDispatcherFunction dispatch,
gpointer data);
-#ifndef GST_DISABLE_LOADSAVE
+#if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_DISABLE_DEPRECATED)
void gst_pad_load_and_link (xmlNodePtr self, GstObject *parent);
#endif