## GstHarness

GstHarness — A test-harness for writing GStreamer unit tests

## Functions

GstHarness * | gst_harness_new_full ()
GstHarness * | gst_harness_new_with_element ()
GstHarness * | gst_harness_new_with_padnames ()
GstHarness * | gst_harness_new_with_templates ()
GstHarness * | gst_harness_new ()
GstHarness * | gst_harness_new_parse ()
void | gst_harness_teardown ()
void | gst_harness_add_element_src_pad ()
void | gst_harness_add_element_sink_pad ()
void | gst_harness_set_src_caps ()
void | gst_harness_set_sink_caps ()
void | gst_harness_set_caps ()
void | gst_harness_set_src_caps_str ()
void | gst_harness_set_sink_caps_str ()
void | gst_harness_set_caps_str ()
void | gst_harness_use_systemclock ()
void | gst_harness_use_testclock ()
GstTestClock * | gst_harness_get_testclock ()
gboolean | gst_harness_set_time ()
gboolean | gst_harness_wait_for_clock_id_waits ()
gboolean | gst_harness_crank_single_clock_wait ()
gboolean | gst_harness_crank_multiple_clock_waits ()
void | gst_harness_play ()
void | gst_harness_set_blocking_push_mode ()
void | gst_harness_set_forwarding ()
GstBuffer * | gst_harness_create_buffer ()
GstFlowReturn | gst_harness_push ()
GstBuffer * | gst_harness_pull ()
GstBuffer * | gst_harness_try_pull ()
GstBuffer * | gst_harness_push_and_pull ()
guint | gst_harness_buffers_received ()
guint | gst_harness_buffers_in_queue ()
void | gst_harness_set_drop_buffers ()
void | gst_harness_dump_to_file ()
GstClockTime | gst_harness_get_last_pushed_timestamp ()
gboolean | gst_harness_push_event ()
GstEvent * | gst_harness_pull_event ()
GstEvent * | gst_harness_try_pull_event ()
guint | gst_harness_events_received ()
guint | gst_harness_events_in_queue ()
gboolean | gst_harness_push_upstream_event ()
GstEvent * | gst_harness_pull_upstream_event ()
GstEvent * | gst_harness_try_pull_upstream_event ()
guint | gst_harness_upstream_events_received ()
guint | gst_harness_upstream_events_in_queue ()
GstClockTime | gst_harness_query_latency ()
void | gst_harness_set_upstream_latency ()
void | gst_harness_set_propose_allocator ()
void | gst_harness_get_allocator ()
void | gst_harness_add_src ()
void | gst_harness_add_src_harness ()
void | gst_harness_add_src_parse ()
GstFlowReturn | gst_harness_push_from_src ()
GstFlowReturn | gst_harness_src_crank_and_push_many ()
gboolean | gst_harness_src_push_event ()
void | gst_harness_add_sink ()
void | gst_harness_add_sink_harness ()
void | gst_harness_add_sink_parse ()
GstFlowReturn | gst_harness_push_to_sink ()
GstFlowReturn | gst_harness_sink_push_many ()
GstElement * | gst_harness_find_element ()
void | gst_harness_set ()
void | gst_harness_get ()
void | gst_harness_add_probe ()
guint | gst_harness_stress_thread_stop ()
GstHarnessThread * | gst_harness_stress_custom_start ()
#define | gst_harness_stress_statechange_start ()
GstHarnessThread * | gst_harness_stress_statechange_start_full ()
#define | gst_harness_stress_push_buffer_start ()
GstHarnessThread * | gst_harness_stress_push_buffer_start_full ()
GstBuffer * | ( *GstHarnessPrepareBufferFunc ) ()
#define | gst_harness_stress_push_buffer_with_cb_start ()
GstHarnessThread * | gst_harness_stress_push_buffer_with_cb_start_full ()
#define | gst_harness_stress_push_event_start ()
GstHarnessThread * | gst_harness_stress_push_event_start_full ()
#define | gst_harness_stress_send_upstream_event_start ()
GstHarnessThread * | gst_harness_stress_push_upstream_event_start_full ()
#define | gst_harness_stress_property_start ()
GstHarnessThread * | gst_harness_stress_property_start_full ()
#define | gst_harness_stress_requestpad_start ()
GstHarnessThread * | gst_harness_stress_requestpad_start_full ()

