/* GStreamer

 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>

 *                    2000 Wim Taymans <wim.taymans@chello.be>

 *

 * gstpad.h: Header for GstPad object

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Library General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Library General Public License for more details.

 *

 * You should have received a copy of the GNU Library General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

#ifndef __GST_PAD_H__

#define __GST_PAD_H__

#include <gst/gstconfig.h>

#include <gst/gstobject.h>

#include <gst/gstbuffer.h>

#include <gst/gstcaps.h>

#include <gst/gstevent.h>

#include <gst/gstquery.h>

#include <gst/gsttask.h>

G_BEGIN_DECLS

/*

 * Pad base class

 */

#define GST_TYPE_PAD			(gst_pad_get_type ())

#define GST_IS_PAD(obj)			(G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PAD))

#define GST_IS_PAD_CLASS(klass)		(G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PAD))

#define GST_PAD(obj)			(G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PAD, GstPad))

#define GST_PAD_CLASS(klass)		(G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PAD, GstPadClass))

#define GST_PAD_CAST(obj)		((GstPad*)(obj))

typedef struct _GstPad GstPad;

typedef struct _GstPadClass GstPadClass;

/**

 * GstPadLinkReturn:

 * @GST_PAD_LINK_OK		: link succeeded

 * @GST_PAD_LINK_WRONG_HIERARCHY: pads have no common grandparent

 * @GST_PAD_LINK_WAS_LINKED	: pad was already linked

 * @GST_PAD_LINK_WRONG_DIRECTION: pads have wrong direction

 * @GST_PAD_LINK_NOFORMAT	: pads do not have common format

 * @GST_PAD_LINK_NOSCHED	: pads cannot cooperate in scheduling

 * @GST_PAD_LINK_REFUSED	: refused for some reason

 *

 * Result values from gst_pad_link and friends.

 */

typedef enum {

  GST_PAD_LINK_OK               =  0,

  GST_PAD_LINK_WRONG_HIERARCHY  = -1,

  GST_PAD_LINK_WAS_LINKED       = -2,

  GST_PAD_LINK_WRONG_DIRECTION  = -3,

  GST_PAD_LINK_NOFORMAT         = -4,

  GST_PAD_LINK_NOSCHED          = -5,

  GST_PAD_LINK_REFUSED          = -6

} GstPadLinkReturn;

/**

 * GST_PAD_LINK_FAILED:

 * @ret: the #GstPadLinkReturn value

 *

 * Macro to test if the given #GstPadLinkReturn value indicates a failed

 * link step.

 */

#define GST_PAD_LINK_FAILED(ret) ((ret) < GST_PAD_LINK_OK)

/**

 * GST_PAD_LINK_SUCCESSFUL:

 * @ret: the #GstPadLinkReturn value

 *

 * Macro to test if the given #GstPadLinkReturn value indicates a successful

 * link step.

 */

#define GST_PAD_LINK_SUCCESSFUL(ret) ((ret) >= GST_PAD_LINK_OK)

/**

 * 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.

 * @GST_FLOW_NOT_LINKED:	 Pad is not linked.

 * @GST_FLOW_WRONG_STATE:	 Pad is in wrong state.

 * @GST_FLOW_UNEXPECTED:	 Did not expect anything, like after EOS.

 * @GST_FLOW_NOT_NEGOTIATED:	 Pad is not negotiated.

 * @GST_FLOW_ERROR:		 Some (fatal) error occured. Element generating

 *                               this error should post an error message with more

 *                               details.

 * @GST_FLOW_NOT_SUPPORTED:	 This operation is not supported.

 * @GST_FLOW_CUSTOM_ERROR:	 Elements can use values starting from

 *                               this to define custom error codes. Since 0.10.7.

 *

 * 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.

 */

typedef enum {

  /* custom success starts here */

  GST_FLOW_CUSTOM_SUCCESS = 100,

  /* core predefined */

  GST_FLOW_RESEND	  =  1,

  GST_FLOW_OK		  =  0,

  /* expected failures */

  GST_FLOW_NOT_LINKED     = -1,

  GST_FLOW_WRONG_STATE    = -2,

  /* error cases */

  GST_FLOW_UNEXPECTED     = -3,

  GST_FLOW_NOT_NEGOTIATED = -4,

  GST_FLOW_ERROR	  = -5,

  GST_FLOW_NOT_SUPPORTED  = -6,

  /* custom error starts here */

  GST_FLOW_CUSTOM_ERROR   = -100

} GstFlowReturn;

