GstHarness

GstHarness

Since : 1.6

gst_harness_add_element_full

gst_harness_add_element_full (GstHarness * h,
                              GstElement * element,
                              GstStaticPadTemplate * hsrc,
                              const gchar * element_sinkpad_name,
                              GstStaticPadTemplate * hsink,
                              const gchar * element_srcpad_name)

Adds a GstElement to an empty GstHarness

MT safe.

Since : 1.6

gst_harness_add_element_sink_pad

gst_harness_add_element_sink_pad (GstHarness * h,
                                  GstPad * sinkpad)

Links the specified GstPad the GstHarness srcpad.

MT safe.

Since : 1.6

gst_harness_add_element_src_pad

gst_harness_add_element_src_pad (GstHarness * h,
                                 GstPad * srcpad)

Links the specified GstPad the GstHarness sinkpad. This can be useful if perhaps the srcpad did not exist at the time of creating the harness, like a demuxer that provides a sometimes-pad after receiving data.

MT safe.

Since : 1.6

gst_harness_add_parse

gst_harness_add_parse (GstHarness * h,
                       const gchar * launchline)

Parses the launchline and puts that in a GstBin, and then attches the supplied GstHarness to the bin.

MT safe.

Since : 1.6

gst_harness_add_probe

gst_harness_add_probe (GstHarness * h,
                       const gchar * element_name,
                       const gchar * pad_name,
                       GstPadProbeType mask,
                       GstPadProbeCallback callback,
                       gpointer user_data,
                       GDestroyNotify destroy_data)

A convenience function to allows you to call gst_pad_add_probe on a GstPad of a GstElement that are residing inside the GstHarness, by using normal gst_pad_add_probe syntax

MT safe.

Since : 1.6

gst_harness_add_propose_allocation_meta

gst_harness_add_propose_allocation_meta (GstHarness * h,
                                         GType api,
                                         const GstStructure * params)

Add api with params as one of the supported metadata API to propose when receiving an allocation query.

MT safe.

Since : 1.16

gst_harness_add_sink

gst_harness_add_sink (GstHarness * h,
                      const gchar * sink_element_name)

Similar to gst_harness_add_sink_harness, this is a convenience to directly create a sink-harness using the sink_element_name name specified.

MT safe.

Since : 1.6

gst_harness_add_sink_harness

gst_harness_add_sink_harness (GstHarness * h,
                              GstHarness * sink_harness)

Similar to gst_harness_add_src, this allows you to send the data coming out of your harnessed GstElement to a sink-element, allowing to test different responses the element output might create in sink elements. An example might be an existing sink providing some analytical data on the input it receives that can be useful to your testing. If the goal is to test a sink-element itself, this is better achieved using gst_harness_new directly on the sink.

If a sink-harness already exists it will be replaced.

MT safe.

Since : 1.6

gst_harness_add_sink_parse

gst_harness_add_sink_parse (GstHarness * h,
                            const gchar * launchline)

Similar to gst_harness_add_sink, this allows you to specify a launch-line instead of just an element name. See gst_harness_add_src_parse for details.

MT safe.

Since : 1.6

gst_harness_add_src

gst_harness_add_src (GstHarness * h,
                     const gchar * src_element_name,
                     gboolean has_clock_wait)

Similar to gst_harness_add_src_harness, this is a convenience to directly create a src-harness using the src_element_name name specified.

MT safe.

Since : 1.6

gst_harness_add_src_harness

gst_harness_add_src_harness (GstHarness * h,
                             GstHarness * src_harness,
                             gboolean has_clock_wait)

A src-harness is a great way of providing the GstHarness with data. By adding a src-type GstElement, it is then easy to use functions like gst_harness_push_from_src or gst_harness_src_crank_and_push_many to provide your harnessed element with input. The has_clock_wait variable is a great way to control you src-element with, in that you can have it produce a buffer for you by simply cranking the clock, and not have it spin out of control producing buffers as fast as possible.

If a src-harness already exists it will be replaced.

MT safe.

