Mon May 14 04:46:06 2007

Asterisk developer's documentation


chanspy.h File Reference

Asterisk PBX channel spy definitions. More...

#include "asterisk/linkedlists.h"

Include dependency graph for chanspy.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ast_channel_spy
struct  ast_channel_spy_queue

Enumerations

enum  chanspy_flags {
  CHANSPY_MIXAUDIO = (1 << 0), CHANSPY_READ_VOLADJUST = (1 << 1), CHANSPY_WRITE_VOLADJUST = (1 << 2), CHANSPY_FORMAT_AUDIO = (1 << 3),
  CHANSPY_TRIGGER_MODE = (3 << 4), CHANSPY_TRIGGER_READ = (1 << 4), CHANSPY_TRIGGER_WRITE = (2 << 4), CHANSPY_TRIGGER_NONE = (3 << 4),
  CHANSPY_TRIGGER_FLUSH = (1 << 6)
}
enum  chanspy_states { CHANSPY_NEW = 0, CHANSPY_RUNNING = 1, CHANSPY_DONE = 2, CHANSPY_STOP = 3 }

Functions

int ast_channel_spy_add (struct ast_channel *chan, struct ast_channel_spy *spy)
 Adds a spy to a channel, to begin receiving copies of the channel's audio frames.
void ast_channel_spy_free (struct ast_channel_spy *spy)
 Free a spy.
ast_frameast_channel_spy_read_frame (struct ast_channel_spy *spy, unsigned int samples)
 Read one (or more) frames of audio from a channel being spied upon.
void ast_channel_spy_remove (struct ast_channel *chan, struct ast_channel_spy *spy)
 Remove a spy from a channel.
void ast_channel_spy_stop_by_type (struct ast_channel *chan, const char *type)
 Find all spies of a particular type on a channel and stop them.
void ast_channel_spy_trigger_wait (struct ast_channel_spy *spy)
 Efficiently wait until audio is available for a spy, or an exception occurs.


Detailed Description

Asterisk PBX channel spy definitions.

Definition in file chanspy.h.


Enumeration Type Documentation

enum chanspy_flags

Enumerator:
CHANSPY_MIXAUDIO 
CHANSPY_READ_VOLADJUST 
CHANSPY_WRITE_VOLADJUST 
CHANSPY_FORMAT_AUDIO 
CHANSPY_TRIGGER_MODE 
CHANSPY_TRIGGER_READ 
CHANSPY_TRIGGER_WRITE 
CHANSPY_TRIGGER_NONE 
CHANSPY_TRIGGER_FLUSH 

Definition at line 39 of file chanspy.h.

00039                    {
00040    CHANSPY_MIXAUDIO = (1 << 0),
00041    CHANSPY_READ_VOLADJUST = (1 << 1),
00042    CHANSPY_WRITE_VOLADJUST = (1 << 2),
00043    CHANSPY_FORMAT_AUDIO = (1 << 3),
00044    CHANSPY_TRIGGER_MODE = (3 << 4),
00045    CHANSPY_TRIGGER_READ = (1 << 4),
00046    CHANSPY_TRIGGER_WRITE = (2 << 4),
00047    CHANSPY_TRIGGER_NONE = (3 << 4),
00048    CHANSPY_TRIGGER_FLUSH = (1 << 6),
00049 };

enum chanspy_states

Enumerator:
CHANSPY_NEW  spy not yet operating
CHANSPY_RUNNING  normal operation, spy is still operating
CHANSPY_DONE  spy is stopped and already removed from channel
CHANSPY_STOP  spy requested to stop, still attached to channel

Definition at line 32 of file chanspy.h.

00032                     {
00033    CHANSPY_NEW = 0,     /*!< spy not yet operating */
00034    CHANSPY_RUNNING = 1,    /*!< normal operation, spy is still operating */
00035    CHANSPY_DONE = 2,    /*!< spy is stopped and already removed from channel */
00036    CHANSPY_STOP = 3,    /*!< spy requested to stop, still attached to channel */
00037 };