/**

 * GST_FLOW_IS_FATAL:

 * @ret: a #GstFlowReturn value

 *

 * Macro to test if the given #GstFlowReturn value indicates a fatal

 * error. This macro is mainly used in elements driving the pipeline to decide

 * 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.

 */

#define GST_FLOW_IS_FATAL(ret) ((ret) <= GST_FLOW_UNEXPECTED)

/**

 * GST_FLOW_IS_SUCCESS:

 * @ret: a #GstFlowReturn value

 *

 * Macro to test if the given #GstFlowReturn value indicates a

 * successfull result

 * This macro is mainly used in elements to decide if the processing

 * of a buffer was successfull.

 *

 * Since: 0.10.7

 */

#define GST_FLOW_IS_SUCCESS(ret) ((ret) >= GST_FLOW_OK)

G_CONST_RETURN gchar*	gst_flow_get_name	(GstFlowReturn ret);

#ifdef __SYMBIAN32__

IMPORT_C

#endif

GQuark			gst_flow_to_quark	(GstFlowReturn ret);

/**

 * GstActivateMode:

 * @GST_ACTIVATE_NONE:	  	 Pad will not handle dataflow

 * @GST_ACTIVATE_PUSH:		 Pad handles dataflow in downstream push mode

 * @GST_ACTIVATE_PULL:     	 Pad handles dataflow in upstream pull mode

 *

 * The status of a GstPad. After activating a pad, which usually happens when the

 * parent element goes from READY to PAUSED, the GstActivateMode defines if the

 * pad operates in push or pull mode.

 */

typedef enum {

  GST_ACTIVATE_NONE,

  GST_ACTIVATE_PUSH,

  GST_ACTIVATE_PULL

} GstActivateMode;

/**

 * GST_PAD_MODE_ACTIVATE:

 * @mode: a #GstActivateMode

 *

 * Macro to test if the given #GstActivateMode value indicates that datapassing

 * is possible or not.

 */

#define GST_PAD_MODE_ACTIVATE(mode) ((mode) != GST_ACTIVATE_NONE)

/* pad states */

/**

 * GstPadActivateFunction:

 * @pad: a #GstPad

 *

 * This function is called when the pad is activated during the element

 * READY to PAUSED state change. By default this function will call the

 * activate function that puts the pad in push mode but elements can

 * override this function to activate the pad in pull mode if they wish.

 *

 * Returns: TRUE if the pad could be activated.

 */

typedef gboolean		(*GstPadActivateFunction)	(GstPad *pad);

/**

 * GstPadActivateModeFunction:

 * @pad: a #GstPad

 * @active: activate or deactivate the pad.

 *

 * The prototype of the push and pull activate functions.

 *

 * Returns: TRUE if the pad could be activated or deactivated.

 */

typedef gboolean		(*GstPadActivateModeFunction)	(GstPad *pad, gboolean active);

/* data passing */

/**

 * GstPadChainFunction:

 * @pad: the sink #GstPad that performed the chain.

 * @buffer: the #GstBuffer that is chained, not %NULL.

 *

 * A function that will be called on sinkpads when chaining buffers.

 * The function typically processes the data contained in the buffer and

 * either consumes the data or passes it on to the internally linked pad(s).

 *

 * The implementer of this function receives a refcount to @buffer and should

 * 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

 *

 * Returns: #GST_FLOW_OK for success

 */

typedef GstFlowReturn		(*GstPadChainFunction)		(GstPad *pad, GstBuffer *buffer);

/**

 * GstPadGetRangeFunction:

 * @pad: the src #GstPad to perform the getrange on.

 * @offset: the offset of the range

 * @length: the length of the range

 * @buffer: a memory location to hold the result buffer, cannot be NULL.

 *

 * This function will be called on source pads when a peer element

 * request a buffer at the specified @offset and @length. If this function

 * returns #GST_FLOW_OK, the result buffer will be stored in @buffer. The

 * contents of @buffer is invalid for any other return value.

 *

 * This function is installed on a source pad with

 * gst_pad_set_getrange_function() and can only be called on source pads after

 * they are successfully activated with gst_pad_activate_pull().

 *

 * @offset and @length are always given in byte units. @offset must normally be a value

 * between 0 and the length in bytes of the data available on @pad. The

 * length (duration in bytes) can be retrieved with a #GST_QUERY_DURATION or with a

 * #GST_QUERY_SEEKING.

 *

 * Any @offset larger or equal than the length will make the function return

 * #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.

 *

 * 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

 * #GST_FLOW_OK.

 *

 * When this function is called with a -1 @offset, the sequentially next buffer

 * of length @length in the stream is returned.

 *

 * When this function is called with a -1 @length, a buffer with a default

 * optimal length is returned in @buffer. The length might depend on the value

 * of @offset.

 *

 * Returns: #GST_FLOW_OK for success

 */