Since : 1.6

gst_harness_add_src_parse

gst_harness_add_src_parse (GstHarness * h,
                           const gchar * launchline,
                           gboolean has_clock_wait)

Similar to gst_harness_add_src, this allows you to specify a launch-line, which can be useful for both having more then one GstElement acting as your src (Like a src producing raw buffers, and then an encoder, providing encoded data), but also by allowing you to set properties like "is-live" directly on the elements.

MT safe.

Since : 1.6

gst_harness_buffers_in_queue

guint
gst_harness_buffers_in_queue (GstHarness * h)

The number of GstBuffer currently in the GstHarness sinkpad GAsyncQueue

MT safe.

Since : 1.6

gst_harness_buffers_received

guint
gst_harness_buffers_received (GstHarness * h)

The total number of GstBuffer that has arrived on the GstHarness sinkpad. This number includes buffers that have been dropped as well as buffers that have already been pulled out.

MT safe.

Since : 1.6

gst_harness_crank_multiple_clock_waits

gboolean
gst_harness_crank_multiple_clock_waits (GstHarness * h,
                                        guint waits)

Similar to gst_harness_crank_single_clock_wait, this is the function to use if your harnessed element(s) are using more then one gst_clock_id_wait. Failing to do so can (and will) make it racy which GstClockID you actually are releasing, where as this function will process all the waits at the same time, ensuring that one thread can't register another wait before both are released.

MT safe.

Since : 1.6

gst_harness_crank_single_clock_wait

gboolean
gst_harness_crank_single_clock_wait (GstHarness * h)

A "crank" consists of three steps: 1: Wait for a GstClockID to be registered with the GstTestClock. 2: Advance the GstTestClock to the time the GstClockID is waiting for. 3: Release the GstClockID wait. Together, this provides an easy way to not have to think about the details around clocks and time, but still being able to write deterministic tests that are dependent on this. A "crank" can be though of as the notion of manually driving the clock forward to its next logical step.

MT safe.

Since : 1.6

gst_harness_create_buffer

GstBuffer *
gst_harness_create_buffer (GstHarness * h,
                           gsize size)

Allocates a buffer using a GstBufferPool if present, or else using the configured GstAllocator and GstAllocationParams

MT safe.

Since : 1.6

gst_harness_dump_to_file

gst_harness_dump_to_file (GstHarness * h,
                          const gchar * filename)

Allows you to dump the GstBuffer the GstHarness sinkpad GAsyncQueue to a file.

MT safe.

Since : 1.6

gst_harness_events_in_queue

guint
gst_harness_events_in_queue (GstHarness * h)

The number of GstEvent currently in the GstHarness sinkpad GAsyncQueue

MT safe.

Since : 1.6

gst_harness_events_received

guint
gst_harness_events_received (GstHarness * h)

The total number of GstEvent that has arrived on the GstHarness sinkpad This number includes events handled by the harness as well as events that have already been pulled out.

MT safe.

Since : 1.6

gst_harness_find_element

GstElement *
gst_harness_find_element (GstHarness * h,
                          const gchar * element_name)

Most useful in conjunction with gst_harness_new_parse, this will scan the GstElement inside the GstHarness, and check if any of them matches element_name. Typical usecase being that you need to access one of the harnessed elements for properties and/or signals.

MT safe.

Since : 1.6

gst_harness_get

gst_harness_get (GstHarness * h,
                 const gchar * element_name,
                 const gchar * first_property_name,
                 ... ...)

A convenience function to allows you to call g_object_get on a GstElement that are residing inside the GstHarness, by using normal g_object_get syntax.

MT safe.

Since : 1.6

gst_harness_get_allocator

gst_harness_get_allocator (GstHarness * h,
                           GstAllocator ** allocator,
                           GstAllocationParams * params)

Gets the allocator and its params that has been decided to use after an allocation query.

MT safe.

Since : 1.6

gst_harness_get_last_pushed_timestamp

GstClockTime
gst_harness_get_last_pushed_timestamp (GstHarness * h)