Function Documentation

int ast_channel_spy_add ( struct ast_channel chan,
struct ast_channel_spy spy 
)

Adds a spy to a channel, to begin receiving copies of the channel's audio frames.

Parameters:
chan The channel to add the spy to.
spy A pointer to ast_channel_spy structure describing how the spy is to be used.
Returns:
0 for success, non-zero for failure
Note: This function performs no locking; you must hold the channel's lock before calling this function.

Definition at line 1333 of file channel.c.

References ast_calloc, ast_clear_flag, ast_cond_init(), AST_FORMAT_SLINEAR, ast_getformatname(), AST_LIST_HEAD_INIT_NOLOCK, AST_LIST_INSERT_HEAD, AST_LIST_INSERT_TAIL, ast_log(), ast_set_flag, ast_test_flag, ast_channel_spy::chan, CHANSPY_FORMAT_AUDIO, CHANSPY_MIXAUDIO, CHANSPY_READ_VOLADJUST, CHANSPY_TRIGGER_MODE, CHANSPY_TRIGGER_NONE, CHANSPY_TRIGGER_READ, CHANSPY_TRIGGER_WRITE, CHANSPY_WRITE_VOLADJUST, ast_channel_spy_queue::format, LOG_DEBUG, LOG_WARNING, option_debug, ast_channel_spy::read_queue, ast_channel::spies, ast_channel_spy::trigger, ast_channel_spy::type, and ast_channel_spy::write_queue.

Referenced by start_spying(), and startmon().

01334 {
01335    /* Link the owner channel to the spy */
01336    spy->chan = chan;
01337 
01338    if (!ast_test_flag(spy, CHANSPY_FORMAT_AUDIO)) {
01339       ast_log(LOG_WARNING, "Could not add channel spy '%s' to channel '%s', only audio format spies are supported.\n",
01340          spy->type, chan->name);
01341       return -1;
01342    }
01343 
01344    if (ast_test_flag(spy, CHANSPY_READ_VOLADJUST) && (spy->read_queue.format != AST_FORMAT_SLINEAR)) {
01345       ast_log(LOG_WARNING, "Cannot provide volume adjustment on '%s' format spies\n",
01346          ast_getformatname(spy->read_queue.format));
01347       return -1;
01348    }
01349 
01350    if (ast_test_flag(spy, CHANSPY_WRITE_VOLADJUST) && (spy->write_queue.format != AST_FORMAT_SLINEAR)) {
01351       ast_log(LOG_WARNING, "Cannot provide volume adjustment on '%s' format spies\n",
01352          ast_getformatname(spy->write_queue.format));
01353       return -1;
01354    }
01355 
01356    if (ast_test_flag(spy, CHANSPY_MIXAUDIO) &&
01357        ((spy->read_queue.format != AST_FORMAT_SLINEAR) ||
01358         (spy->write_queue.format != AST_FORMAT_SLINEAR))) {
01359       ast_log(LOG_WARNING, "Cannot provide audio mixing on '%s'-'%s' format spies\n",
01360          ast_getformatname(spy->read_queue.format), ast_getformatname(spy->write_queue.format));
01361       return -1;
01362    }
01363 
01364    if (!chan->spies) {
01365       if (!(chan->spies = ast_calloc(1, sizeof(*chan->spies)))) {
01366          return -1;
01367       }
01368 
01369       AST_LIST_HEAD_INIT_NOLOCK(&chan->spies->list);
01370       AST_LIST_INSERT_HEAD(&chan->spies->list, spy, list);
01371    } else {
01372       AST_LIST_INSERT_TAIL(&chan->spies->list, spy, list);
01373    }
01374 
01375    if (ast_test_flag(spy, CHANSPY_TRIGGER_MODE) != CHANSPY_TRIGGER_NONE) {
01376       ast_cond_init(&spy->trigger, NULL);
01377       ast_set_flag(spy, CHANSPY_TRIGGER_READ);
01378       ast_clear_flag(spy, CHANSPY_TRIGGER_WRITE);
01379    }
01380 
01381    if (option_debug)
01382       ast_log(LOG_DEBUG, "Spy %s added to channel %s\n",
01383          spy->type, chan->name);
01384 
01385    return 0;
01386 }

