Sat Nov 1 06:28:30 2008

Asterisk developer's documentation

---

channel.c

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 1999 - 2006, Digium, Inc.
 *
 * Mark Spencer <markster@digium.com>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief Channel Management
 *
 * \author Mark Spencer <markster@digium.com>
 */

#include "asterisk.h"

ASTERISK_FILE_VERSION(__FILE__, "$Revision: 150557 $")

#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
#include <string.h>
#include <sys/time.h>
#include <signal.h>
#include <errno.h>
#include <unistd.h>
#include <math.h>

#if defined(HAVE_DAHDI)
#include <sys/ioctl.h>
#include "asterisk/dahdi_compat.h"
#endif

#include "asterisk/pbx.h"
#include "asterisk/frame.h"
#include "asterisk/sched.h"
#include "asterisk/options.h"
#include "asterisk/channel.h"
#include "asterisk/audiohook.h"
#include "asterisk/musiconhold.h"
#include "asterisk/logger.h"
#include "asterisk/say.h"
#include "asterisk/file.h"
#include "asterisk/cli.h"
#include "asterisk/translate.h"
#include "asterisk/manager.h"
#include "asterisk/chanvars.h"
#include "asterisk/linkedlists.h"
#include "asterisk/indications.h"
#include "asterisk/monitor.h"
#include "asterisk/causes.h"
#include "asterisk/callerid.h"
#include "asterisk/utils.h"
#include "asterisk/lock.h"
#include "asterisk/app.h"
#include "asterisk/transcap.h"
#include "asterisk/devicestate.h"
#include "asterisk/sha1.h"
#include "asterisk/threadstorage.h"
#include "asterisk/slinfactory.h"

/* uncomment if you have problems with 'monitoring' synchronized files */
#if 0
#define MONITOR_CONSTANT_DELAY
#define MONITOR_DELAY   150 * 8     /* 150 ms of MONITORING DELAY */
#endif

/*! Prevent new channel allocation if shutting down. */
static int shutting_down;

static int uniqueint;

unsigned long global_fin, global_fout;

AST_THREADSTORAGE(state2str_threadbuf, state2str_threadbuf_init);
#define STATE2STR_BUFSIZE   32

/*! Default amount of time to use when emulating a digit as a begin and end 
 *  100ms */
#define AST_DEFAULT_EMULATE_DTMF_DURATION 100

/*! Minimum allowed digit length - 80ms */
#define AST_MIN_DTMF_DURATION 80

/*! Minimum amount of time between the end of the last digit and the beginning 
 *  of a new one - 45ms */
#define AST_MIN_DTMF_GAP 45

struct chanlist {
   const struct ast_channel_tech *tech;
   AST_LIST_ENTRY(chanlist) list;
};

/*! the list of registered channel types */
static AST_LIST_HEAD_NOLOCK_STATIC(backends, chanlist);

/*! the list of channels we have. Note that the lock for this list is used for
    both the channels list and the backends list.  */
static AST_LIST_HEAD_STATIC(channels, ast_channel);

