gstreamer-rs/docs/gstreamer-net/docs.md

141 lines
5 KiB
Markdown
Raw Normal View History

2017-12-16 12:53:48 +00:00
<!-- file * -->
<!-- struct NetClientClock -->
`NetClientClock` implements a custom `gst::Clock` that synchronizes its time
to a remote time provider such as `NetTimeProvider`. `NtpClock`
implements a `gst::Clock` that synchronizes its time to a remote NTPv4 server.
A new clock is created with `NetClientClock::new` or
`NtpClock::new`, which takes the address and port of the remote time
provider along with a name and an initial time.
This clock will poll the time provider and will update its calibration
parameters based on the local and remote observations.
The "round-trip" property limits the maximum round trip packets can take.
Various parameters of the clock can be configured with the parent `gst::Clock`
"timeout", "window-size" and "window-threshold" object properties.
A `NetClientClock` and `NtpClock` is typically set on a `gst::Pipeline` with
`gst::Pipeline::use_clock`.
If you set a `gst::Bus` on the clock via the "bus" object property, it will
2021-04-11 19:38:18 +00:00
send [`crate::gst::MessageType::Element`] (XXX: @-reference does not belong to NetClientClock!) messages with an attached `gst::Structure` containing
2017-12-16 12:53:48 +00:00
statistics about clock accuracy and network traffic.
# Implements
[`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`]
2017-12-16 12:53:48 +00:00
<!-- impl NetClientClock::fn new -->
2020-06-19 09:49:13 +00:00
Create a new `NetClientClock` that will report the time
2017-12-16 12:53:48 +00:00
provided by the `NetTimeProvider` on `remote_address` and
`remote_port`.
## `name`
a name for the clock
## `remote_address`
the address or hostname of the remote clock provider
## `remote_port`
the port of the remote clock provider
## `base_time`
initial time of the clock
# Returns
a new `gst::Clock` that receives a time from the remote
clock.
<!-- struct NetTimeProvider -->
This object exposes the time of a `gst::Clock` on the network.
A `NetTimeProvider` is created with `NetTimeProvider::new` which
takes a `gst::Clock`, an address and a port number as arguments.
After creating the object, a client clock such as `NetClientClock` can
query the exposed clock over the network for its values.
The `NetTimeProvider` typically wraps the clock used by a `gst::Pipeline`.
# Implements
[`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`]
2017-12-16 12:53:48 +00:00
<!-- impl NetTimeProvider::fn new -->
Allows network clients to get the current time of `clock`.
## `clock`
a `gst::Clock` to export over the network
## `address`
an address to bind on as a dotted quad
(xxx.xxx.xxx.xxx), IPv6 address, or NULL to bind to all addresses
## `port`
a port to bind on, or 0 to let the kernel choose
# Returns
the new `NetTimeProvider`, or NULL on error
<!-- struct NtpClock -->
# Implements
[`NetClientClockExt`](trait@crate::NetClientClockExt), [`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`]
2017-12-16 12:53:48 +00:00
<!-- impl NtpClock::fn new -->
Create a new `NtpClock` that will report the time provided by
the NTPv4 server on `remote_address` and `remote_port`.
## `name`
a name for the clock
## `remote_address`
the address or hostname of the remote clock provider
## `remote_port`
the port of the remote clock provider
## `base_time`
initial time of the clock
# Returns
a new `gst::Clock` that receives a time from the remote
clock.
<!-- struct PtpClock -->
GstPtpClock implements a PTP (IEEE1588:2008) ordinary clock in slave-only
mode, that allows a GStreamer pipeline to synchronize to a PTP network
clock in some specific domain.
The PTP subsystem can be initialized with `gst_ptp_init`, which then starts
a helper process to do the actual communication via the PTP ports. This is
required as PTP listens on ports < 1024 and thus requires special
privileges. Once this helper process is started, the main process will
synchronize to all PTP domains that are detected on the selected
interfaces.
`PtpClock::new` then allows to create a GstClock that provides the PTP
time from a master clock inside a specific PTP domain. This clock will only
return valid timestamps once the timestamps in the PTP domain are known. To
check this, you can use `gst::ClockExt::wait_for_sync`, the GstClock::synced
signal and `gst::ClockExt::is_synced`.
To gather statistics about the PTP clock synchronization,
`gst_ptp_statistics_callback_add` can be used. This gives the application
the possibility to collect all kinds of statistics from the clock
synchronization.
# Implements
[`trait@gst::ClockExt`], [`trait@gst::ObjectExt`], [`trait@glib::object::ObjectExt`]
2017-12-16 12:53:48 +00:00
<!-- impl PtpClock::fn new -->
Creates a new PTP clock instance that exports the PTP time of the master
clock in `domain`. This clock can be slaved to other clocks as needed.
If `gst_ptp_init` was not called before, this will call `gst_ptp_init` with
default parameters.
This clock only returns valid timestamps after it received the first
times from the PTP master clock on the network. Once this happens the
GstPtpClock::internal-clock property will become non-NULL. You can
check this with `gst::ClockExt::wait_for_sync`, the GstClock::synced signal and
`gst::ClockExt::is_synced`.
## `name`
Name of the clock
## `domain`
PTP domain
2018-03-20 10:36:29 +00:00
# Returns
A new `gst::Clock`