## Types and Values

struct | GstHarness
| GstHarnessThread

## Includes

    #include <gst/check/check.h>

## Description

GstHarness is ment to make writing unit test for GStreamer much easier. It can be though of as a way of treating a GstElement as a black box, deterministially feeding it data, and controlling what data it outputs.

The basic structure of GstHarness is two "floating" GstPads, that connects to the harnessed GstElement src and sink GstPads like so:

              __________________________
     _____   |  _____            _____  |   _____
    |     |  | |     |          |     | |  |     |
    | src |--+-| sink|  Element | src |-+--| sink|
    |_____|  | |_____|          |_____| |  |_____|
             |__________________________|

With this, you can now simulate any environment the GstElement might find itself in. By specifying the GstCaps of the harness GstPads, using functions like gst_harness_set_src_caps or gst_harness_set_sink_caps_str, you can test how the GstElement interacts with different capssets.

Your harnessed GstElement can of course also be a bin, and using gst_harness_new_parse supporting standard gst-launch syntax, you can easily test a whole pipeline instead of just one element.

You can then go on to push GstBuffers and GstEvents on to the srcpad, using functions like gst_harness_push and gst_harness_push_event, and then pull them out to examine them with gst_harness_pull and gst_harness_pull_event.

Example 1. A simple buffer-in buffer-out example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27

    #include <gst/gst.h>
    #include <gst/check/gstharness.h>
    GstHarness *h;
    GstBuffer *in_buf;
    GstBuffer *out_buf;

    // attach the harness to the src and sink pad of GstQueue
    h = gst_harness_new ("queue");

    // we must specify a caps before pushing buffers
    gst_harness_set_src_caps_str (h, "mycaps");

    // create a buffer of size 42
    in_buf = gst_harness_create_buffer (h, 42);

    // push the buffer into the queue
    gst_harness_push (h, in_buf);

    // pull the buffer from the queue
    out_buf = gst_harness_pull (h);

    // validate the buffer in is the same as buffer out
    fail_unless (in_buf == out_buf);

    // cleanup
    gst_buffer_unref (out_buf);
    gst_harness_teardown (h);

Another main feature of the GstHarness is its integration with the GstTestClock. Operating the GstTestClock can be very challenging, but GstHarness simplifies some of the most desired actions a lot, like wanting to manually advance the clock while at the same time releasing a GstClockID that is waiting, with functions like gst_harness_crank_single_clock_wait.

GstHarness also supports sub-harnesses, as a way of generating and validating data. A sub-harness is another GstHarness that is managed by the "parent" harness, and can either be created by using the standard gst_harness_new type functions directly on the (GstHarness *)->src_harness, or using the much more convenient gst_harness_add_src or gst_harness_add_sink_parse. If you have a decoder-element you want to test, (like vp8dec) it can be very useful to add a src-harness with both a src-element (videotestsrc) and an encoder (vp8enc) to feed the decoder data with different configurations, by simply doing:

Example 2.

    1
    2

    GstHarness * h = gst_harness_new (h, "vp8dec");
    gst_harness_add_src_parse (h, "videotestsrc is-live=1 ! vp8enc", TRUE);

and then feeding it data with:

Example 3.

    1

    gst_harness_push_from_src (h);

## Functions

### gst_harness_new_full ()

    GstHarness *
    gst_harness_new_full (GstElement *element,
                          GstStaticPadTemplate *hsrc,
                          const gchar *element_sinkpad_name,
                          GstStaticPadTemplate *hsink,
                          const gchar *element_srcpad_name);

Creates a new harness.

MT safe.

[skip]

#### Parameters

element | a GstElement to attach the harness to (transfer none) |
hsrc | a GstStaticPadTemplate describing the harness srcpad. `NULL` will not create a harness srcpad. | [allow-none]
element_sinkpad_name | a gchar with the name of the element sinkpad that is then linked to the harness srcpad. Can be a static or request or a sometimes pad that has been added. `NULL` will not get/request a sinkpad from the element. (Like if the element is a src.). | [allow-none]
hsink | a GstStaticPadTemplate describing the harness sinkpad. `NULL` will not create a harness sinkpad. | [allow-none]
element_srcpad_name | a gchar with the name of the element srcpad that is then linked to the harness sinkpad, similar to the `element_sinkpad_name` . | [allow-none]

