GstValidateScenario: GstValidate Reference Manual

## GstValidateScenario GstValidateScenario — A GstValidateScenario represents a set of actions to be executed on a pipeline. |

## Functions

GstValidateExecuteActionReturn | (*GstValidateExecuteAction) ()
gboolean | gst_validate_print_action_types ()
gboolean | gst_validate_list_scenarios ()
GstValidateActionType * | gst_validate_register_action_type ()
gboolean | gst_validate_action_get_clocktime ()
gboolean | gst_validate_scenario_execute_seek ()
void | gst_validate_action_set_done ()
GstValidateScenario * | gst_validate_action_get_scenario ()

## Properties

gboolean | execute-on-idle | Read / Write
gboolean | handles-states | Read
GstValidateRunner * | validate-runner | Read / Write / Construct Only

## Signals

void | done | Run Last

## Types and Values

| GstValidateAction
struct | GstValidateActionParameter
| GstValidateScenario
| GstValidateScenarioClass
| GstValidateActionType

## Object Hierarchy

        GBoxed
        ├── GstValidateAction
        ╰── GstValidateActionType
        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstValidateScenario

## Implemented Interfaces

GstValidateScenario implements GstValidateReporter.

## Description

A GstValidateScenario represents the scenario that will be executed on a GstPipeline. It is basically an ordered list of GstValidateAction that will be executed during the execution of the pipeline.

Possible configurations (see GST_VALIDATE_CONFIG):

- scenario-action-execution-interval: Sets the interval in milliseconds (1/1000ths of a second), between which actions will be executed, setting it to 0 means "execute in idle". The default value is 10ms.

## Functions

### GstValidateExecuteAction ()

    GstValidateExecuteActionReturn
    (*GstValidateExecuteAction) (GstValidateScenario *scenario,
                                 GstValidateAction *action);

A function that executes a GstValidateAction

#### Parameters

scenario | The GstValidateScenario from which the `action` is executed |
action | The GstValidateAction being executed |

#### Returns

a GstValidateExecuteActionReturn

### gst_validate_print_action_types ()

    gboolean
    gst_validate_print_action_types (const gchar **wanted_types,
                                     gint num_wanted_types);

Prints the action types details wanted in `wanted_types`

#### Parameters

wanted_types | (optional): List of types to be printed. | [array length=num_wanted_types]
num_wanted_types | Length of `wanted_types` . | [optional]

#### Returns

True if all types could be printed

### gst_validate_list_scenarios ()

    gboolean
    gst_validate_list_scenarios (gchar **scenarios,
                                 gint num_scenarios,
                                 gchar *output_file);

### gst_validate_register_action_type ()

    GstValidateActionType *
    gst_validate_register_action_type (const gchar *type_name,
                                       const gchar *implementer_namespace,
                                       GstValidateExecuteAction function,
                                       GstValidateActionParameter *parameters,
                                       const gchar *description,
                                       GstValidateActionTypeFlags flags);

Register a new action type to the action type system. If the action type already exists, it will be overriden by that new definition

#### Parameters

type_name | The name of the new action type to add |
implementer_namespace | The namespace of the implementer of the action type. That should always be the name of the GstPlugin as retrieved with gst_plugin_get_name when the action type is register inside a plugin. |
function | The function to be called to execute the action. | [scope notified]
parameters | The GstValidateActionParameter usable as parameter of the type. | [allow-none][array zero-terminated=1][element-type GstValidate.ActionParameter]
description | A description of the new type |
flags | The GstValidateActionTypeFlags to set on the new action type |

#### Returns

The newly created action type or the already registered action type if it had a higher rank.

[transfer none]

### gst_validate_action_get_clocktime ()

    gboolean
    gst_validate_action_get_clocktime (GstValidateScenario *scenario,
                                       GstValidateAction *action,
                                       const gchar *name,
                                       GstClockTime *retval);

Get a time value for the `name` parameter of an action. This method should be called to retrieved and compute a timed value of a given action. It will first try to retrieve the value as a double, then get it as a string and execute any formula taking into account the 'position' and 'duration' variables. And it will always convert that value to a GstClockTime.

#### Parameters

scenario | The GstValidateScenario from which to get a time for a parameter of an action |
action | The action from which to retrieve the time for `name` parameter. |
name | The name of the parameter for which to retrieve a time |
retval | The return value for the wanted time. | [out]

#### Returns

`TRUE` if the time value could be retrieved/computed or `FALSE` otherwise

### gst_validate_scenario_execute_seek ()

    gboolean
    gst_validate_scenario_execute_seek (GstValidateScenario *scenario,
                                        GstValidateAction *action,
                                        gdouble rate,
                                        GstFormat format,
                                        GstSeekFlags flags,
                                        GstSeekType start_type,
                                        GstClockTime start,
                                        GstSeekType stop_type,
                                        GstClockTime stop);

Executes a seek event on the scenario' pipeline. You should always use that method when you want to execute a seek inside a new action types so that the scenario state is updated taking into account that seek.

