Mon Apr 30 07:40:28 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_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.
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.

                   {
   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

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.

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

---

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

{
   /* Link the owner channel to the spy */
   spy->chan = chan;

   if (!ast_test_flag(spy, CHANSPY_FORMAT_AUDIO)) {
      ast_log(LOG_WARNING, "Could not add channel spy '%s' to channel '%s', only audio format spies are supported.\n",
         spy->type, chan->name);
      return -1;
   }

   if (ast_test_flag(spy, CHANSPY_READ_VOLADJUST) && (spy->read_queue.format != AST_FORMAT_SLINEAR)) {
      ast_log(LOG_WARNING, "Cannot provide volume adjustment on '%s' format spies\n",
         ast_getformatname(spy->read_queue.format));
      return -1;
   }

   if (ast_test_flag(spy, CHANSPY_WRITE_VOLADJUST) && (spy->write_queue.format != AST_FORMAT_SLINEAR)) {
      ast_log(LOG_WARNING, "Cannot provide volume adjustment on '%s' format spies\n",
         ast_getformatname(spy->write_queue.format));
      return -1;
   }

   if (ast_test_flag(spy, CHANSPY_MIXAUDIO) &&
       ((spy->read_queue.format != AST_FORMAT_SLINEAR) ||
        (spy->write_queue.format != AST_FORMAT_SLINEAR))) {
      ast_log(LOG_WARNING, "Cannot provide audio mixing on '%s'-'%s' format spies\n",
         ast_getformatname(spy->read_queue.format), ast_getformatname(spy->write_queue.format));
      return -1;
   }

   if (!chan->spies) {
      if (!(chan->spies = ast_calloc(1, sizeof(*chan->spies)))) {
         return -1;
      }

      AST_LIST_HEAD_INIT_NOLOCK(&chan->spies->list);
      AST_LIST_INSERT_HEAD(&chan->spies->list, spy, list);
   } else {
      AST_LIST_INSERT_TAIL(&chan->spies->list, spy, list);
   }

   if (ast_test_flag(spy, CHANSPY_TRIGGER_MODE) != CHANSPY_TRIGGER_NONE) {
      ast_cond_init(&spy->trigger, NULL);
      ast_set_flag(spy, CHANSPY_TRIGGER_READ);
      ast_clear_flag(spy, CHANSPY_TRIGGER_WRITE);
   }

   if (option_debug)
      ast_log(LOG_DEBUG, "Spy %s added to channel %s\n",
         spy->type, chan->name);

   return 0;
}

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

{
   struct ast_frame *f = NULL;

   if (spy->status == CHANSPY_DONE)
      return;

   /* Switch status to done in case we get called twice */
   spy->status = CHANSPY_DONE;

   /* Drop any frames in the queue */
   while ((f = AST_LIST_REMOVE_HEAD(&spy->write_queue.list, frame_list)))
      ast_frfree(f);
   while ((f = AST_LIST_REMOVE_HEAD(&spy->read_queue.list, frame_list)))
      ast_frfree(f);

   /* Destroy the condition if in use */
   if (ast_test_flag(spy, CHANSPY_TRIGGER_MODE) != CHANSPY_TRIGGER_NONE)
      ast_cond_destroy(&spy->trigger);

   /* Destroy our mutex since it is no longer in use */
   ast_mutex_destroy(&spy->lock);

   return;
}

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

{
   struct ast_frame *result;
   /* buffers are allocated to hold SLINEAR, which is the largest format */
        short read_buf[samples];
        short write_buf[samples];
   struct ast_frame *read_frame;
   struct ast_frame *write_frame;
   int need_dup;
   struct ast_frame stack_read_frame = { .frametype = AST_FRAME_VOICE,
                     .subclass = spy->read_queue.format,
                     .data = read_buf,
                     .samples = samples,
                     .datalen = ast_codec_get_len(spy->read_queue.format, samples),
   };
   struct ast_frame stack_write_frame = { .frametype = AST_FRAME_VOICE,
                      .subclass = spy->write_queue.format,
                      .data = write_buf,
                      .samples = samples,
                      .datalen = ast_codec_get_len(spy->write_queue.format, samples),
   };

   /* if a flush has been requested, dump everything in whichever queue is larger */
   if (ast_test_flag(spy, CHANSPY_TRIGGER_FLUSH)) {
      if (spy->read_queue.samples > spy->write_queue.samples) {
         if (ast_test_flag(spy, CHANSPY_READ_VOLADJUST)) {
            AST_LIST_TRAVERSE(&spy->read_queue.list, result, frame_list)
               ast_frame_adjust_volume(result, spy->read_vol_adjustment);
         }
         result = AST_LIST_FIRST(&spy->read_queue.list);
         AST_LIST_HEAD_SET_NOLOCK(&spy->read_queue.list, NULL);
         spy->read_queue.samples = 0;
      } else {
         if (ast_test_flag(spy, CHANSPY_WRITE_VOLADJUST)) {
            AST_LIST_TRAVERSE(&spy->write_queue.list, result, frame_list)
               ast_frame_adjust_volume(result, spy->write_vol_adjustment);
         }
         result = AST_LIST_FIRST(&spy->write_queue.list);
         AST_LIST_HEAD_SET_NOLOCK(&spy->write_queue.list, NULL);
         spy->write_queue.samples = 0;
      }
      ast_clear_flag(spy, CHANSPY_TRIGGER_FLUSH);
      return result;
   }

   if ((spy->read_queue.samples < samples) || (spy->write_queue.samples < samples))
      return NULL;

   /* short-circuit if both head frames have exactly what we want */
   if ((AST_LIST_FIRST(&spy->read_queue.list)->samples == samples) &&
       (AST_LIST_FIRST(&spy->write_queue.list)->samples == samples)) {
      read_frame = AST_LIST_REMOVE_HEAD(&spy->read_queue.list, frame_list);
      write_frame = AST_LIST_REMOVE_HEAD(&spy->write_queue.list, frame_list);

      spy->read_queue.samples -= samples;
      spy->write_queue.samples -= samples;

      need_dup = 0;
   } else {
      copy_data_from_queue(&spy->read_queue, read_buf, samples);
      copy_data_from_queue(&spy->write_queue, write_buf, samples);

      read_frame = &stack_read_frame;
      write_frame = &stack_write_frame;
      need_dup = 1;
   }
   
   if (ast_test_flag(spy, CHANSPY_READ_VOLADJUST))
      ast_frame_adjust_volume(read_frame, spy->read_vol_adjustment);

   if (ast_test_flag(spy, CHANSPY_WRITE_VOLADJUST))
      ast_frame_adjust_volume(write_frame, spy->write_vol_adjustment);

   if (ast_test_flag(spy, CHANSPY_MIXAUDIO)) {
      ast_frame_slinear_sum(read_frame, write_frame);

      if (need_dup)
         result = ast_frdup(read_frame);
      else {
         result = read_frame;
         ast_frfree(write_frame);
      }
   } else {
      if (need_dup) {
         result = ast_frdup(read_frame);
         AST_LIST_NEXT(result, frame_list) = ast_frdup(write_frame);
      } else {
         result = read_frame;
         AST_LIST_NEXT(result, frame_list) = write_frame;
      }
   }

   return result;
}

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 1455 of file channel.c.

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

Referenced by channel_spy().

{
   if (!chan->spies)
      return;

   AST_LIST_REMOVE(&chan->spies->list, spy, list);
   spy_detach(spy, chan);
   spy_cleanup(chan);
}

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

{
   struct ast_channel_spy *spy = NULL;
   
   if (!chan->spies)
      return;

   AST_LIST_TRAVERSE_SAFE_BEGIN(&chan->spies->list, spy, list) {
      ast_mutex_lock(&spy->lock);
      if ((spy->type == type) && (spy->status == CHANSPY_RUNNING)) {
         ast_mutex_unlock(&spy->lock);
         AST_LIST_REMOVE_CURRENT(&chan->spies->list, list);
         spy_detach(spy, chan);
      } else
         ast_mutex_unlock(&spy->lock);
   }
   AST_LIST_TRAVERSE_SAFE_END
   spy_cleanup(chan);
}

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 1443 of file channel.c.

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

Referenced by mixmonitor_thread().

{
   struct timeval tv;
   struct timespec ts;

   tv = ast_tvadd(ast_tvnow(), ast_samp2tv(50000, 1000));
   ts.tv_sec = tv.tv_sec;
   ts.tv_nsec = tv.tv_usec * 1000;

   ast_cond_timedwait(&spy->trigger, &spy->lock, &ts);
}

---