Group PJMEDIA_CLOCK
- group PJMEDIA_CLOCK
Interface for generating clock.
The clock generator provides the application with media timing, and it is used by the Master Port for its sound clock.
The clock generator may be configured to run asynchronously (the default behavior) or synchronously. When it is run asynchronously, it will call the application’s callback every time the clock tick expires. When it is run synchronously, application must continuously polls the clock generator to synchronize the timing.
Typedefs
-
typedef struct pjmedia_clock pjmedia_clock
Opaque declaration for media clock.
-
typedef void pjmedia_clock_callback(const pj_timestamp *ts, void *user_data)
Type of media clock callback.
- Param ts:
Current timestamp, in samples.
- Param user_data:
Application data that is passed when the clock was created.
Enums
-
enum pjmedia_clock_options
Options when creating the clock.
Values:
-
enumerator PJMEDIA_CLOCK_NO_ASYNC
Prevents the clock from running asynchronously. In this case, application must poll the clock continuously by calling pjmedia_clock_wait() in order to synchronize timing.
-
enumerator PJMEDIA_CLOCK_NO_HIGHEST_PRIO
Prevent the clock from setting it’s thread to highest priority.
-
enumerator PJMEDIA_CLOCK_NO_ASYNC
Functions
-
pj_status_t pjmedia_clock_src_init(pjmedia_clock_src *clocksrc, pjmedia_type media_type, unsigned clock_rate, unsigned ptime_usec)
This is an auxiliary function to initialize the media clock source.
- Parameters:
clocksrc – The clock source to be initialized.
media_type – The media type.
clock_rate – The clock rate.
ptime_usec – Media frame interval (in usec).
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjmedia_clock_src_update(pjmedia_clock_src *clocksrc, const pj_timestamp *timestamp)
This function updates the clock source’s timestamp. Application should use this function instead of updating the timestamp directly since this function will also update the last_update field of the clock source.
- Parameters:
clocksrc – The clock source to be updated.
timestamp – The new timestamp, can be NULL if the current timestamp does not change (in this case it will only update the last_update field).
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjmedia_clock_src_get_current_timestamp(const pjmedia_clock_src *clocksrc, pj_timestamp *timestamp)
This function gets the clock source’s current timestamp. Application should use this function instead of accessing the timestamp directly since this function will calculate the predicted timestamp for current time, based on the values of timestamp, last_update, and clock_rate.
- Parameters:
clocksrc – The clock source.
timestamp – Argument to receive the current timestamp
- Returns:
PJ_SUCCESS on success.
-
pj_uint32_t pjmedia_clock_src_get_time_msec(const pjmedia_clock_src *clocksrc)
This function gets the clock source’s time in msec.
- Parameters:
clocksrc – The clock source.
- Returns:
The clock source’s time (in msec).
-
pj_status_t pjmedia_clock_create(pj_pool_t *pool, unsigned clock_rate, unsigned channel_count, unsigned samples_per_frame, unsigned options, pjmedia_clock_callback *cb, void *user_data, pjmedia_clock **p_clock)
Create media clock. This creates a media clock object that will run periodically at an interval that is calculated from the audio parameters. Once created, application must call pjmedia_clock_start() to actually start the clock.
See also
- Parameters:
pool – Pool to allocate memory.
clock_rate – Number of samples per second.
channel_count – Number of channel.
samples_per_frame – Number of samples per frame. This argument along with clock_rate and channel_count, specifies the interval of each clock run (or clock ticks).
options – Bitmask of pjmedia_clock_options.
cb – Callback to be called for each clock tick.
user_data – User data, which will be passed to the callback.
p_clock – Pointer to receive the clock instance.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjmedia_clock_create2(pj_pool_t *pool, const pjmedia_clock_param *param, unsigned options, pjmedia_clock_callback *cb, void *user_data, pjmedia_clock **p_clock)
Create media clock. This creates a media clock object that will run periodically at the specified interval. Once created, application must call pjmedia_clock_start() to actually start the clock.
- Parameters:
pool – Pool to allocate memory.
param – The clock parameter.
options – Bitmask of pjmedia_clock_options.
cb – Callback to be called for each clock tick.
user_data – User data, which will be passed to the callback.
p_clock – Pointer to receive the clock instance.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjmedia_clock_start(pjmedia_clock *clock)
Start the clock. For clock created with asynchronous flag set to TRUE, this may start a worker thread for the clock (depending on the backend clock implementation being used).
- Parameters:
clock – The media clock.
- Returns:
PJ_SUCCES on success.
-
pj_status_t pjmedia_clock_stop(pjmedia_clock *clock)
Stop the clock. When the function returns PJ_SUCCESS, it is guaranteed that the clock thread (if any) has stopped and the callback has completed. But if the function is called from within the clock’s callback itself, the callback will still be running until completion. In that case, the function will only stop future callbacks and returns PJ_EBUSY.
- Parameters:
clock – The media clock.
- Returns:
PJ_SUCCES on success, or PJ_EBUSY.
-
pj_status_t pjmedia_clock_modify(pjmedia_clock *clock, const pjmedia_clock_param *param)
Modify the clock’s parameter.
- Parameters:
clock – The media clock.
param – The clock’s new parameter.
- Returns:
PJ_SUCCES on success.
-
pj_bool_t pjmedia_clock_wait(pjmedia_clock *clock, pj_bool_t wait, pj_timestamp *ts)
Poll the media clock, and execute the callback when the clock tick has elapsed. This operation is only valid if the clock is created with async flag set to FALSE.
- Parameters:
clock – The media clock.
wait – If non-zero, then the function will block until a clock tick elapsed and callback has been called.
ts – Optional argument to receive the current timestamp.
- Returns:
Non-zero if clock tick has elapsed, or FALSE if the function returns before a clock tick has elapsed.
-
pj_status_t pjmedia_clock_destroy(pjmedia_clock *clock)
Destroy the clock.
- Parameters:
clock – The media clock.
- Returns:
PJ_SUCCES on success.
-
struct pjmedia_clock_src
- #include <clock.h>
Media clock source.
Public Members
-
pjmedia_type media_type
Media type.
-
unsigned clock_rate
Clock rate.
-
unsigned ptime_usec
Frame interval (in usec).
-
pj_timestamp timestamp
The timestamp field holds an increasing value in samples and its value is expected to be increased by clock_rate samples per second.
-
pj_timestamp last_update
Timestamp’s last update. The last_update field contains a value in ticks, and it is expected to be increased by pj_get_timestamp_freq() ticks per second.
-
pjmedia_type media_type
-
struct pjmedia_clock_param
-
typedef struct pjmedia_clock pjmedia_clock