Get the timestamp of the last GstBuffer pushed on the GstHarness srcpad, typically with gst_harness_push or gst_harness_push_from_src.

MT safe.

Since : 1.6

gst_harness_get_testclock

GstTestClock *
gst_harness_get_testclock (GstHarness * h)

Get the GstTestClock. Useful if specific operations on the testclock is needed.

MT safe.

Since : 1.6

gst_harness_play

gst_harness_play (GstHarness * h)

This will set the harnessed GstElement to GST_STATE_PLAYING. GstElement without a sink-#GstPad and with the GST_ELEMENT_FLAG_SOURCE flag set is considered a src GstElement Non-src GstElement (like sinks and filters) are automatically set to playing by the GstHarness, but src GstElement are not to avoid them starting to produce buffers. Hence, for src GstElement you must call gst_harness_play explicitly.

MT safe.

Since : 1.6

gst_harness_pull

GstBuffer *
gst_harness_pull (GstHarness * h)

Pulls a GstBuffer from the GAsyncQueue on the GstHarness sinkpad. The pull will timeout in 60 seconds. This is the standard way of getting a buffer from a harnessed GstElement.

MT safe.

Since : 1.6

gst_harness_pull_event

GstEvent *
gst_harness_pull_event (GstHarness * h)

Pulls an GstEvent from the GAsyncQueue on the GstHarness sinkpad. Timeouts after 60 seconds similar to gst_harness_pull.

MT safe.

Since : 1.6

gst_harness_pull_until_eos

gboolean
gst_harness_pull_until_eos (GstHarness * h,
                            GstBuffer ** buf)

Pulls a GstBuffer from the GAsyncQueue on the GstHarness sinkpad. The pull will block until an EOS event is received, or timeout in 60 seconds. MT safe.

Since : 1.18

gst_harness_pull_upstream_event

GstEvent *
gst_harness_pull_upstream_event (GstHarness * h)

Pulls an GstEvent from the GAsyncQueue on the GstHarness srcpad. Timeouts after 60 seconds similar to gst_harness_pull.

MT safe.

Since : 1.6

gst_harness_push

GstFlowReturn
gst_harness_push (GstHarness * h,
                  GstBuffer * buffer)

Pushes a GstBuffer on the GstHarness srcpad. The standard way of interacting with an harnessed element.

MT safe.

Since : 1.6

gst_harness_push_and_pull

GstBuffer *
gst_harness_push_and_pull (GstHarness * h,
                           GstBuffer * buffer)

Basically a gst_harness_push and a gst_harness_pull in one line. Reflects the fact that you often want to do exactly this in your test: Push one buffer in, and inspect the outcome.

MT safe.

Since : 1.6

gst_harness_push_event

gboolean
gst_harness_push_event (GstHarness * h,
                        GstEvent * event)

Pushes an GstEvent on the GstHarness srcpad.

MT safe.

Since : 1.6

gst_harness_push_from_src

GstFlowReturn
gst_harness_push_from_src (GstHarness * h)

Transfer data from the src-#GstHarness to the main-#GstHarness. It consists of 4 steps: 1: Make sure the src is started. (see: gst_harness_play) 2: Crank the clock (see: gst_harness_crank_single_clock_wait) 3: Pull a GstBuffer from the src-#GstHarness (see: gst_harness_pull) 4: Push the same GstBuffer into the main-#GstHarness (see: gst_harness_push)

MT safe.

Since : 1.6

gst_harness_push_to_sink

GstFlowReturn
gst_harness_push_to_sink (GstHarness * h)

Transfer one GstBuffer from the main-#GstHarness to the sink-#GstHarness. See gst_harness_push_from_src for details.

MT safe.

Since : 1.6

gst_harness_push_upstream_event

gboolean
gst_harness_push_upstream_event (GstHarness * h,
                                 GstEvent * event)

Pushes an GstEvent on the GstHarness sinkpad.

MT safe.

Since : 1.6

gst_harness_query_latency