/*! map AST_CAUSE's to readable string representations */
const struct ast_cause {
   int cause;
   const char *name;
   const char *desc;
} causes[] = {
   { AST_CAUSE_UNALLOCATED, "UNALLOCATED", "Unallocated (unassigned) number" },
   { AST_CAUSE_NO_ROUTE_TRANSIT_NET, "NO_ROUTE_TRANSIT_NET", "No route to specified transmit network" },
   { AST_CAUSE_NO_ROUTE_DESTINATION, "NO_ROUTE_DESTINATION", "No route to destination" },
   { AST_CAUSE_CHANNEL_UNACCEPTABLE, "CHANNEL_UNACCEPTABLE", "Channel unacceptable" },
   { AST_CAUSE_CALL_AWARDED_DELIVERED, "CALL_AWARDED_DELIVERED", "Call awarded and being delivered in an established channel" },
   { AST_CAUSE_NORMAL_CLEARING, "NORMAL_CLEARING", "Normal Clearing" },
   { AST_CAUSE_USER_BUSY, "USER_BUSY", "User busy" },
   { AST_CAUSE_NO_USER_RESPONSE, "NO_USER_RESPONSE", "No user responding" },
   { AST_CAUSE_NO_ANSWER, "NO_ANSWER", "User alerting, no answer" },
   { AST_CAUSE_CALL_REJECTED, "CALL_REJECTED", "Call Rejected" },
   { AST_CAUSE_NUMBER_CHANGED, "NUMBER_CHANGED", "Number changed" },
   { AST_CAUSE_DESTINATION_OUT_OF_ORDER, "DESTINATION_OUT_OF_ORDER", "Destination out of order" },
   { AST_CAUSE_INVALID_NUMBER_FORMAT, "INVALID_NUMBER_FORMAT", "Invalid number format" },
   { AST_CAUSE_FACILITY_REJECTED, "FACILITY_REJECTED", "Facility rejected" },
   { AST_CAUSE_RESPONSE_TO_STATUS_ENQUIRY, "RESPONSE_TO_STATUS_ENQUIRY", "Response to STATus ENQuiry" },
   { AST_CAUSE_NORMAL_UNSPECIFIED, "NORMAL_UNSPECIFIED", "Normal, unspecified" },
   { AST_CAUSE_NORMAL_CIRCUIT_CONGESTION, "NORMAL_CIRCUIT_CONGESTION", "Circuit/channel congestion" },
   { AST_CAUSE_NETWORK_OUT_OF_ORDER, "NETWORK_OUT_OF_ORDER", "Network out of order" },
   { AST_CAUSE_NORMAL_TEMPORARY_FAILURE, "NORMAL_TEMPORARY_FAILURE", "Temporary failure" },
   { AST_CAUSE_SWITCH_CONGESTION, "SWITCH_CONGESTION", "Switching equipment congestion" },
   { AST_CAUSE_ACCESS_INFO_DISCARDED, "ACCESS_INFO_DISCARDED", "Access information discarded" },
   { AST_CAUSE_REQUESTED_CHAN_UNAVAIL, "REQUESTED_CHAN_UNAVAIL", "Requested channel not available" },
   { AST_CAUSE_PRE_EMPTED, "PRE_EMPTED", "Pre-empted" },
   { AST_CAUSE_FACILITY_NOT_SUBSCRIBED, "FACILITY_NOT_SUBSCRIBED", "Facility not subscribed" },
   { AST_CAUSE_OUTGOING_CALL_BARRED, "OUTGOING_CALL_BARRED", "Outgoing call barred" },
   { AST_CAUSE_INCOMING_CALL_BARRED, "INCOMING_CALL_BARRED", "Incoming call barred" },
   { AST_CAUSE_BEARERCAPABILITY_NOTAUTH, "BEARERCAPABILITY_NOTAUTH", "Bearer capability not authorized" },
   { AST_CAUSE_BEARERCAPABILITY_NOTAVAIL, "BEARERCAPABILITY_NOTAVAIL", "Bearer capability not available" },
   { AST_CAUSE_BEARERCAPABILITY_NOTIMPL, "BEARERCAPABILITY_NOTIMPL", "Bearer capability not implemented" },
   { AST_CAUSE_CHAN_NOT_IMPLEMENTED, "CHAN_NOT_IMPLEMENTED", "Channel not implemented" },
   { AST_CAUSE_FACILITY_NOT_IMPLEMENTED, "FACILITY_NOT_IMPLEMENTED", "Facility not implemented" },
   { AST_CAUSE_INVALID_CALL_REFERENCE, "INVALID_CALL_REFERENCE", "Invalid call reference value" },
   { AST_CAUSE_INCOMPATIBLE_DESTINATION, "INCOMPATIBLE_DESTINATION", "Incompatible destination" },
   { AST_CAUSE_INVALID_MSG_UNSPECIFIED, "INVALID_MSG_UNSPECIFIED", "Invalid message unspecified" },
   { AST_CAUSE_MANDATORY_IE_MISSING, "MANDATORY_IE_MISSING", "Mandatory information element is missing" },
   { AST_CAUSE_MESSAGE_TYPE_NONEXIST, "MESSAGE_TYPE_NONEXIST", "Message type nonexist." },
   { AST_CAUSE_WRONG_MESSAGE, "WRONG_MESSAGE", "Wrong message" },
   { AST_CAUSE_IE_NONEXIST, "IE_NONEXIST", "Info. element nonexist or not implemented" },
   { AST_CAUSE_INVALID_IE_CONTENTS, "INVALID_IE_CONTENTS", "Invalid information element contents" },
   { AST_CAUSE_WRONG_CALL_STATE, "WRONG_CALL_STATE", "Message not compatible with call state" },
   { AST_CAUSE_RECOVERY_ON_TIMER_EXPIRE, "RECOVERY_ON_TIMER_EXPIRE", "Recover on timer expiry" },
   { AST_CAUSE_MANDATORY_IE_LENGTH_ERROR, "MANDATORY_IE_LENGTH_ERROR", "Mandatory IE length error" },
   { AST_CAUSE_PROTOCOL_ERROR, "PROTOCOL_ERROR", "Protocol error, unspecified" },
   { AST_CAUSE_INTERWORKING, "INTERWORKING", "Interworking, unspecified" },
};

