Home --> Documentations --> PJMEDIA Reference

Data Structures | Typedefs | Enumerations | Functions

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

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.

Parameters
tsCurrent timestamp, in samples.
user_dataApplication data that is passed when the clock was created.

Enumeration Type Documentation

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

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
clocksrcThe clock source to be initialized.
media_typeThe media type.
clock_rateThe clock rate.
ptime_usecMedia 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
clocksrcThe clock source to be updated.
timestampThe 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
clocksrcThe clock source.
timestampArgument 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
clocksrcThe 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
poolPool to allocate memory.
clock_rateNumber of samples per second.
channel_countNumber of channel.
samples_per_frameNumber of samples per frame. This argument along with clock_rate and channel_count, specifies the interval of each clock run (or clock ticks).
optionsBitmask of pjmedia_clock_options.
cbCallback to be called for each clock tick.
user_dataUser data, which will be passed to the callback.
p_clockPointer 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
poolPool to allocate memory.
paramThe clock parameter.
optionsBitmask of pjmedia_clock_options.
cbCallback to be called for each clock tick.
user_dataUser data, which will be passed to the callback.
p_clockPointer 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
clockThe media clock.
Returns
PJ_SUCCES on success.
pj_status_t pjmedia_clock_stop ( pjmedia_clock clock)

Stop the clock.

Parameters
clockThe media clock.
Returns
PJ_SUCCES on success.
pj_status_t pjmedia_clock_modify ( pjmedia_clock clock,
const pjmedia_clock_param param 
)

Modify the clock's parameter.

Parameters
clockThe media clock.
paramThe 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
clockThe media clock.
waitIf non-zero, then the function will block until a clock tick elapsed and callback has been called.
tsOptional 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
clockThe media clock.
Returns
PJ_SUCCES on success.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.