GstClockTime
gst_harness_query_latency (GstHarness * h)

Get the min latency reported by any harnessed GstElement.

MT safe.

Since : 1.6

gst_harness_set

gst_harness_set (GstHarness * h,
                 const gchar * element_name,
                 const gchar * first_property_name,
                 ... ...)

A convenience function to allows you to call g_object_set on a GstElement that are residing inside the GstHarness, by using normal g_object_set syntax.

MT safe.

Since : 1.6

gst_harness_set_blocking_push_mode

gst_harness_set_blocking_push_mode (GstHarness * h)

Setting this will make the harness block in the chain-function, and then release when gst_harness_pull or gst_harness_try_pull is called. Can be useful when wanting to control a src-element that is not implementing gst_clock_id_wait so it can't be controlled by the GstTestClock, since it otherwise would produce buffers as fast as possible.

MT safe.

Since : 1.6

gst_harness_set_caps

gst_harness_set_caps (GstHarness * h,
                      GstCaps * in,
                      GstCaps * out)

Sets the GstHarness srcpad and sinkpad caps.

MT safe.

Since : 1.6

gst_harness_set_caps_str

gst_harness_set_caps_str (GstHarness * h,
                          const gchar * in,
                          const gchar * out)

Sets the GstHarness srcpad and sinkpad caps using strings.

MT safe.

Since : 1.6

gst_harness_set_drop_buffers

gst_harness_set_drop_buffers (GstHarness * h,
                              gboolean drop_buffers)

When set to TRUE, instead of placing the buffers arriving from the harnessed GstElement inside the sinkpads GAsyncQueue, they are instead unreffed.

MT safe.

Since : 1.6

gst_harness_set_forwarding

gst_harness_set_forwarding (GstHarness * h,
                            gboolean forwarding)

As a convenience, a src-harness will forward GST_EVENT_STREAM_START, GST_EVENT_CAPS and GST_EVENT_SEGMENT to the main-harness if forwarding is enabled, and forward any sticky-events from the main-harness to the sink-harness. It will also forward the GST_QUERY_ALLOCATION.

If forwarding is disabled, the user will have to either manually push these events from the src-harness using gst_harness_src_push_event, or create and push them manually. While this will allow full control and inspection of these events, for the most cases having forwarding enabled will be sufficient when writing a test where the src-harness' main function is providing data for the main-harness.

Forwarding is enabled by default.

MT safe.

Since : 1.6

gst_harness_set_live

gst_harness_set_live (GstHarness * h,
                      gboolean is_live)

Sets the liveness reported by GstHarness when receiving a latency-query. The default is TRUE.

Since : 1.20

gst_harness_set_propose_allocator

gst_harness_set_propose_allocator (GstHarness * h,
                                   GstAllocator * allocator,
                                   const GstAllocationParams * params)

Sets the allocator and params to propose when receiving an allocation query.

MT safe.

Since : 1.6

gst_harness_set_sink_caps

gst_harness_set_sink_caps (GstHarness * h,
                           GstCaps * caps)

Sets the GstHarness sinkpad caps.

MT safe.

Since : 1.6

gst_harness_set_sink_caps_str

gst_harness_set_sink_caps_str (GstHarness * h,
                               const gchar * str)

Sets the GstHarness sinkpad caps using a string.

MT safe.

Since : 1.6

gst_harness_set_src_caps

gst_harness_set_src_caps (GstHarness * h,
                          GstCaps * caps)

Sets the GstHarness srcpad caps. This must be done before any buffers can legally be pushed from the harness to the element.

MT safe.

Since : 1.6

gst_harness_set_src_caps_str

gst_harness_set_src_caps_str (GstHarness * h,
                              const gchar * str)

Sets the GstHarness srcpad caps using a string. This must be done before any buffers can legally be pushed from the harness to the element.

MT safe.

Since : 1.6

gst_harness_set_time

gboolean
gst_harness_set_time (GstHarness * h,
                      GstClockTime time)

Advance the GstTestClock to a specific time.

MT safe.

Since : 1.6