#### Returns

a GstHarness, or `NULL` if the harness could not be created.

[transfer full]

Since: 1.6

### gst_harness_new_with_element ()

    GstHarness *
    gst_harness_new_with_element (GstElement *element,
                                  const gchar *element_sinkpad_name,
                                  const gchar *element_srcpad_name);

Creates a new harness. Works in the same way as gst_harness_new_full, only that generic padtemplates are used for the harness src and sinkpads, which will be sufficient in most usecases.

MT safe.

[skip]

#### Parameters

element | a GstElement to attach the harness to (transfer none) |
element_sinkpad_name | a gchar with the name of the element sinkpad that is then linked to the harness srcpad. `NULL` does not attach a sinkpad. | [allow-none]
element_srcpad_name | a gchar with the name of the element srcpad that is then linked to the harness sinkpad. `NULL` does not attach a srcpad. | [allow-none]

#### Returns

a GstHarness, or `NULL` if the harness could not be created.

[transfer full]

Since: 1.6

### gst_harness_new_with_padnames ()

    GstHarness *
    gst_harness_new_with_padnames (const gchar *element_name,
                                   const gchar *element_sinkpad_name,
                                   const gchar *element_srcpad_name);

Creates a new harness. Works in the same way as gst_harness_new_with_element, except you specify the factoryname of the GstElement

MT safe.

[skip]

#### Parameters

element_name | a gchar describing the GstElement name |
element_sinkpad_name | a gchar with the name of the element sinkpad that is then linked to the harness srcpad. `NULL` does not attach a sinkpad. | [allow-none]
element_srcpad_name | a gchar with the name of the element srcpad that is then linked to the harness sinkpad. `NULL` does not attach a srcpad. | [allow-none]

#### Returns

a GstHarness, or `NULL` if the harness could not be created.

[transfer full]

Since: 1.6

### gst_harness_new_with_templates ()

    GstHarness *
    gst_harness_new_with_templates (const gchar *element_name,
                                    GstStaticPadTemplate *hsrc,
                                    GstStaticPadTemplate *hsink);

Creates a new harness, like gst_harness_new_full, except it assumes the GstElement sinkpad is named "sink" and srcpad is named "src"

MT safe.

[skip]

#### Parameters

element_name | a gchar describing the GstElement name |
hsrc | a GstStaticPadTemplate describing the harness srcpad. `NULL` will not create a harness srcpad. | [allow-none]
hsink | a GstStaticPadTemplate describing the harness sinkpad. `NULL` will not create a harness sinkpad. | [allow-none]

#### Returns

a GstHarness, or `NULL` if the harness could not be created.

[transfer full]

Since: 1.6

### gst_harness_new ()

    GstHarness *
    gst_harness_new (const gchar *element_name);

Creates a new harness. Works like gst_harness_new_with_padnames, except it assumes the GstElement sinkpad is named "sink" and srcpad is named "src"

MT safe.

[skip]

#### Parameters

element_name | a gchar describing the GstElement name |

#### Returns

a GstHarness, or `NULL` if the harness could not be created.

[transfer full]

Since: 1.6

### gst_harness_new_parse ()

    GstHarness *
    gst_harness_new_parse (const gchar *launchline);

Creates a new harness, parsing the `launchline` and putting that in a GstBin, and then attches the harness to the bin.

MT safe.

[skip]

#### Parameters

launchline | a gchar describing a gst-launch type line |

#### Returns

a GstHarness, or `NULL` if the harness could not be created.

[transfer full]

Since: 1.6

### gst_harness_teardown ()

    void
    gst_harness_teardown (GstHarness *h);

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

MT safe.

#### Parameters

h | a GstHarness |

Since: 1.6

### gst_harness_add_element_src_pad ()

    void
    gst_harness_add_element_src_pad (GstHarness *h,
                                     GstPad *srcpad);

Links the specifed 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.

#### Parameters