typedef GstFlowReturn		(*GstPadGetRangeFunction)	(GstPad *pad, guint64 offset,

		                                                 guint length, GstBuffer **buffer);

/**

 * GstPadEventFunction:

 * @pad: the #GstPad to handle the event.

 * @event: the #GstEvent to handle.

 *

 * Function signature to handle an event for the pad.

 *

 * Returns: TRUE if the pad could handle the event.

 */

typedef gboolean		(*GstPadEventFunction)		(GstPad *pad, GstEvent *event);

/* FIXME: 0.11: deprecate me, check range should use seeking query */

/**

 * GstPadCheckGetRangeFunction:

 * @pad: a #GstPad

 *

 * Check if @pad can be activated in pull mode.

 *

 * This function will be deprecated after 0.10; use the seeking query to check

 * if a pad can support random access.

 *

 * Returns: TRUE if the pad can operate in pull mode.

 */

typedef gboolean		(*GstPadCheckGetRangeFunction)	(GstPad *pad);

/* internal links */

/**

 * GstPadIntLinkFunction:

 * @pad: The #GstPad to query.

 *

 * The signature of the internal pad link function.

 *

 * Returns: a newly allocated #GList of pads that are linked to the given pad on

 */

typedef GList*			(*GstPadIntLinkFunction)	(GstPad *pad);

/* generic query function */

/**

 * GstPadQueryTypeFunction:

 * @pad: a #GstPad to query

 *

 * The signature of the query types function.

 *

 * Returns: a constant array of query types

 */

typedef const GstQueryType*	(*GstPadQueryTypeFunction)	(GstPad *pad);

/**

 * GstPadQueryFunction:

 * @pad: the #GstPad to query.

 * @query: the #GstQuery object to execute

 *

 * The signature of the query function.

 *

 * Returns: TRUE if the query could be performed.

 */

typedef gboolean		(*GstPadQueryFunction)		(GstPad *pad, GstQuery *query);

/* linking */

/**

 * GstPadLinkFunction

 * @pad: the #GstPad that is linked.

 * @peer: the peer #GstPad of the link

 *

 * Function signature to handle a new link on the pad.

 *

 * Returns: the result of the link with the specified peer.

 */

typedef GstPadLinkReturn	(*GstPadLinkFunction)		(GstPad *pad, GstPad *peer);

/**

 * GstPadUnlinkFunction

 * @pad: the #GstPad that is linked.

 *

 * Function signature to handle a unlinking the pad prom its peer.

 */

typedef void			(*GstPadUnlinkFunction)		(GstPad *pad);

/* caps nego */

/**

 * GstPadGetCapsFunction:

 * @pad: the #GstPad to get the capabilities of.

 *

 * Returns a copy of the capabilities of the specified pad. By default this

 * function will return the pad template capabilities, but can optionally

 * be overridden by elements.

 *

 * Returns: a newly allocated copy #GstCaps of the pad.

 */

typedef GstCaps*		(*GstPadGetCapsFunction)	(GstPad *pad);

/**

 * GstPadSetCapsFunction:

 * @pad: the #GstPad to set the capabilities of.

 * @caps: the #GstCaps to set

 *

 * Set @caps on @pad. By default this function updates the caps of the

 * pad but the function can be overriden by elements to perform extra

 * actions or verifications.

 *

 * Returns: TRUE if the caps could be set on the pad.

 */

typedef gboolean		(*GstPadSetCapsFunction)	(GstPad *pad, GstCaps *caps);

/**

 * GstPadAcceptCapsFunction:

 * @pad: the #GstPad to check

 * @caps: the #GstCaps to check

 *

 * Check if @pad can accept @caps. By default this function will see if @caps

 * intersect with the result from gst_pad_get_caps() by can be overridden to

 * perform extra checks.

 *

 * Returns: TRUE if the caps can be accepted by the pad.

 */

typedef gboolean		(*GstPadAcceptCapsFunction)	(GstPad *pad, GstCaps *caps);

/**

 * GstPadFixateCapsFunction:

 * @pad: a #GstPad

 * @caps: the #GstCaps to fixate

 *

 * Given possibly unfixed caps @caps, let @pad use its default prefered

 * 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.

 */

typedef void			(*GstPadFixateCapsFunction)	(GstPad *pad, GstCaps *caps);