For more information you should have a look at gst_event_new_seek

#### Parameters

scenario | The GstValidateScenario for which to execute a seek action |
action | The seek action to execute |
rate | The playback rate of the seek |
format | The GstFormat of the seek |
flags | The GstSeekFlags of the seek |
start_type | The GstSeekType of the start value of the seek |
start | The start time of the seek |
stop_type | The GstSeekType of the stop value of the seek |
stop | The stop time of the seek |

#### Returns

`TRUE` if the seek could be executed, `FALSE` otherwise

### gst_validate_action_set_done ()

    void
    gst_validate_action_set_done (GstValidateAction *action);

### gst_validate_action_get_scenario ()

    GstValidateScenario *
    gst_validate_action_get_scenario (GstValidateAction *action);

Retrieve the scenario from which `action` is executed.

#### Parameters

action | The action from which to retrieve the scenario |

#### Returns

The scenario from which the action is being executed.

[transfer full]

## Types and Values

### GstValidateAction

    typedef struct {
      GstMiniObject          mini_object;

      const gchar *type;
      const gchar *name;
      GstStructure *structure;
      GstValidateScenario *scenario;
    } GstValidateAction;

The GstValidateAction defined to be executed as part of a scenario

Only access it from the default main context.

#### Members

GstMiniObject `mini_object`; |  |
const gchar *`type`; | The type of the GstValidateAction, which is the name of the GstValidateActionType registered with gst_validate_register_action_type |
const gchar *`name`; | The name of the action, set from the user in the scenario |
GstStructure *`structure`; | the GstStructure defining the action |
GstValidateScenario *`scenario`; | The scenario for this action. This is not thread safe and should be accessed exculsively from the main thread. If you need to access it from another thread use the gst_validate_action_get_scenario method |

### struct GstValidateActionParameter

    struct GstValidateActionParameter {
      const gchar  *name;
      const gchar  *description;
      gboolean     mandatory;
      const gchar  *types;
      const gchar  *possible_variables;
      const gchar  *def;
    };

#### Members

const gchar *`name`; | The name of the parameter |
const gchar *`description`; | The description of the parameter |
gboolean `mandatory`; | Whether the parameter is mandatory for a specific action type |
const gchar *`types`; | The types the parameter can take described as a string. It can be precisely describing how the typing works using '\n' between the various acceptable types. |
const gchar *`possible_variables`; | The name of the variables that can be used to compute the value of the parameter. For example for the start value of a seek action, we will accept to take 'duration' which will be replace by the total duration of the stream on which the action is executed. |
const gchar *`def`; | The default value of a parameter as a string, should be `NULL` for mandatory streams. |

### GstValidateScenario

    typedef struct {
      GstElement *pipeline;
    } GstValidateScenario;

#### Members

GstElement *`pipeline`; | The GstPipeline on which the scenario is being executed. |

### GstValidateScenarioClass

    typedef struct {
      GstObjectClass parent_class;
    } GstValidateScenarioClass;

### GstValidateActionType

    typedef struct {
      GstMiniObject          mini_object;

      gchar *name;
      gchar *implementer_namespace;

      GstValidatePrepareAction prepare;
      GstValidateExecuteAction execute;

      GstValidateActionParameter *parameters;

      gchar *description;
      GstValidateActionTypeFlags flags;

      GstRank rank;

      GstValidateActionType *overriden_type;
    } GstValidateActionType;

#### Members

GstMiniObject `mini_object`; |  |
gchar *`name`; | The name of the new action type to add |
gchar *`implementer_namespace`; | The namespace of the implementer of the action type |
GstValidatePrepareAction `prepare`; |  |
GstValidateExecuteAction `execute`; | The function to be called to execute the action |
GstValidateActionParameter *`parameters`; | The GstValidateActionParameter usable as parameter of the type. | [allow-none][array zero-terminated=1][element-type GstValidate.ActionParameter]
gchar *`description`; | A description of the new type |
GstValidateActionTypeFlags `flags`; | The flags of the action type |
GstRank `rank`; |  |
GstValidateActionType *`overriden_type`; |  |

## Property Details

### The `“execute-on-idle”` property

      “execute-on-idle”          gboolean

Always execute actions on idle and do not chain them to execute as fast as possible. That is usefull if action execution can lead to the addition of source on the same main loop. It allows those other GSources to have a chance to be dispatch between validate actions execution.

Flags: Read / Write

Default value: FALSE

### The `“handles-states”` property

      “handles-states”           gboolean

True if the application should not set handle the first state change False if it is application responsibility.

Flags: Read

Default value: FALSE

### The `“validate-runner”` property

      “validate-runner”          GstValidateRunner *

The Validate runner to report errors to.

Flags: Read / Write / Construct Only

## Signal Details

### The `“done”` signal

    void
    user_function (GstValidateScenario *scenario,
                   gpointer             user_data)

Emitted once all actions have been executed

#### Parameters

scenario | The scenario runing |
user_data | user data set when the signal handler was connected. |

Flags: Run Last