h | a GstHarness |
srcpad | a GstPad to link to the harness sinkpad |

Since: 1.6

### gst_harness_add_element_sink_pad ()

    void
    gst_harness_add_element_sink_pad (GstHarness *h,
                                      GstPad *sinkpad);

Links the specifed GstPad the `GstHarness` srcpad.

MT safe.

#### Parameters

h | a GstHarness |
sinkpad | a GstPad to link to the harness srcpad |

Since: 1.6

### gst_harness_set_src_caps ()

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

#### Parameters

h | a GstHarness |
caps | a GstCaps to set on the harness srcpad. | [transfer full]

Since: 1.6

### gst_harness_set_sink_caps ()

    void
    gst_harness_set_sink_caps (GstHarness *h,
                               GstCaps *caps);

Sets the `GstHarness` sinkpad caps.

MT safe.

#### Parameters

h | a GstHarness |
caps | a GstCaps to set on the harness sinkpad. | [transfer full]

Since: 1.6

### gst_harness_set_caps ()

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

Sets the `GstHarness` srcpad and sinkpad caps.

MT safe.

#### Parameters

h | a GstHarness |
in | a GstCaps to set on the harness srcpad. | [transfer full]
out | a GstCaps to set on the harness sinkpad. | [transfer full]

Since: 1.6

### gst_harness_set_src_caps_str ()

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

#### Parameters

h | a GstHarness |
str | a `gchar` describing a GstCaps to set on the harness srcpad |

Since: 1.6

### gst_harness_set_sink_caps_str ()

    void
    gst_harness_set_sink_caps_str (GstHarness *h,
                                   const gchar *str);

Sets the `GstHarness` sinkpad caps using a string.

MT safe.

#### Parameters

h | a GstHarness |
str | a `gchar` describing a GstCaps to set on the harness sinkpad |

Since: 1.6

### gst_harness_set_caps_str ()

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

Sets the `GstHarness` srcpad and sinkpad caps using strings.

MT safe.

#### Parameters

h | a GstHarness |
in | a `gchar` describing a GstCaps to set on the harness srcpad |
out | a `gchar` describing a GstCaps to set on the harness sinkpad |

Since: 1.6

### gst_harness_use_systemclock ()

    void
    gst_harness_use_systemclock (GstHarness *h);

Sets the system GstClock on the `GstHarness` GstElement

MT safe.

#### Parameters

h | a GstHarness |

Since: 1.6

### gst_harness_use_testclock ()

    void
    gst_harness_use_testclock (GstHarness *h);

Sets the GstTestClock on the GstHarness GstElement

MT safe.

#### Parameters

h | a GstHarness |

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstTestClock, or `NULL` if the testclock is not present.

[transfer full]

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.

#### Parameters

h | a GstHarness |
time | a GstClockTime to advance the clock to |

#### Returns

a `gboolean` `TRUE` if the time could be set. `FALSE` if not.

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.

#### Parameters

h | a GstHarness |
waits | a guint describing the numbers of GstClockID registered with the GstTestClock |
timeout | a guint describing how many seconds to wait for `waits` to be true |

#### Returns

a `gboolean` `TRUE` if the waits have been registered, `FALSE` if not. (Could be that it timed out waiting or that more waits then waits was found)

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 dependant on this. A "crank" can be though of as the notion of manually driving the clock forward to its next logical step.

MT safe.

#### Parameters

h | a GstHarness |

#### Returns

a `gboolean` `TRUE` if the "crank" was successful, `FALSE` if not.

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.

#### Parameters

h | a GstHarness |
waits | a guint describing the number of GstClockIDs to crank |

#### Returns

a `gboolean` `TRUE` if the "crank" was successful, `FALSE` if not.

Since: 1.6

### gst_harness_play ()

    void
    gst_harness_play (GstHarness *h);

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

MT safe.

#### Parameters

h | a GstHarness |

Since: 1.6

### gst_harness_set_blocking_push_mode ()

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

#### Parameters

h | a GstHarness |

Since: 1.6

### gst_harness_set_forwarding ()

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

#### Parameters

h | a GstHarness |
forwarding | a gboolean to enable/disable forwarding |

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.

#### Parameters