void ast_channel_spy_free ( struct ast_channel_spy spy  ) 

Free a spy.

Parameters:
spy The spy to free
Returns:
nothing
Note: This function MUST NOT be called with the spy locked.

Definition at line 1468 of file channel.c.

References ast_cond_destroy(), ast_frfree(), AST_LIST_REMOVE_HEAD, ast_mutex_destroy(), ast_test_flag, CHANSPY_DONE, CHANSPY_TRIGGER_MODE, CHANSPY_TRIGGER_NONE, f, ast_channel_spy::lock, ast_channel_spy::read_queue, ast_channel_spy::status, ast_channel_spy::trigger, and ast_channel_spy::write_queue.

Referenced by channel_spy(), and mixmonitor_thread().

01469 {
01470    struct ast_frame *f = NULL;
01471 
01472    if (spy->status == CHANSPY_DONE)
01473       return;
01474 
01475    /* Switch status to done in case we get called twice */
01476    spy->status = CHANSPY_DONE;
01477 
01478    /* Drop any frames in the queue */
01479    while ((f = AST_LIST_REMOVE_HEAD(&spy->write_queue.list, frame_list)))
01480       ast_frfree(f);
01481    while ((f = AST_LIST_REMOVE_HEAD(&spy->read_queue.list, frame_list)))
01482       ast_frfree(f);
01483 
01484    /* Destroy the condition if in use */
01485    if (ast_test_flag(spy, CHANSPY_TRIGGER_MODE) != CHANSPY_TRIGGER_NONE)
01486       ast_cond_destroy(&spy->trigger);
01487 
01488    /* Destroy our mutex since it is no longer in use */
01489    ast_mutex_destroy(&spy->lock);
01490 
01491    return;
01492 }

struct ast_frame* ast_channel_spy_read_frame ( struct ast_channel_spy spy,
unsigned int  samples 
)

Read one (or more) frames of audio from a channel being spied upon.

Parameters:
spy The spy to operate on
samples The number of audio samples to read
Returns:
NULL for failure, one ast_frame pointer, or a chain of ast_frame pointers
This function can return multiple frames if the spy structure needs to be 'flushed' due to mismatched queue lengths, or if the spy structure is configured to return unmixed audio (in which case each call to this function will return a frame of audio from each side of channel).

Note: This function performs no locking; you must hold the spy's lock before calling this function. You must not hold the channel's lock at the same time.

Definition at line 4540 of file channel.c.

References ast_clear_flag, ast_codec_get_len(), ast_frame_adjust_volume(), ast_frame_slinear_sum(), AST_FRAME_VOICE, ast_frdup(), ast_frfree(), AST_LIST_FIRST, AST_LIST_HEAD_SET_NOLOCK, AST_LIST_NEXT, AST_LIST_REMOVE_HEAD, AST_LIST_TRAVERSE, ast_test_flag, CHANSPY_MIXAUDIO, CHANSPY_READ_VOLADJUST, CHANSPY_TRIGGER_FLUSH, CHANSPY_WRITE_VOLADJUST, copy_data_from_queue(), ast_channel_spy_queue::format, ast_frame::frametype, ast_channel_spy::read_queue, ast_channel_spy::read_vol_adjustment, result, ast_channel_spy_queue::samples, ast_channel_spy::write_queue, and ast_channel_spy::write_vol_adjustment.

Referenced by mixmonitor_thread(), and spy_generate().

