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.

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

pjmedia_clock_create2()

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.

struct pjmedia_clock_param

Public Members

unsigned usec_interval

The frame interval, in microseconds.

unsigned clock_rate

The media clock rate, to determine timestamp increment for each call.