h | a GstHarness |
size | a gsize specifying the size of the buffer |

#### Returns

a GstBuffer of size `size`

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.

#### Parameters

h | a GstHarness |
buffer | a GstBuffer to push |

#### Returns

a GstFlowReturn with the result from the push

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstBuffer or `NULL` if timed out.

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstBuffer or `NULL` if no buffers are present in the GAsyncQueue

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.

#### Parameters

h | a GstHarness |
buffer | a GstBuffer to push |

#### Returns

a GstBuffer or `NULL` if timed out.

Since: 1.6

### gst_harness_buffers_received ()

    guint
    gst_harness_buffers_received (GstHarness *h);

The total number of GstBuffers 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.

#### Parameters

h | a GstHarness |

#### Returns

a guint number of buffers received

Since: 1.6

### gst_harness_buffers_in_queue ()

    guint
    gst_harness_buffers_in_queue (GstHarness *h);

The number of GstBuffers currently in the GstHarness sinkpad GAsyncQueue

MT safe.

#### Parameters

h | a GstHarness |

#### Returns

a guint number of buffers in the queue

Since: 1.6

### gst_harness_set_drop_buffers ()

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

#### Parameters

h | a GstHarness |
drop_buffers | a gboolean specifying to drop outgoing buffers or not |

Since: 1.6

### gst_harness_dump_to_file ()

    void
    gst_harness_dump_to_file (GstHarness *h,
                              const gchar *filename);

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

MT safe.

#### Parameters

h | a GstHarness |
filename | a gchar with a the name of a file |

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstClockTime with the timestamp or `GST_CLOCK_TIME_NONE` if no GstBuffer has been pushed on the GstHarness srcpad

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.

#### Parameters

h | a GstHarness |
event | a GstEvent to push |

#### Returns

a gboolean with the result from the push

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstEvent or `NULL` if timed out.

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstEvent or `NULL` if no buffers are present in the GAsyncQueue

Since: 1.6

### gst_harness_events_received ()

    guint
    gst_harness_events_received (GstHarness *h);

The total number of GstEvents 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.

#### Parameters

h | a GstHarness |

#### Returns

a guint number of events received

Since: 1.6

### gst_harness_events_in_queue ()

    guint
    gst_harness_events_in_queue (GstHarness *h);

The number of GstEvents currently in the GstHarness sinkpad GAsyncQueue

MT safe.

#### Parameters

h | a GstHarness |

#### Returns

a guint number of events in the queue

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.

#### Parameters

h | a GstHarness |
event | a GstEvent to push |

#### Returns

a gboolean with the result from the push

Since: 1.6

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

#### Parameters

h | a GstHarness |

#### Returns

a GstEvent or `NULL` if timed out.

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstEvent or `NULL` if no buffers are present in the GAsyncQueue

Since: 1.6

### gst_harness_upstream_events_received ()

    guint
    gst_harness_upstream_events_received (GstHarness *h);

The total number of GstEvents 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.

#### Parameters

h | a GstHarness |

#### Returns

a guint number of events received

Since: 1.6

### gst_harness_upstream_events_in_queue ()

    guint
    gst_harness_upstream_events_in_queue (GstHarness *h);

The number of GstEvents currently in the GstHarness srcpad GAsyncQueue

MT safe.

#### Parameters

h | a GstHarness |

#### Returns

a guint number of events in the queue

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstClockTime with min latency

Since: 1.6

### gst_harness_set_upstream_latency ()

    void
    gst_harness_set_upstream_latency (GstHarness *h,
                                      GstClockTime latency);

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

MT safe.

#### Parameters

h | a GstHarness |
latency | a GstClockTime specifying the latency |

#### Returns

a GstClockTime with min latency

Since: 1.6

### gst_harness_set_propose_allocator ()

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

#### Parameters

h | a GstHarness |
allocator | a GstAllocator. | [allow-none][transfer full]
params | a GstAllocationParams. | [allow-none][transfer none]

Since: 1.6

### gst_harness_get_allocator ()

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

#### Parameters

h | a GstHarness |
allocator | the GstAllocator used. | [out][allow-none][transfer none]
params | the GstAllocationParams of `allocator` . | [out][allow-none][transfer full]