struct ast_variable *ast_channeltype_list(void)
{
   struct chanlist *cl;
   struct ast_variable *var=NULL, *prev = NULL;
   AST_LIST_TRAVERSE(&backends, cl, list) {
      if (prev)  {
         if ((prev->next = ast_variable_new(cl->tech->type, cl->tech->description)))
            prev = prev->next;
      } else {
         var = ast_variable_new(cl->tech->type, cl->tech->description);
         prev = var;
      }
   }
   return var;
}

static int show_channeltypes(int fd, int argc, char *argv[])
{
#define FORMAT  "%-10.10s  %-40.40s %-12.12s %-12.12s %-12.12s\n"
   struct chanlist *cl;
   int count_chan = 0;

   ast_cli(fd, FORMAT, "Type", "Description",       "Devicestate", "Indications", "Transfer");
   ast_cli(fd, FORMAT, "----------", "-----------", "-----------", "-----------", "--------");
   if (AST_LIST_LOCK(&channels)) {
      ast_log(LOG_WARNING, "Unable to lock channel list\n");
      return -1;
   }
   AST_LIST_TRAVERSE(&backends, cl, list) {
      ast_cli(fd, FORMAT, cl->tech->type, cl->tech->description,
         (cl->tech->devicestate) ? "yes" : "no",
         (cl->tech->indicate) ? "yes" : "no",
         (cl->tech->transfer) ? "yes" : "no");
      count_chan++;
   }
   AST_LIST_UNLOCK(&channels);
   ast_cli(fd, "----------\n%d channel drivers registered.\n", count_chan);
   return RESULT_SUCCESS;

#undef FORMAT

}

static int show_channeltype_deprecated(int fd, int argc, char *argv[])
{
   struct chanlist *cl = NULL;

   if (argc != 3)
      return RESULT_SHOWUSAGE;
   
   if (AST_LIST_LOCK(&channels)) {
      ast_log(LOG_WARNING, "Unable to lock channel list\n");
      return RESULT_FAILURE;
   }

   AST_LIST_TRAVERSE(&backends, cl, list) {
      if (!strncasecmp(cl->tech->type, argv[2], strlen(cl->tech->type))) {
         break;
      }
   }


   if (!cl) {
      ast_cli(fd, "\n%s is not a registered channel driver.\n", argv[2]);
      AST_LIST_UNLOCK(&channels);
      return RESULT_FAILURE;
   }

   ast_cli(fd,
      "-- Info about channel driver: %s --\n"
      "  Device State: %s\n"
      "    Indication: %s\n"
      "     Transfer : %s\n"
      "  Capabilities: %d\n"
      "   Digit Begin: %s\n"
      "     Digit End: %s\n"
      "    Send HTML : %s\n"
      " Image Support: %s\n"
      "  Text Support: %s\n",
      cl->tech->type,
      (cl->tech->devicestate) ? "yes" : "no",
      (cl->tech->indicate) ? "yes" : "no",
      (cl->tech->transfer) ? "yes" : "no",
      (cl->tech->capabilities) ? cl->tech->capabilities : -1,
      (cl->tech->send_digit_begin) ? "yes" : "no",
      (cl->tech->send_digit_end) ? "yes" : "no",
      (cl->tech->send_html) ? "yes" : "no",
      (cl->tech->send_image) ? "yes" : "no",
      (cl->tech->send_text) ? "yes" : "no"
      
   );

   AST_LIST_UNLOCK(&channels);
   return RESULT_SUCCESS;
}

static int show_channeltype(int fd, int argc, char *argv[])
{
   struct chanlist *cl = NULL;

   if (argc != 4)
      return RESULT_SHOWUSAGE;
   
   if (AST_LIST_LOCK(&channels)) {
      ast_log(LOG_WARNING, "Unable to lock channel list\n");
      return RESULT_FAILURE;
   }

   AST_LIST_TRAVERSE(&backends, cl, list) {
      if (!strncasecmp(cl->tech->type, argv[3], strlen(cl->tech->type))) {
         break;
      }
   }


   if (!cl) {
      ast_cli(fd, "\n%s is not a registered channel driver.\n", argv[3]);
      AST_LIST_UNLOCK(&channels);
      return RESULT_FAILURE;
   }

   ast_cli(fd,
      "-- Info about channel driver: %s --\n"
      "  Device State: %s\n"
      "    Indication: %s\n"
      "     Transfer : %s\n"
      "  Capabilities: %d\n"
      "   Digit Begin: %s\n"
      "     Digit End: %s\n"
      "    Send HTML : %s\n"
      " Image Support: %s\n"
      "  Text Support: %s\n",
      cl->tech->type,
      (cl->tech->devicestate) ? "yes" : "no",
      (cl->tech->indicate) ? "yes" : "no",
      (cl->tech->transfer) ? "yes" : "no",
      (cl->tech->capabilities) ? cl->tech->capabilities : -1,
      (cl->tech->send_digit_begin) ? "yes" : "no",
      (cl->tech->send_digit_end) ? "yes" : "no",
      (cl->tech->send_html) ? "yes" : "no",
      (cl->tech->send_image) ? "yes" : "no",
      (cl->tech->send_text) ? "yes" : "no"
      
   );

   AST_LIST_UNLOCK(&channels);
   return RESULT_SUCCESS;
}