04541 {
04542    struct ast_frame *result;
04543    /* buffers are allocated to hold SLINEAR, which is the largest format */
04544         short read_buf[samples];
04545         short write_buf[samples];
04546    struct ast_frame *read_frame;
04547    struct ast_frame *write_frame;
04548    int need_dup;
04549    struct ast_frame stack_read_frame = { .frametype = AST_FRAME_VOICE,
04550                      .subclass = spy->read_queue.format,
04551                      .data = read_buf,
04552                      .samples = samples,
04553                      .datalen = ast_codec_get_len(spy->read_queue.format, samples),
04554    };
04555    struct ast_frame stack_write_frame = { .frametype = AST_FRAME_VOICE,
04556                       .subclass = spy->write_queue.format,
04557                       .data = write_buf,
04558                       .samples = samples,
04559                       .datalen = ast_codec_get_len(spy->write_queue.format, samples),
04560    };
04561 
04562    /* if a flush has been requested, dump everything in whichever queue is larger */
04563    if (ast_test_flag(spy, CHANSPY_TRIGGER_FLUSH)) {
04564       if (spy->read_queue.samples > spy->write_queue.samples) {
04565          if (ast_test_flag(spy, CHANSPY_READ_VOLADJUST)) {
04566             AST_LIST_TRAVERSE(&spy->read_queue.list, result, frame_list)
04567                ast_frame_adjust_volume(result, spy->read_vol_adjustment);
04568          }
04569          result = AST_LIST_FIRST(&spy->read_queue.list);
04570          AST_LIST_HEAD_SET_NOLOCK(&spy->read_queue.list, NULL);
04571          spy->read_queue.samples = 0;
04572       } else {
04573          if (ast_test_flag(spy, CHANSPY_WRITE_VOLADJUST)) {
04574             AST_LIST_TRAVERSE(&spy->write_queue.list, result, frame_list)
04575                ast_frame_adjust_volume(result, spy->write_vol_adjustment);
04576          }
04577          result = AST_LIST_FIRST(&spy->write_queue.list);
04578          AST_LIST_HEAD_SET_NOLOCK(&spy->write_queue.list, NULL);
04579          spy->write_queue.samples = 0;
04580       }
04581       ast_clear_flag(spy, CHANSPY_TRIGGER_FLUSH);
04582       return result;
04583    }
04584 
04585    if ((spy->read_queue.samples < samples) || (spy->write_queue.samples < samples))
04586       return NULL;
04587 
04588    /* short-circuit if both head frames have exactly what we want */
04589    if ((AST_LIST_FIRST(&spy->read_queue.list)->samples == samples) &&
04590        (AST_LIST_FIRST(&spy->write_queue.list)->samples == samples)) {
04591       read_frame = AST_LIST_REMOVE_HEAD(&spy->read_queue.list, frame_list);
04592       write_frame = AST_LIST_REMOVE_HEAD(&spy->write_queue.list, frame_list);
04593 
04594       spy->read_queue.samples -= samples;
04595       spy->write_queue.samples -= samples;
04596 
04597       need_dup = 0;
04598    } else {
04599       copy_data_from_queue(&spy->read_queue, read_buf, samples);
04600       copy_data_from_queue(&spy->write_queue, write_buf, samples);
04601 
04602       read_frame = &stack_read_frame;
04603       write_frame = &stack_write_frame;
04604       need_dup = 1;
04605    }
04606    
04607    if (ast_test_flag(spy, CHANSPY_READ_VOLADJUST))
04608       ast_frame_adjust_volume(read_frame, spy->read_vol_adjustment);
04609 
04610    if (ast_test_flag(spy, CHANSPY_WRITE_VOLADJUST))
04611       ast_frame_adjust_volume(write_frame, spy->write_vol_adjustment);
04612 
04613    if (ast_test_flag(spy, CHANSPY_MIXAUDIO)) {
04614       ast_frame_slinear_sum(read_frame, write_frame);
04615 
04616       if (need_dup)
04617          result = ast_frdup(read_frame);
04618       else {
04619          result = read_frame;
04620          ast_frfree(write_frame);
04621       }
04622    } else {
04623       if (need_dup) {
04624          result = ast_frdup(read_frame);
04625          AST_LIST_NEXT(result, frame_list) = ast_frdup(write_frame);
04626       } else {
04627          result = read_frame;
04628          AST_LIST_NEXT(result, frame_list) = write_frame;
04629       }
04630    }
04631 
04632    return result;
04633 }