Since: 1.6

### gst_harness_add_src ()

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

#### Parameters

h | a GstHarness |
src_element_name | a gchar with the name of a GstElement |
has_clock_wait | a gboolean specifying if the GstElement uses gst_clock_wait_id internally. |

Since: 1.6

### gst_harness_add_src_harness ()

    void
    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 greate 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.

#### Parameters

h | a GstHarness |
src_harness | a GstHarness to be added as a src-harness. | [transfer full]
has_clock_wait | a gboolean specifying if the GstElement uses gst_clock_wait_id internally. |

Since: 1.6

### gst_harness_add_src_parse ()

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

#### Parameters

h | a GstHarness |
launchline | a gchar describing a gst-launch type line |
has_clock_wait | a gboolean specifying if the GstElement uses gst_clock_wait_id internally. |

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstFlowReturn with the result of the push

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.

#### Parameters

h | a GstHarness |
cranks | a gint with the number of calls to gst_harness_crank_single_clock_wait |
pushes | a gint with the number of calls to gst_harness_push |

#### Returns

a GstFlowReturn with the result of the push

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 GstBuffers, this transfers a GstEvent from the src-GstHarness to the main-GstHarness. Note that some GstEvents are being transferred automagically. Look at sink_forward_pad for details.

MT safe.

#### Parameters

h | a GstHarness |

#### Returns

a gboolean with the result of the push

Since: 1.6

### gst_harness_add_sink ()

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

#### Parameters

h | a GstHarness |
sink_element_name | a gchar with the name of a GstElement |

Since: 1.6

### gst_harness_add_sink_harness ()

    void
    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 acheived using gst_harness_new directly on the sink.

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

MT safe.

#### Parameters

h | a GstHarness |
sink_harness | a GstHarness to be added as a sink-harness. | [transfer full]

Since: 1.6

### gst_harness_add_sink_parse ()

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

#### Parameters

h | a GstHarness |
launchline | a gchar with the name of a GstElement |

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.

#### Parameters

h | a GstHarness |

#### Returns

a GstFlowReturn with the result of the push

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.

#### Parameters

h | a GstHarness |
pushes | a gint with the number of calls to gst_harness_push_to_sink |

#### Returns

a GstFlowReturn with the result of the push

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

#### Parameters

h | a GstHarness |
element_name | a gchar with a GstElementFactory name |

#### Returns

a GstElement or `NULL` if not found.

[transfer full][allow-none]

Since: 1.6

### gst_harness_set ()

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

#### Parameters

h | a GstHarness |
element_name | a gchar with a GstElementFactory name |
first_property_name | a gchar with the first property name |
... | value for the first property, followed optionally by more name/value pairs, followed by `NULL` |

Since: 1.6

### gst_harness_get ()

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

#### Parameters

h | a GstHarness |
element_name | a gchar with a GstElementFactory name |
first_property_name | a gchar with the first property name |
... | return location for the first property, followed optionally by more name/return location pairs, followed by `NULL` |

Since: 1.6

### gst_harness_add_probe ()

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

#### Parameters

h | a GstHarness |
element_name | a gchar with a GstElementFactory name |
pad_name | a gchar with the name of the pad to attach the probe to |
mask | a GstPadProbeType (see gst_pad_add_probe) |
callback | a GstPadProbeCallback (see gst_pad_add_probe) |
user_data | a gpointer (see gst_pad_add_probe) |
destroy_data | a GDestroyNotify (see gst_pad_add_probe) |

Since: 1.6

### gst_harness_stress_thread_stop ()

    guint
    gst_harness_stress_thread_stop (GstHarnessThread *t);

Stop the running GstHarnessThread

MT safe.

#### Parameters

t | a GstHarnessThread |

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.

[skip]

#### Parameters

h | a GstHarness |
init | a GFunc that is called initially and only once. | [allow-none]
callback | a GFunc that is called as often as possible |
data | a gpointer with custom data to pass to the `callback` function |
sleep | a gulong specifying how long to sleep in (microseconds) for each call to the `callback` |

#### Returns

a GstHarnessThread

Since: 1.6

### gst_harness_stress_statechange_start()

    #define             gst_harness_stress_statechange_start(h)

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