static char *complete_channeltypes_deprecated(const char *line, const char *word, int pos, int state)
{
   struct chanlist *cl;
   int which = 0;
   int wordlen;
   char *ret = NULL;

   if (pos != 2)
      return NULL;

   wordlen = strlen(word);

   AST_LIST_TRAVERSE(&backends, cl, list) {
      if (!strncasecmp(word, cl->tech->type, wordlen) && ++which > state) {
         ret = strdup(cl->tech->type);
         break;
      }
   }
   
   return ret;
}

static char *complete_channeltypes(const char *line, const char *word, int pos, int state)
{
   struct chanlist *cl;
   int which = 0;
   int wordlen;
   char *ret = NULL;

   if (pos != 3)
      return NULL;

   wordlen = strlen(word);

   AST_LIST_TRAVERSE(&backends, cl, list) {
      if (!strncasecmp(word, cl->tech->type, wordlen) && ++which > state) {
         ret = strdup(cl->tech->type);
         break;
      }
   }
   
   return ret;
}

static char show_channeltypes_usage[] =
"Usage: core show channeltypes\n"
"       Lists available channel types registered in your Asterisk server.\n";

static char show_channeltype_usage[] =
"Usage: core show channeltype <name>\n"
"  Show details about the specified channel type, <name>.\n";

static struct ast_cli_entry cli_show_channeltypes_deprecated = {
   { "show", "channeltypes", NULL },
   show_channeltypes, NULL,
   NULL };

static struct ast_cli_entry cli_show_channeltype_deprecated = {
   { "show", "channeltype", NULL },
   show_channeltype_deprecated, NULL,
   NULL, complete_channeltypes_deprecated };

static struct ast_cli_entry cli_channel[] = {
   { { "core", "show", "channeltypes", NULL },
   show_channeltypes, "List available channel types",
   show_channeltypes_usage, NULL, &cli_show_channeltypes_deprecated },

   { { "core", "show", "channeltype", NULL },
   show_channeltype, "Give more details on that channel type",
   show_channeltype_usage, complete_channeltypes, &cli_show_channeltype_deprecated },
};

/*! \brief Checks to see if a channel is needing hang up */
int ast_check_hangup(struct ast_channel *chan)
{
   if (chan->_softhangup)     /* yes if soft hangup flag set */
      return 1;
   if (!chan->tech_pvt)    /* yes if no technology private data */
      return 1;
   if (!chan->whentohangup)   /* no if no hangup scheduled */
      return 0;
   if (chan->whentohangup > time(NULL))   /* no if hangup time has not come yet. */
      return 0;
   chan->_softhangup |= AST_SOFTHANGUP_TIMEOUT; /* record event */
   return 1;
}

static int ast_check_hangup_locked(struct ast_channel *chan)
{
   int res;
   ast_channel_lock(chan);
   res = ast_check_hangup(chan);
   ast_channel_unlock(chan);
   return res;
}

/*! \brief printf the string into a correctly sized mallocd buffer, and return the buffer */
char *ast_safe_string_alloc(const char *fmt, ...)
{
   char *b2, buf[1];
   int len;
   va_list args;

   va_start(args, fmt);
   len = vsnprintf(buf, 1, fmt, args);
   va_end(args);

   if (!(b2 = ast_malloc(len + 1)))
      return NULL;

   va_start(args, fmt);
   vsnprintf(b2, len + 1,  fmt, args);
   va_end(args);

   return b2;
}

/*! \brief Initiate system shutdown */
void ast_begin_shutdown(int hangup)
{
   struct ast_channel *c;
   shutting_down = 1;
   if (hangup) {
      AST_LIST_LOCK(&channels);
      AST_LIST_TRAVERSE(&channels, c, chan_list)
         ast_softhangup(c, AST_SOFTHANGUP_SHUTDOWN);
      AST_LIST_UNLOCK(&channels);
   }
}