void ast_channel_spy_remove ( struct ast_channel chan,
struct ast_channel_spy spy 
)

Remove a spy from a channel.

Parameters:
chan The channel to remove the spy from
spy The spy to be removed
Returns:
nothing
Note: This function performs no locking; you must hold the channel's lock before calling this function.

Definition at line 1458 of file channel.c.

References AST_LIST_REMOVE, ast_channel::spies, spy_cleanup(), and spy_detach().

Referenced by channel_spy().

01459 {
01460    if (!chan->spies)
01461       return;
01462 
01463    AST_LIST_REMOVE(&chan->spies->list, spy, list);
01464    spy_detach(spy, chan);
01465    spy_cleanup(chan);
01466 }

void ast_channel_spy_stop_by_type ( struct ast_channel chan,
const char *  type 
)

Find all spies of a particular type on a channel and stop them.

Parameters:
chan The channel to operate on
type A character string identifying the type of spies to be stopped
Returns:
nothing
Note: This function performs no locking; you must hold the channel's lock before calling this function.

Definition at line 1426 of file channel.c.

References AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, ast_mutex_lock(), ast_mutex_unlock(), ast_channel_spy::chan, CHANSPY_RUNNING, ast_channel_spy::lock, ast_channel::spies, spy_cleanup(), spy_detach(), ast_channel_spy::status, and ast_channel_spy::type.

Referenced by mixmonitor_cli(), and stop_mixmonitor_exec().

01427 {
01428    struct ast_channel_spy *spy = NULL;
01429    
01430    if (!chan->spies)
01431       return;
01432 
01433    AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->spies->list, spy, list) {
01434       ast_mutex_lock(&spy->lock);
01435       if ((spy->type == type) && (spy->status == CHANSPY_RUNNING)) {
01436          ast_mutex_unlock(&spy->lock);
01437          AST_LIST_REMOVE_CURRENT(&chan->spies->list, list);
01438          spy_detach(spy, chan);
01439       } else
01440          ast_mutex_unlock(&spy->lock);
01441    }
01442    AST_LIST_TRAVERSE_SAFE_END
01443    spy_cleanup(chan);
01444 }

void ast_channel_spy_trigger_wait ( struct ast_channel_spy spy  ) 

Efficiently wait until audio is available for a spy, or an exception occurs.

Parameters:
spy The spy to wait on
Returns:
nothing
Note: The locking rules for this function are non-obvious... first, you must not hold the channel's lock when calling this function. Second, you must hold the spy's lock before making the function call; while the function runs the lock will be released, and when the trigger event occurs, the lock will be re-obtained. This means that when control returns to your code, you will again hold the spy's lock.

Definition at line 1446 of file channel.c.

References ast_cond_timedwait(), ast_tvadd(), ast_channel_spy::lock, and ast_channel_spy::trigger.

Referenced by mixmonitor_thread().

01447 {
01448    struct timeval tv;
01449    struct timespec ts;
01450 
01451    tv = ast_tvadd(ast_tvnow(), ast_samp2tv(50000, 1000));
01452    ts.tv_sec = tv.tv_sec;
01453    ts.tv_nsec = tv.tv_usec * 1000;
01454 
01455    ast_cond_timedwait(&spy->trigger, &spy->lock, &ts);
01456 }


Generated on Mon May 14 04:46:06 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1