[skip]

#### Parameters

h | a GstHarness |
sleep | a gulong specifying how long to sleep in (microseconds) for each state-change |

#### Returns

a GstHarnessThread

Since: 1.6

### gst_harness_stress_push_buffer_start()

    #define             gst_harness_stress_push_buffer_start(h, c, s, b)

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

[skip]

#### Parameters

h | a GstHarness |
caps | a GstCaps for the GstBuffer |
segment | a GstSegment |
buf | a GstBuffer to push |
sleep | a gulong specifying how long to sleep in (microseconds) for each call to gst_pad_push |

#### Returns

a GstHarnessThread

Since: 1.6

### GstHarnessPrepareBufferFunc ()

    GstBuffer *
    (*GstHarnessPrepareBufferFunc) (GstHarness *h,
                                    gpointer data);

#### Parameters

h | a GstHarness |
data | user data |

Since: 1.6

### gst_harness_stress_push_buffer_with_cb_start()

    #define             gst_harness_stress_push_buffer_with_cb_start(h, c, s, f, d, n)

### 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 in intervals of `sleep` microseconds.

MT safe.

[skip]

#### Parameters

h | a GstHarness |
caps | a GstCaps for the GstBuffer |
segment | a GstSegment |
func | a GstHarnessPrepareBufferFunc function called before every iteration to prepare / create a GstBuffer for pushing |
data | a gpointer with data to the GstHarnessPrepareBufferFunc function |
notify | a GDestroyNotify that is called for every push to allow cleaning up the GstBuffer. (like gst_buffer_unref) |
sleep | a gulong specifying how long to sleep in (microseconds) for each call to gst_pad_push |

#### Returns

a GstHarnessThread

Since: 1.6

### gst_harness_stress_push_event_start()

    #define             gst_harness_stress_push_event_start(h, e)

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

[skip]

#### Parameters

h | a GstHarness |
event | a GstEvent to push |
sleep | a gulong specifying how long to sleep in (microseconds) for each gst_event_push with `event` |

#### Returns

a GstHarnessThread

Since: 1.6

### gst_harness_stress_send_upstream_event_start()

    #define             gst_harness_stress_send_upstream_event_start(h, e)

### 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. Pushing events should generally be OOB events. If you need serialized events, you may use a custom stress thread which both pushes buffers and events.

MT safe.

[skip]

#### Parameters

h | a GstHarness |
event | a GstEvent to push |
sleep | a gulong specifying how long to sleep in (microseconds) for each gst_event_push with `event` |

#### Returns

a GstHarnessThread

Since: 1.6

### gst_harness_stress_property_start()

    #define             gst_harness_stress_property_start(h, n, v)

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

[skip]

#### Parameters

h | a GstHarness |
name | a gchar specifying a property name |
value | a GValue to set the property to |
sleep | a gulong specifying how long to sleep in (microseconds) for each g_object_set with `name` and `value` |

#### Returns

a GstHarnessThread

Since: 1.6

### gst_harness_stress_requestpad_start()

    #define             gst_harness_stress_requestpad_start(h, t, n, c, r)

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

[skip]

#### Parameters

h | a GstHarness |
templ | a GstPadTemplate |
name | a gchar |
caps | a GstCaps |
release | a gboolean |
sleep | a gulong specifying how long to sleep in (microseconds) for each gst_element_request_pad |

#### Returns

a GstHarnessThread

Since: 1.6

## Types and Values

### struct GstHarness

    struct GstHarness {
      GstElement * element;

      GstPad * srcpad;
      GstPad * sinkpad;

      GstHarness * src_harness;
      GstHarness * sink_harness;
    };

#### Members

GstElement *`element`; | the element inside the harness |
GstPad *`srcpad`; | the internal harness source pad |
GstPad *`sinkpad`; | the internal harness sink pad |
GstHarness *`src_harness`; | the source (input) harness (if any) |
GstHarness *`sink_harness`; | the sink (output) harness (if any) |

Since: 1.6

### GstHarnessThread

    typedef struct _GstHarnessThread GstHarnessThread;

Opaque handle representing a GstHarness stress testing thread.

Since: 1.6

## See Also

GstTestClock,\