/*! \brief returns number of active/allocated channels */
int ast_active_channels(void)
{
   struct ast_channel *c;
   int cnt = 0;
   AST_LIST_LOCK(&channels);
   AST_LIST_TRAVERSE(&channels, c, chan_list)
      cnt++;
   AST_LIST_UNLOCK(&channels);
   return cnt;
}

/*! \brief Cancel a shutdown in progress */
void ast_cancel_shutdown(void)
{
   shutting_down = 0;
}

/*! \brief Returns non-zero if Asterisk is being shut down */
int ast_shutting_down(void)
{
   return shutting_down;
}

/*! \brief Set when to hangup channel */
void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset)
{
   chan->whentohangup = offset ? time(NULL) + offset : 0;
   ast_queue_frame(chan, &ast_null_frame);
   return;
}

/*! \brief Compare a offset with when to hangup channel */
int ast_channel_cmpwhentohangup(struct ast_channel *chan, time_t offset)
{
   time_t whentohangup;

   if (chan->whentohangup == 0) {
      return (offset == 0) ? 0 : -1;
   } else {
      if (offset == 0)  /* XXX why is this special ? */
         return (1);
      else {
         whentohangup = offset + time (NULL);
         if (chan->whentohangup < whentohangup)
            return (1);
         else if (chan->whentohangup == whentohangup)
            return (0);
         else
            return (-1);
      }
   }
}

/*! \brief Register a new telephony channel in Asterisk */
int ast_channel_register(const struct ast_channel_tech *tech)
{
   struct chanlist *chan;

   AST_LIST_LOCK(&channels);

   AST_LIST_TRAVERSE(&backends, chan, list) {
      if (!strcasecmp(tech->type, chan->tech->type)) {
         ast_log(LOG_WARNING, "Already have a handler for type '%s'\n", tech->type);
         AST_LIST_UNLOCK(&channels);
         return -1;
      }
   }
   
   if (!(chan = ast_calloc(1, sizeof(*chan)))) {
      AST_LIST_UNLOCK(&channels);
      return -1;
   }
   chan->tech = tech;
   AST_LIST_INSERT_HEAD(&backends, chan, list);

   if (option_debug)
      ast_log(LOG_DEBUG, "Registered handler for '%s' (%s)\n", chan->tech->type, chan->tech->description);

   if (option_verbose > 1)
      ast_verbose(VERBOSE_PREFIX_2 "Registered channel type '%s' (%s)\n", chan->tech->type,
             chan->tech->description);

   AST_LIST_UNLOCK(&channels);
   return 0;
}

void ast_channel_unregister(const struct ast_channel_tech *tech)
{
   struct chanlist *chan;

   if (option_debug)
      ast_log(LOG_DEBUG, "Unregistering channel type '%s'\n", tech->type);

   AST_LIST_LOCK(&channels);

   AST_LIST_TRAVERSE_SAFE_BEGIN(&backends, chan, list) {
      if (chan->tech == tech) {
         AST_LIST_REMOVE_CURRENT(&backends, list);
         free(chan);
         if (option_verbose > 1)
            ast_verbose(VERBOSE_PREFIX_2 "Unregistered channel type '%s'\n", tech->type);
         break;   
      }
   }
   AST_LIST_TRAVERSE_SAFE_END

   AST_LIST_UNLOCK(&channels);
}

const struct ast_channel_tech *ast_get_channel_tech(const char *name)
{
   struct chanlist *chanls;
   const struct ast_channel_tech *ret = NULL;

   if (AST_LIST_LOCK(&channels)) {
      ast_log(LOG_WARNING, "Unable to lock channel tech list\n");
      return NULL;
   }

   AST_LIST_TRAVERSE(&backends, chanls, list) {
      if (!strcasecmp(name, chanls->tech->type)) {
         ret = chanls->tech;
         break;
      }
   }

   AST_LIST_UNLOCK(&channels);
   
   return ret;
}

/*! \brief Gives the string form of a given hangup cause */
const char *ast_cause2str(int cause)
{
   int x;

   for (x=0; x < sizeof(causes) / sizeof(causes[0]); x++) {
      if (causes[x].cause == cause)
         return causes[x].desc;
   }

   return "Unknown";
}

/*! \brief Convert a symbolic hangup cause to number */
int ast_str2cause(const char *name)
{
   int x;

   for (x = 0; x < sizeof(causes) / sizeof(causes[0]); x++)
      if (strncasecmp(causes[x].name, name, strlen(causes[x].name)) == 0)
         return causes[x].cause;

   return -1;
}

