include/asterisk/channel.h

   1 /*
   2  * Asterisk -- A telephony toolkit for Linux.
   3  *
   4  * General Asterisk channel definitions.
   5  *
   6  * Copyright (C) 1999, Mark Spencer
   7  *
   8  * Mark Spencer <markster@linux-support.net>
   9  *
  10  * This program is free software, distributed under the terms of
  11  * the GNU General Public License
  12  */
  13
  14 #ifndef _ASTERISK_CHANNEL_H
  15 #define _ASTERISK_CHANNEL_H
  16
  17 #include <asterisk/frame.h>
  18 #include <asterisk/sched.h>
  19 #include <setjmp.h>
  20 #include <pthread.h>
  21
  22 #if defined(__cplusplus) || defined(c_plusplus)
  23 extern "C" {
  24 #endif
  25
  26 #include <pthread.h>
  27
  28 #ifdef DEBUG_THREADS
  29
  30 #define TRIES 50
  31
  32 #include <errno.h>
  33 #include <string.h>
  34 #include <stdio.h>
  35 #include <unistd.h>
  36
  37 struct mutex_info {
  38         pthread_mutex_t *mutex;
  39         char *file;
  40         int lineno;
  41         char *func;
  42         struct mutex_info *next;
  43 };
  44
  45 static inline int __ast_pthread_mutex_lock(char *filename, int lineno, char *func, pthread_mutex_t *t) {
  46         int res;
  47         int tries = TRIES;
  48         do {
  49                 res = pthread_mutex_trylock(t);
  50                 /* If we can't run, yield */
  51                 if (res) {
  52                         sched_yield();
  53                         usleep(1);
  54                 }
  55         } while(res && tries--);
  56         if (res) {
  57                 fprintf(stderr, "%s line %d (%s): Error obtaining mutex: %s\n",
  58                                 filename, lineno, func, strerror(res));
  59                 res = pthread_mutex_lock(t);
  60                 fprintf(stderr, "%s line %d (%s): Got it eventually...\n",
  61                                 filename, lineno, func);
  62         }
  63         return res;
  64 }
  65
  66 #define ast_pthread_mutex_lock(a) __ast_pthread_mutex_lock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a)
  67
  68 static inline int __ast_pthread_mutex_unlock(char *filename, int lineno, char *func, pthread_mutex_t *t) {
  69         int res;
  70         res = pthread_mutex_unlock(t);
  71         if (res)
  72                 fprintf(stderr, "%s line %d (%s): Error releasing mutex: %s\n",
  73                                 filename, lineno, func, strerror(res));
  74         return res;
  75 }
  76 #define ast_pthread_mutex_unlock(a) __ast_pthread_mutex_unlock(__FILE__, __LINE__, __PRETTY_FUNCTION__, a)
  77 #else
  78 #define ast_pthread_mutex_lock pthread_mutex_lock
  79 #define ast_pthread_mutex_unlock pthread_mutex_unlock
  80 #endif
  81
  82 #define AST_CHANNEL_NAME 80
  83 #define AST_CHANNEL_MAX_STACK 32
  84
  85 #define MAX_LANGUAGE 20
  86
  87 /* Max length an extension can be (unique) is this number */
  88 #define AST_MAX_EXTENSION 80
  89
  90 #define AST_MAX_FDS 4
  91
  92 struct ast_channel {
  93         char name[AST_CHANNEL_NAME];            /* ASCII Description of channel name */
  94         char language[MAX_LANGUAGE];            /* Language requested */
  95         char *type;                             /* Type of channel */
  96         int fds[AST_MAX_FDS];                   /* File descriptor for channel -- Drivers will poll
  97                                                                    on these file descriptors, so at least one must be
  98                                                                    non -1.  */
  99
 100         struct ast_channel *bridge;                     /* Who are we bridged to, if we're bridged */
 101         struct ast_channel *masq;                       /* Channel that will masquerade as us */
 102         struct ast_channel *masqr;                      /* Who we are masquerading as */
 103         int cdrflags;                                           /* Call Detail Record Flags */
 104
 105         int blocking;                                           /* Whether or not we're blocking */
 106         int softhangup;                                         /* Whether or not we have been hung up */
 107         int zombie;                                                     /* Non-zero if this is a zombie channel */
 108         pthread_t blocker;                                      /* If anyone is blocking, this is them */
 109         pthread_mutex_t lock;                           /* Lock, can be used to lock a channel for some operations */
 110         char *blockproc;                                        /* Procedure causing blocking */
 111
 112         char *appl;                                                     /* Current application */
 113         char *data;                                                     /* Data passed to current application */
 114
 115         int exception;                                          /* Has an exception been detected */
 116         int fdno;                                                       /* Which fd had an event detected on */
 117         struct sched_context *sched;            /* Schedule context */
 118
 119         int streamid;                                   /* For streaming playback, the schedule ID */
 120         struct ast_filestream *stream;  /* Stream itself. */
 121         int oldwriteformat;                             /* Original writer format */
 122
 123         int state;                              /* State of line */
 124         int rings;                              /* Number of rings so far */
 125         int stack;                              /* Current level of application */
 126
 127         int nativeformats;              /* Kinds of data this channel can
 128                                                            natively handle */
 129         int readformat;                 /* Requested read format */
 130         int writeformat;                /* Requested write format */
 131
 132         char *dnid;                             /* Malloc'd Dialed Number Identifier */
 133         char *callerid;                 /* Malloc'd Caller ID */
 134
 135         char context[AST_MAX_EXTENSION];        /* Current extension context */
 136         char exten[AST_MAX_EXTENSION];          /* Current extension number */
 137         int priority;                                           /* Current extension priority */
 138         void *app[AST_CHANNEL_MAX_STACK];       /* Application information -- see assigned numbers */
 139         char dtmfq[AST_MAX_EXTENSION];          /* Any/all queued DTMF characters */
 140         int deferdtmf;                                          /* Are DTMF digits being deferred */
 141         struct ast_frame dtmff;                         /* DTMF frame */
 142         struct ast_channel_pvt *pvt;
 143                                                 /* Private channel implementation details */
 144         jmp_buf jmp[AST_CHANNEL_MAX_STACK];             /* Jump buffer used for returning from applications */
 145         struct ast_pbx *pbx;
 146         struct ast_channel *next;               /* For easy linking */
 147 };
 148
 149
 150 #define AST_CDR_TRANSFER        (1 << 0)
 151 #define AST_CDR_FORWARD         (1 << 1)
 152 #define AST_CDR_CALLWAIT        (1 << 2)
 153 #define AST_CDR_CONFERENCE      (1 << 3)
 154
 155 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
 156
 157 #define AST_STATE_DOWN          0               /* Channel is down and available */
 158 #define AST_STATE_RESERVED      1               /* Channel is down, but reserved */
 159 #define AST_STATE_OFFHOOK       2               /* Channel is off hook */
 160 #define AST_STATE_DIALING       3               /* Digits (or equivalent) have been dialed */
 161 #define AST_STATE_RING          4               /* Line is ringing */
 162 #define AST_STATE_RINGING       5               /* Remote end is ringing */
 163 #define AST_STATE_UP            6               /* Line is up */
 164 #define AST_STATE_BUSY          7               /* Line is busy */
 165
 166 /* Bits 16-32 of state are reserved for flags */
 167
 168 #define AST_STATE_MUTE          (1 << 16)       /* Do not transmit voice data */
 169
 170 /* Request a channel of a given type, with data as optional information used
 171    by the low level module */
 172 struct ast_channel *ast_request(char *type, int format, void *data);
 173
 174 /* Called by a channel module to register the kind of channels it supports.
 175    It supplies a brief type, a longer, but still short description, and a
 176    routine that creates a channel */
 177 int ast_channel_register(char *type, char *description, int capabilities,
 178                         struct ast_channel* (*requester)(char *type, int format, void *data));
 179
 180 /* Unregister a channel class */
 181 void ast_channel_unregister(char *type);
 182
 183 /* Hang up a channel -- chan is no longer valid after this call! */
 184 int ast_hangup(struct ast_channel *chan);
 185
 186 /* Softly hangup up a channel -- call the protocol layer, but don't
 187    destroy the channel structure (use this if you are trying to
 188    safely hangup a channel managed by another thread. */
 189 int ast_softhangup(struct ast_channel *chan);
 190
 191 /* Answer a ringing call */
 192 int ast_answer(struct ast_channel *chan);
 193
 194 /* Place a call, take no longer than timeout ms.  Returns -1 on failure,
 195    0 on not enough time (does not auto matically stop ringing), and
 196    the number of seconds the connect took otherwise.  */
 197 int ast_call(struct ast_channel *chan, char *addr, int timeout);
 198
 199 /* Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel */
 200 int ast_indicate(struct ast_channel *chan, int condition);
 201
 202 /* Misc stuff */
 203
 204 /* Wait for input on a channel for a given # of milliseconds (<0 for indefinite).
 205   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
 206 int ast_waitfor(struct ast_channel *chan, int ms);
 207
 208 /* Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
 209    file descriptors.  Returns the channel with activity, or NULL on error or if an FD
 210    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
 211    will be -1 */
 212 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
 213
 214 /* Wait for input on an array of channels for a given # of milliseconds. Return channel
 215    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
 216
 217 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
 218
 219 /* This version works on fd's only.  Be careful with it. */
 220 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
 221
 222 /* Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
 223    best just stop reading frames and assume the channel has been
 224    disconnected. */
 225 struct ast_frame *ast_read(struct ast_channel *chan);
 226
 227 /* Write a frame to a channel */
 228 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
 229
 230 /* Set read format for channelto whichever component of "format" is best. */
 231 int ast_set_read_format(struct ast_channel *chan, int format);
 232
 233 /* Set write format for channel to whichever compoent of "format" is best. */
 234 int ast_set_write_format(struct ast_channel *chan, int format);
 235
 236 /* Write text to a display on a channel */
 237 int ast_sendtext(struct ast_channel *chan, char *text);
 238
 239 /* Browse the channels currently in use */
 240 struct ast_channel *ast_channel_walk(struct ast_channel *prev);
 241
 242 /* Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
 243 char ast_waitfordigit(struct ast_channel *c, int ms);
 244
 245 /* Read in a digit string "s", max length "len", maximum timeout between
 246    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
 247    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
 248    a timeout, any digits that were read before the timeout will still be available in s.  */
 249 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
 250
 251 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                /* Report DTMF on channel 0 */
 252 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                /* Report DTMF on channel 1 */
 253 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                /* Return all voice frames on channel 0 */
 254 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                /* Return all voice frames on channel 1 */
 255 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                /* Ignore all signal frames except NULL */
 256
 257
 258 /* Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
 259    and -1 if it could not be done */
 260 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
 261
 262 /* Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
 263    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
 264 int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc);
 265
 266 /* This is a very strange and freaky function used primarily for transfer.  Suppose that
 267    "original" and "clone" are two channels in random situations.  This function takes
 268    the guts out of "clone" and puts them into the "original" channel, then alerts the
 269    channel driver of the change, asking it to fixup any private information (like the
 270    p->owner pointer) that is affected by the change.  The physical layer of the original
 271    channel is hung up.  */
 272 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
 273
 274 /* Give a name to a state */
 275 char *ast_state2str(int state);
 276
 277 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
 278    low level channel.  See frame.h for options.  Note that many channel drivers may support
 279    none or a subset of those features, and you should not count on this if you want your
 280    asterisk application to be portable.  They're mainly useful for tweaking performance */
 281
 282 /* Set an option on a channel (see frame.h), optionally blocking awaiting the reply */
 283 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
 284
 285 /* Query the value of an option, optionally blocking until a reply is received */
 286 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
 287
 288 /* Returns 0 if channel does not support HTML or non-zero if it does */
 289 int ast_channel_supports_html(struct ast_channel *channel);
 290
 291 /* Send HTML or URL on link.  Returns 0 on success or -1 on failure */
 292 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, char *data, int datalen);
 293
 294 /* Send URL on link.  Returns 0 on success or -1 on failure */
 295 int ast_channel_sendurl(struct ast_channel *channel, char *url);
 296
 297 /* Defer DTMF so that you only read things like hangups and audio.  Returns
 298    non-zero if channel was already DTMF-deferred or 0 if channel is just now
 299    being DTMF-deferred */
 300 int ast_channel_defer_dtmf(struct ast_channel *chan);
 301
 302 /* Undo defer.  ast_read will return any dtmf characters that were queued */
 303 void ast_channel_undefer_dtmf(struct ast_channel *chan);
 304
 305 #ifdef DO_CRASH
 306 #define CRASH do { *((int *)0) = 0; } while(0)
 307 #else
 308 #define CRASH do { } while(0)
 309 #endif
 310
 311 #define CHECK_BLOCKING(c) {      \
 312                                                         if ((c)->blocking) {\
 313                                                                 ast_log(LOG_WARNING, "Thread %ld Blocking '%s', already blocked by thread %ld in procedure %s\n", pthread_self(), (c)->name, (c)->blocker, (c)->blockproc); \
 314                                                                 CRASH; \
 315                                                         } else { \
 316                                                                 (c)->blocker = pthread_self(); \
 317                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
 318                                                                         c->blocking = -1; \
 319                                                                         } }
 320
 321 #if defined(__cplusplus) || defined(c_plusplus)
 322 }
 323 #endif
 324
 325
 326 #endif