/**

 * GstPadBufferAllocFunction:

 * @pad: a sink #GstPad

 * @offset: the desired offset of the buffer

 * @size: the desired size of the buffer

 * @caps: the desired caps of the buffer

 * @buf: pointer to hold the allocated buffer.

 *

 * Ask the sinkpad @pad to allocate a buffer with @offset, @size and @caps.

 * The result will be stored in @buf.

 *

 * The purpose of this function is to allocate a buffer that is optimal to

 * be processed by @pad. The function is mostly overridden by elements that can

 * provide a hardware buffer in order to avoid additional memcpy operations.

 *

 *

 * When this function returns anything else than #GST_FLOW_OK, the buffer allocation

 *

 * By default this function returns a new buffer of @size and with @caps containing

 * purely malloced data. The buffer should be freed with gst_buffer_unref()

 * after usage.

 *

 * Returns: #GST_FLOW_OK if @buf contains a valid buffer, any other return

 *  value means @buf does not hold a valid buffer.

 */

typedef GstFlowReturn		(*GstPadBufferAllocFunction)	(GstPad *pad, guint64 offset, guint size,

								 GstCaps *caps, GstBuffer **buf);

/* misc */

/**

 * GstPadDispatcherFunction:

 * @pad: the #GstPad that is dispatched.

 * @data: the gpointer to optional user data.

 *

 * A dispatcher function is called for all internally linked pads, see

 * gst_pad_dispatcher().

 *

 * Returns: TRUE if the dispatching procedure has to be stopped.

 */

typedef gboolean		(*GstPadDispatcherFunction)	(GstPad *pad, gpointer data);

/**

 * GstPadBlockCallback:

 * @pad: the #GstPad that is blockend or unblocked.

 * @blocked: blocking state for the pad

 * @user_data: the gpointer to optional user data.

 *

 * Callback used by gst_pad_set_blocked_async(). Gets called when the blocking

 * operation succeeds.

 */

typedef void			(*GstPadBlockCallback)		(GstPad *pad, gboolean blocked, gpointer user_data);

/**

 * GstPadDirection:

 * @GST_PAD_UNKNOWN: direction is unknown.

 * @GST_PAD_SRC: the pad is a source pad.

 * @GST_PAD_SINK: the pad is a sink pad.

 *

 * The direction of a pad.

 */

typedef enum {

  GST_PAD_UNKNOWN,

  GST_PAD_SRC,

  GST_PAD_SINK

} GstPadDirection;

/**

 * GstPadFlags:

 * @GST_PAD_BLOCKED: is dataflow on a pad blocked

 * @GST_PAD_FLUSHING: is pad refusing buffers

 * @GST_PAD_IN_GETCAPS: GstPadGetCapsFunction() is running now

 * @GST_PAD_IN_SETCAPS: GstPadSetCapsFunction() is running now

 * @GST_PAD_BLOCKING: is pad currently blocking on a buffer or event

 * @GST_PAD_FLAG_LAST: offset to define more flags

 *

 * Pad state flags

 */

typedef enum {

  GST_PAD_BLOCKED       = (GST_OBJECT_FLAG_LAST << 0),

  GST_PAD_FLUSHING      = (GST_OBJECT_FLAG_LAST << 1),

  GST_PAD_IN_GETCAPS    = (GST_OBJECT_FLAG_LAST << 2),

  GST_PAD_IN_SETCAPS    = (GST_OBJECT_FLAG_LAST << 3),

  GST_PAD_BLOCKING	= (GST_OBJECT_FLAG_LAST << 4),

  /* padding */

  GST_PAD_FLAG_LAST     = (GST_OBJECT_FLAG_LAST << 8)

} GstPadFlags;

/* FIXME: this awful circular dependency need to be resolved properly (see padtemplate.h) */

typedef struct _GstPadTemplate GstPadTemplate;

/**

 * GstPad:

 * @element_private: private data owned by the parent element

 * @padtemplate: padtemplate for this pad

 * @direction: the direction of the pad, cannot change after creating

 *             the pad.

 * @stream_rec_lock: recursive stream lock of the pad, used to protect

 *                   the data used in streaming.

 * @task: task for this pad if the pad is actively driving dataflow.

 * @preroll_lock: lock used when prerolling

 * @preroll_cond: conf to signal preroll

 * @block_cond: conditional to signal pad block

 * @block_callback: callback for the pad block if any

 * @block_data: user data for @block_callback

 * @caps: the current caps of the pad

 * @getcapsfunc: function to get caps of the pad

 * @setcapsfunc: function to set caps on the pad

 * @acceptcapsfunc: function to check if pad can accept caps

 * @fixatecapsfunc: function to fixate caps

 * @activatefunc: pad activation function

 * @activatepushfunc: function to activate/deactivate pad in push mode