/*! \brief Gives the string form of a given channel state */
char *ast_state2str(enum ast_channel_state state)
{
   char *buf;

   switch(state) {
   case AST_STATE_DOWN:
      return "Down";
   case AST_STATE_RESERVED:
      return "Rsrvd";
   case AST_STATE_OFFHOOK:
      return "OffHook";
   case AST_STATE_DIALING:
      return "Dialing";
   case AST_STATE_RING:
      return "Ring";
   case AST_STATE_RINGING:
      return "Ringing";
   case AST_STATE_UP:
      return "Up";
   case AST_STATE_BUSY:
      return "Busy";
   case AST_STATE_DIALING_OFFHOOK:
      return "Dialing Offhook";
   case AST_STATE_PRERING:
      return "Pre-ring";
   default:
      if (!(buf = ast_threadstorage_get(&state2str_threadbuf, STATE2STR_BUFSIZE)))
         return "Unknown";
      snprintf(buf, STATE2STR_BUFSIZE, "Unknown (%d)", state);
      return buf;
   }
}

/*! \brief Gives the string form of a given transfer capability */
char *ast_transfercapability2str(int transfercapability)
{
   switch(transfercapability) {
   case AST_TRANS_CAP_SPEECH:
      return "SPEECH";
   case AST_TRANS_CAP_DIGITAL:
      return "DIGITAL";
   case AST_TRANS_CAP_RESTRICTED_DIGITAL:
      return "RESTRICTED_DIGITAL";
   case AST_TRANS_CAP_3_1K_AUDIO:
      return "3K1AUDIO";
   case AST_TRANS_CAP_DIGITAL_W_TONES:
      return "DIGITAL_W_TONES";
   case AST_TRANS_CAP_VIDEO:
      return "VIDEO";
   default:
      return "UNKNOWN";
   }
}

/*! \brief Pick the best audio codec */
int ast_best_codec(int fmts)
{
   /* This just our opinion, expressed in code.  We are asked to choose
      the best codec to use, given no information */
   int x;
   static int prefs[] =
   {
      /*! Okay, ulaw is used by all telephony equipment, so start with it */
      AST_FORMAT_ULAW,
      /*! Unless of course, you're a silly European, so then prefer ALAW */
      AST_FORMAT_ALAW,
      /*! G.722 is better then all below, but not as common as the above... so give ulaw and alaw priority */
      AST_FORMAT_G722,
      /*! Okay, well, signed linear is easy to translate into other stuff */
      AST_FORMAT_SLINEAR,
      /*! G.726 is standard ADPCM, in RFC3551 packing order */
      AST_FORMAT_G726,
      /*! G.726 is standard ADPCM, in AAL2 packing order */
      AST_FORMAT_G726_AAL2,
      /*! ADPCM has great sound quality and is still pretty easy to translate */
      AST_FORMAT_ADPCM,
      /*! Okay, we're down to vocoders now, so pick GSM because it's small and easier to
          translate and sounds pretty good */
      AST_FORMAT_GSM,
      /*! iLBC is not too bad */
      AST_FORMAT_ILBC,
      /*! Speex is free, but computationally more expensive than GSM */
      AST_FORMAT_SPEEX,
      /*! Ick, LPC10 sounds terrible, but at least we have code for it, if you're tacky enough
          to use it */
      AST_FORMAT_LPC10,
      /*! G.729a is faster than 723 and slightly less expensive */
      AST_FORMAT_G729A,
      /*! Down to G.723.1 which is proprietary but at least designed for voice */
      AST_FORMAT_G723_1,
   };

   /* Strip out video */
   fmts &= AST_FORMAT_AUDIO_MASK;
   
   /* Find the first preferred codec in the format given */
   for (x=0; x < (sizeof(prefs) / sizeof(prefs[0]) ); x++)
      if (fmts & prefs[x])
         return prefs[x];
   ast_log(LOG_WARNING, "Don't know any of 0x%x formats\n", fmts);
   return 0;
}

static const struct ast_channel_tech null_tech = {
   .type = "NULL",
   .description = "Null channel (should not see this)",
};

/*! \brief Create a new channel structure */
struct ast_channel *ast_channel_alloc(int needqueue, int state, const char *cid_num, const char *cid_name, const char *acctcode, const char *exten, const char *context, const int amaflag, const char *name_fmt, ...)
{
   struct ast_channel *tmp;
   int x;
   int flags;
   struct varshead *headp;
   va_list ap1, ap2;

   /* If shutting down, don't allocate any new channels */
   if (shutting_down) {
      ast_log(LOG_WARNING, "Channel allocation failed: Refusing due to active shutdown\n");
      return NULL;
   }

   if (!(tmp = ast_calloc(1, sizeof(*tmp))))
      return NULL;

