Clock Generator

Interface for generating clock. More...

Data Structures
struct	pjmedia_clock_src
struct	pjmedia_clock_param

Typedefs
typedef struct pjmedia_clock	pjmedia_clock
typedef void	pjmedia_clock_callback(const pj_timestamp *ts, void *user_data)

Enumerations
enum	pjmedia_clock_options {   PJMEDIA_CLOCK_NO_ASYNC = 1 ,   PJMEDIA_CLOCK_NO_HIGHEST_PRIO = 2 }

Functions
pj_status_t	pjmedia_clock_src_init (pjmedia_clock_src *clocksrc, pjmedia_type media_type, unsigned clock_rate, unsigned ptime_usec)
pj_status_t	pjmedia_clock_src_update (pjmedia_clock_src *clocksrc, const pj_timestamp *timestamp)
pj_status_t	pjmedia_clock_src_get_current_timestamp (const pjmedia_clock_src *clocksrc, pj_timestamp *timestamp)
pj_uint32_t	pjmedia_clock_src_get_time_msec (const pjmedia_clock_src *clocksrc)
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)
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)
pj_status_t	pjmedia_clock_start (pjmedia_clock *clock)
pj_status_t	pjmedia_clock_stop (pjmedia_clock *clock)
pj_status_t	pjmedia_clock_modify (pjmedia_clock *clock, const pjmedia_clock_param *param)
pj_bool_t	pjmedia_clock_wait (pjmedia_clock *clock, pj_bool_t wait, pj_timestamp *ts)
pj_status_t	pjmedia_clock_destroy (pjmedia_clock *clock)

Detailed Description

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.

Typedef Documentation

pjmedia_clock

typedef struct pjmedia_clock pjmedia_clock

Opaque declaration for media clock.

pjmedia_clock_callback

typedef void pjmedia_clock_callback(const pj_timestamp *ts, void *user_data)

Type of media clock callback.

Parameters

ts	Current timestamp, in samples.
user_data	Application data that is passed when the clock was created.

Enumeration Type Documentation

pjmedia_clock_options

enum pjmedia_clock_options

Options when creating the clock.

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.
PJMEDIA_CLOCK_NO_HIGHEST_PRIO	Prevent the clock from setting it's thread to highest priority.

Function Documentation

pjmedia_clock_src_init()

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.

pjmedia_clock_src_update()

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.

pjmedia_clock_src_get_current_timestamp()

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.

pjmedia_clock_src_get_time_msec()

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).

pjmedia_clock_create()

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.

pjmedia_clock_create2()

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.

pjmedia_clock_start()

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.

pjmedia_clock_stop()

pj_status_t pjmedia_clock_stop

(

pjmedia_clock *

clock

)

Stop the clock.

Parameters

clock

The media clock.

Returns

PJ_SUCCES on success.

pjmedia_clock_modify()

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.

pjmedia_clock_wait()

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.

pjmedia_clock_destroy()

pj_status_t pjmedia_clock_destroy

(

pjmedia_clock *

clock

)

Destroy the clock.

Parameters

clock

The media clock.

Returns

PJ_SUCCES on success.

References PJ_END_DECL.