gst_harness_set_upstream_latency

gst_harness_set_upstream_latency (GstHarness * h,
                                  GstClockTime latency)

Sets the min latency reported by GstHarness when receiving a latency-query

Since : 1.6

gst_harness_sink_push_many

GstFlowReturn
gst_harness_sink_push_many (GstHarness * h,
                            gint pushes)

Convenience that calls gst_harness_push_to_sink pushes number of times. Will abort the pushing if any one push fails.

MT safe.

Since : 1.6

gst_harness_src_crank_and_push_many

GstFlowReturn
gst_harness_src_crank_and_push_many (GstHarness * h,
                                     gint cranks,
                                     gint pushes)

Transfer data from the src-#GstHarness to the main-#GstHarness. Similar to gst_harness_push_from_src, this variant allows you to specify how many cranks and how many pushes to perform. This can be useful for both moving a lot of data at the same time, as well as cases when one crank does not equal one buffer to push and v.v.

MT safe.

Since : 1.6

gst_harness_src_push_event

gboolean
gst_harness_src_push_event (GstHarness * h)

Similar to what gst_harness_src_push does with GstBuffer, this transfers a GstEvent from the src-#GstHarness to the main-#GstHarness. Note that some GstEvent are being transferred automagically. Look at sink_forward_pad for details.

MT safe.

Since : 1.6

gst_harness_stress_custom_start

GstHarnessThread *
gst_harness_stress_custom_start (GstHarness * h,
                                 GFunc init,
                                 GFunc callback,
                                 gpointer data,
                                 gulong sleep)

Start a custom stress-thread that will call your callback for every iteration allowing you to do something nasty.

MT safe.

Since : 1.6

gst_harness_stress_property_start_full

GstHarnessThread *
gst_harness_stress_property_start_full (GstHarness * h,
                                        const gchar * name,
                                        const GValue * value,
                                        gulong sleep)

Call g_object_set with name and value in intervals of sleep microseconds

MT safe.

Since : 1.6

gst_harness_stress_push_buffer_start_full

GstHarnessThread *
gst_harness_stress_push_buffer_start_full (GstHarness * h,
                                           GstCaps * caps,
                                           const GstSegment * segment,
                                           GstBuffer * buf,
                                           gulong sleep)

Push a GstBuffer in intervals of sleep microseconds.

MT safe.

Since : 1.6

gst_harness_stress_push_buffer_with_cb_start_full

GstHarnessThread *
gst_harness_stress_push_buffer_with_cb_start_full (GstHarness * h,
                                                   GstCaps * caps,
                                                   const GstSegment * segment,
                                                   GstHarnessPrepareBufferFunc func,
                                                   gpointer data,
                                                   GDestroyNotify notify,
                                                   gulong sleep)

Push a GstBuffer returned by func in intervals of sleep microseconds.

MT safe.

Since : 1.6

gst_harness_stress_push_event_start_full

GstHarnessThread *
gst_harness_stress_push_event_start_full (GstHarness * h,
                                          GstEvent * event,
                                          gulong sleep)

Push the event onto the harnessed GstElement sinkpad in intervals of sleep microseconds

MT safe.

Since : 1.6

gst_harness_stress_push_event_with_cb_start_full

GstHarnessThread *
gst_harness_stress_push_event_with_cb_start_full (GstHarness * h,
                                                  GstHarnessPrepareEventFunc func,
                                                  gpointer data,
                                                  GDestroyNotify notify,
                                                  gulong sleep)

Push a GstEvent returned by func onto the harnessed GstElement sinkpad in intervals of sleep microseconds.

MT safe.

Since : 1.8

gst_harness_stress_push_upstream_event_start_full

GstHarnessThread *
gst_harness_stress_push_upstream_event_start_full (GstHarness * h,
                                                   GstEvent * event,
                                                   gulong sleep)

Push the event onto the harnessed GstElement srcpad in intervals of sleep microseconds.

MT safe.

Since : 1.6

gst_harness_stress_push_upstream_event_with_cb_start_full