   if (!(tmp->sched = sched_context_create())) {
      ast_log(LOG_WARNING, "Channel allocation failed: Unable to create schedule context\n");
      free(tmp);
      return NULL;
   }
   
   if ((ast_string_field_init(tmp, 128))) {
      sched_context_destroy(tmp->sched);
      free(tmp);
      return NULL;
   }

   /* Don't bother initializing the last two FD here, because they
      will *always* be set just a few lines down (AST_TIMING_FD,
      AST_ALERT_FD). */
   for (x = 0; x < AST_MAX_FDS - 2; x++)
      tmp->fds[x] = -1;

#ifdef HAVE_DAHDI

#ifdef HAVE_ZAPTEL
   tmp->timingfd = open("/dev/zap/timer", O_RDWR);
#else
   tmp->timingfd = open("/dev/dahdi/timer", O_RDWR);
#endif

   if (tmp->timingfd > -1) {
      /* Check if timing interface supports new
         ping/pong scheme */
      flags = 1;
      if (!ioctl(tmp->timingfd, DAHDI_TIMERPONG, &flags))
         needqueue = 0;
   }
#else
   tmp->timingfd = -1;              
#endif               

   if (needqueue) {
      if (pipe(tmp->alertpipe)) {
         ast_log(LOG_WARNING, "Channel allocation failed: Can't create alert pipe!\n");
alertpipe_failed:
#ifdef HAVE_DAHDI
         if (tmp->timingfd > -1)
            close(tmp->timingfd);
#endif
         sched_context_destroy(tmp->sched);
         ast_string_field_free_memory(tmp);
         free(tmp);
         return NULL;
      } else {
         flags = fcntl(tmp->alertpipe[0], F_GETFL);
         if (fcntl(tmp->alertpipe[0], F_SETFL, flags | O_NONBLOCK) < 0) {
            ast_log(LOG_WARNING, "Channel allocation failed: Unable to set alertpipe nonblocking! (%d: %s)\n", errno, strerror(errno));
            close(tmp->alertpipe[0]);
            close(tmp->alertpipe[1]);
            goto alertpipe_failed;
         }
         flags = fcntl(tmp->alertpipe[1], F_GETFL);
         if (fcntl(tmp->alertpipe[1], F_SETFL, flags | O_NONBLOCK) < 0) {
            ast_log(LOG_WARNING, "Channel allocation failed: Unable to set alertpipe nonblocking! (%d: %s)\n", errno, strerror(errno));
            close(tmp->alertpipe[0]);
            close(tmp->alertpipe[1]);
            goto alertpipe_failed;
         }
      }
   } else   /* Make sure we've got it done right if they don't */
      tmp->alertpipe[0] = tmp->alertpipe[1] = -1;

   /* Always watch the alertpipe */
   tmp->fds[AST_ALERT_FD] = tmp->alertpipe[0];
   /* And timing pipe */
   tmp->fds[AST_TIMING_FD] = tmp->timingfd;
   ast_string_field_set(tmp, name, "**Unknown**");

   /* Initial state */
   tmp->_state = state;

   tmp->streamid = -1;
   
   tmp->fin = global_fin;
   tmp->fout = global_fout;

   if (ast_strlen_zero(ast_config_AST_SYSTEM_NAME)) {
      ast_string_field_build(tmp, uniqueid, "%li.%d", (long) time(NULL), 
         ast_atomic_fetchadd_int(&uniqueint, 1));
   } else {
      ast_string_field_build(tmp, uniqueid, "%s-%li.%d", ast_config_AST_SYSTEM_NAME, 
         (long) time(NULL), ast_atomic_fetchadd_int(&uniqueint, 1));
   }

   tmp->cid.cid_name = ast_strdup(cid_name);
   tmp->cid.cid_num = ast_strdup(cid_num);
   
   if (!ast_strlen_zero(name_fmt)) {
      /* Almost every channel is calling this function, and setting the name via the ast_string_field_build() call.
       * And they all use slightly different formats for their name string.
       * This means, to set the name here, we have to accept variable args, and call the string_field_build from here.
       * This means, that the stringfields must have a routine that takes the va_lists directly, and 
       * uses them to build the string, instead of forming the va_lists internally from the vararg ... list.
       * This new function was written so this can be accomplished.
       */
      va_start(ap1, name_fmt);
      va_start(ap2, name_fmt);
      ast_string_field_build_va(tmp, name, name_fmt, ap1, ap2);
      va_end(ap1);
      va_end(ap2);
   }

   /* Reminder for the future: under what conditions do we NOT want to track cdrs on channels? */

   /* These 4 variables need to be set up for the cdr_init() to work right */
   if (amaflag)
      tmp->amaflags = amaflag;
   else
      tmp->amaflags = ast_default_amaflags;
   
