## GstProbe

GstProbe — Receive callbacks of data passing

## Synopsis

    #include <gst/gst.h>

                GstProbe;
    gboolean    (*GstProbeCallback)             (GstProbe *probe,
                                                 GstData **data,
                                                 gpointer user_data);
    GstProbe*   gst_probe_new                   (gboolean single_shot,
                                                 GstProbeCallback callback,
                                                 gpointer user_data);
    void        gst_probe_destroy               (GstProbe *probe);
    gboolean    gst_probe_perform               (GstProbe *probe,
                                                 GstData **data);
                GstProbeDispatcher;
    GstProbeDispatcher* gst_probe_dispatcher_new
                                                (void);
    void        gst_probe_dispatcher_destroy    (GstProbeDispatcher *disp);
    void        gst_probe_dispatcher_init       (GstProbeDispatcher *disp);
    void        gst_probe_dispatcher_set_active (GstProbeDispatcher *disp,
                                                 gboolean active);
    void        gst_probe_dispatcher_add_probe  (GstProbeDispatcher *disp,
                                                 GstProbe *probe);
    void        gst_probe_dispatcher_remove_probe
                                                (GstProbeDispatcher *disp,
                                                 GstProbe *probe);
    gboolean    gst_probe_dispatcher_dispatch   (GstProbeDispatcher *disp,
                                                 GstData **data);

## Description

PadProbes are used to be signalled with a callback when certain GstData passes through pads.

Probes are usually used in combination with a probe dispatcher that will enumerate all registered probes to signal them.

## Details

### GstProbe

    typedef struct {
      gboolean		single_shot;

      GstProbeCallback	callback;
      gpointer		user_data;
    } GstProbe;

The probe structure

### GstProbeCallback ()

    gboolean    (*GstProbeCallback)             (GstProbe *probe,
                                                 GstData **data,
                                                 gpointer user_data);

The function that will be called when a probe is activated.

`probe` : | The probe that signalled the callback
`data` : | The GstData that triggered the probe
`user_data` : | user data
Returns : | FALSE if the GstData should be removed from the stream.

### gst_probe_new ()

    GstProbe*   gst_probe_new                   (gboolean single_shot,
                                                 GstProbeCallback callback,
                                                 gpointer user_data);

Create a new probe with the specified parameters

`single_shot` : | TRUE if a single shot probe is required
`callback` : | the function to call when the probe is triggered
`user_data` : | data passed to the callback function
Returns : | a new GstProbe.

### gst_probe_destroy ()

    void        gst_probe_destroy               (GstProbe *probe);

Free the memory associated with the probe.

`probe` : | The probe to destroy

### gst_probe_perform ()

    gboolean    gst_probe_perform               (GstProbe *probe,
                                                 GstData **data);

Perform the callback associated with the given probe.

`probe` : | The probe to trigger
`data` : | the GstData that triggered the probe.
Returns : | the result of the probe callback function.

### GstProbeDispatcher

    typedef struct {
      gboolean		active;

      GSList		*probes;
    } GstProbeDispatcher;

The structure of the probe dispatcher

### gst_probe_dispatcher_new ()

    GstProbeDispatcher* gst_probe_dispatcher_new
                                                (void);

Create a new probe dispatcher

Returns : | a new probe dispatcher.

### gst_probe_dispatcher_destroy ()

    void        gst_probe_dispatcher_destroy    (GstProbeDispatcher *disp);

Free the memory allocated by the probe dispatcher. All pending probes are removed first.

`disp` : | the dispatcher to destroy

### gst_probe_dispatcher_init ()

    void        gst_probe_dispatcher_init       (GstProbeDispatcher *disp);

Initialize the dispatcher. Useful for statically allocated probe dispatchers.

`disp` : | the dispatcher to initialize

### gst_probe_dispatcher_set_active ()

    void        gst_probe_dispatcher_set_active (GstProbeDispatcher *disp,
                                                 gboolean active);

Activate or deactivate the given dispatcher dispatchers.

`disp` : | the dispatcher to activate
`active` : | boolean to indicate activation or deactivation

### gst_probe_dispatcher_add_probe ()

    void        gst_probe_dispatcher_add_probe  (GstProbeDispatcher *disp,
                                                 GstProbe *probe);

Adds the given probe to the dispatcher.

`disp` : | the dispatcher to add the probe to
`probe` : | the probe to add to the dispatcher

### gst_probe_dispatcher_remove_probe ()

    void        gst_probe_dispatcher_remove_probe
                                                (GstProbeDispatcher *disp,
                                                 GstProbe *probe);

Removes the given probe from the dispatcher.

`disp` : | the dispatcher to remove the probe from
`probe` : | the probe to remove from the dispatcher

### gst_probe_dispatcher_dispatch ()

    gboolean    gst_probe_dispatcher_dispatch   (GstProbeDispatcher *disp,
                                                 GstData **data);

Trigger all registered probes on the given dispatcher.

`disp` : | the dispatcher to dispatch
`data` : | the data that triggered the dispatch
Returns : | TRUE if all callbacks returned TRUE.