GstHarnessThread *
gst_harness_stress_push_upstream_event_with_cb_start_full (GstHarness * h,
                                                           GstHarnessPrepareEventFunc func,
                                                           gpointer data,
                                                           GDestroyNotify notify,
                                                           gulong sleep)

Push a GstEvent returned by func onto the harnessed GstElement srcpad in intervals of sleep microseconds.

MT safe.

Since : 1.8

gst_harness_stress_requestpad_start_full

GstHarnessThread *
gst_harness_stress_requestpad_start_full (GstHarness * h,
                                          GstPadTemplate * templ,
                                          const gchar * name,
                                          GstCaps * caps,
                                          gboolean release,
                                          gulong sleep)

Call gst_element_request_pad in intervals of sleep microseconds

MT safe.

Since : 1.6

gst_harness_stress_statechange_start_full

GstHarnessThread *
gst_harness_stress_statechange_start_full (GstHarness * h,
                                           gulong sleep)

Change the state of your harnessed GstElement from NULL to PLAYING and back again, only pausing for sleep microseconds every time.

MT safe.

Since : 1.6

gst_harness_take_all_data

guint8 *
gst_harness_take_all_data (GstHarness * h,
                           gsize * size)

Pulls all pending data from the harness and returns it as a single data slice.

Since : 1.14

gst_harness_take_all_data_as_buffer

GstBuffer *
gst_harness_take_all_data_as_buffer (GstHarness * h)

Pulls all pending data from the harness and returns it as a single buffer.

Since : 1.14

gst_harness_take_all_data_as_bytes

GBytes *
gst_harness_take_all_data_as_bytes (GstHarness * h)

Pulls all pending data from the harness and returns it as a single GBytes.

Since : 1.14

gst_harness_teardown

gst_harness_teardown (GstHarness * h)

Tears down a GstHarness, freeing all resources allocated using it.

MT safe.

Since : 1.6

gst_harness_try_pull

GstBuffer *
gst_harness_try_pull (GstHarness * h)

Pulls a GstBuffer from the GAsyncQueue on the GstHarness sinkpad. Unlike gst_harness_pull this will not wait for any buffers if not any are present, and return NULL straight away.

MT safe.

Since : 1.6

gst_harness_try_pull_event

GstEvent *
gst_harness_try_pull_event (GstHarness * h)

Pulls an GstEvent from the GAsyncQueue on the GstHarness sinkpad. See gst_harness_try_pull for details.

MT safe.

Since : 1.6

gst_harness_try_pull_upstream_event

GstEvent *
gst_harness_try_pull_upstream_event (GstHarness * h)

Pulls an GstEvent from the GAsyncQueue on the GstHarness srcpad. See gst_harness_try_pull for details.

MT safe.

Since : 1.6

gst_harness_upstream_events_in_queue

guint
gst_harness_upstream_events_in_queue (GstHarness * h)

The number of GstEvent currently in the GstHarness srcpad GAsyncQueue

MT safe.

Since : 1.6

gst_harness_upstream_events_received

guint
gst_harness_upstream_events_received (GstHarness * h)

The total number of GstEvent that has arrived on the GstHarness srcpad This number includes events handled by the harness as well as events that have already been pulled out.

MT safe.

Since : 1.6

gst_harness_use_systemclock

gst_harness_use_systemclock (GstHarness * h)

Sets the system GstClock on the GstHarness GstElement

MT safe.

Since : 1.6

gst_harness_use_testclock

gst_harness_use_testclock (GstHarness * h)

Sets the GstTestClock on the GstHarness GstElement

MT safe.

Since : 1.6

gst_harness_wait_for_clock_id_waits

gboolean
gst_harness_wait_for_clock_id_waits (GstHarness * h,
                                     guint waits,
                                     guint timeout)

Waits for timeout seconds until waits number of GstClockID waits is registered with the GstTestClock. Useful for writing deterministic tests, where you want to make sure that an expected number of waits have been reached.

MT safe.

Since : 1.6