   if (!ast_strlen_zero(acctcode))
      ast_string_field_set(tmp, accountcode, acctcode);
   else
      ast_string_field_set(tmp, accountcode, ast_default_accountcode);
      
   if (!ast_strlen_zero(context))
      ast_copy_string(tmp->context, context, sizeof(tmp->context));
   else
      strcpy(tmp->context, "default");

   if (!ast_strlen_zero(exten))
      ast_copy_string(tmp->exten, exten, sizeof(tmp->exten));
   else
      strcpy(tmp->exten, "s");

   tmp->priority = 1;
      
   tmp->cdr = ast_cdr_alloc();
   ast_cdr_init(tmp->cdr, tmp);
   ast_cdr_start(tmp->cdr);
   
   headp = &tmp->varshead;
   AST_LIST_HEAD_INIT_NOLOCK(headp);
   
   ast_mutex_init(&tmp->lock);
   
   AST_LIST_HEAD_INIT_NOLOCK(&tmp->datastores);
   
   ast_string_field_set(tmp, language, defaultlanguage);

   tmp->tech = &null_tech;

   AST_LIST_LOCK(&channels);
   AST_LIST_INSERT_HEAD(&channels, tmp, chan_list);
   AST_LIST_UNLOCK(&channels);

   /*\!note
    * and now, since the channel structure is built, and has its name, let's
    * call the manager event generator with this Newchannel event. This is the
    * proper and correct place to make this call, but you sure do have to pass
    * a lot of data into this func to do it here!
    */
   if (!ast_strlen_zero(name_fmt)) {
      manager_event(EVENT_FLAG_CALL, "Newchannel",
            "Channel: %s\r\n"
            "State: %s\r\n"
            "CallerIDNum: %s\r\n"
            "CallerIDName: %s\r\n"
            "Uniqueid: %s\r\n",
            tmp->name, ast_state2str(state),
            S_OR(cid_num, "<unknown>"),
            S_OR(cid_name, "<unknown>"),
            tmp->uniqueid);
   }

   return tmp;
}

/*! \brief Queue an outgoing media frame */
int ast_queue_frame(struct ast_channel *chan, struct ast_frame *fin)
{
   struct ast_frame *f;
   struct ast_frame *cur;
   int blah = 1;
   int qlen = 0;

   /* Build us a copy and free the original one */
   if (!(f = ast_frdup(fin))) {
      ast_log(LOG_WARNING, "Unable to duplicate frame\n");
      return -1;
   }
   ast_channel_lock(chan);

   /* See if the last frame on the queue is a hangup, if so don't queue anything */
   if ((cur = AST_LIST_LAST(&chan->readq)) && (cur->frametype == AST_FRAME_CONTROL) && (cur->subclass == AST_CONTROL_HANGUP)) {
      ast_frfree(f);
      ast_channel_unlock(chan);
      return 0;
   }

   /* Count how many frames exist on the queue */
   AST_LIST_TRAVERSE(&chan->readq, cur, frame_list) {
      qlen++;
   }

   /* Allow up to 96 voice frames outstanding, and up to 128 total frames */
   if (((fin->frametype == AST_FRAME_VOICE) && (qlen > 96)) || (qlen  > 128)) {
      if (fin->frametype != AST_FRAME_VOICE) {
         ast_log(LOG_WARNING, "Exceptionally long queue length queuing to %s\n", chan->name);
         ast_assert(fin->frametype == AST_FRAME_VOICE);
      } else {
         if (option_debug)
            ast_log(LOG_DEBUG, "Dropping voice to exceptionally long queue on %s\n", chan->name);
         ast_frfree(f);
         ast_channel_unlock(chan);
         return 0;
      }
   }
   AST_LIST_INSERT_TAIL(&chan->readq, f, frame_list);
   if (chan->alertpipe[1] > -1) {
      if (write(chan->alertpipe[1], &blah, sizeof(blah)) != sizeof(blah))
         ast_log(LOG_WARNING, "Unable to write to alert pipe on %s, frametype/subclass %d/%d (qlen = %d): %s!\n",
            chan->name, f->frametype, f->subclass, qlen, strerror(errno));
#ifdef HAVE_DAHDI
   } else if (chan->timingfd > -1) {
      ioctl(chan->timingfd, DAHDI_TIMERPING, &blah);
#endif            
   } else if (ast_test_flag(chan, AST_FLAG_BLOCKING)) {
      pthread_kill(chan->blocker, SIGURG);
   }
   ast_channel_unlock(chan);
   return 0;
}

/*! \brief Queue a hangup frame for channel */
int