define an AST_MAX_CONTEXT for use instead of AST_MAX_EXTENSION
[asterisk/asterisk.git] / include / asterisk / channel.h
1 /*
2  * Asterisk -- A telephony toolkit for Linux.
3  *
4  * General Asterisk channel definitions.
5  * 
6  * Copyright (C) 1999 - 2005, Digium, Inc.
7  *
8  * Mark Spencer <markster@digium.com>
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 #ifdef SOLARIS
18 #include <solaris-compat/compat.h>
19 #endif
20 #include "asterisk/frame.h"
21 #include "asterisk/sched.h"
22 #include "asterisk/chanvars.h"
23
24 #include <unistd.h>
25 #include <setjmp.h>
26 #if defined(__APPLE__)
27 #include "asterisk/poll-compat.h"
28 #else
29 #include <sys/poll.h>
30 #endif
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C" {
34 #endif
35
36 #include "asterisk/lock.h"
37
38 /*! Max length of an extension */
39 #define AST_MAX_EXTENSION       80
40
41 #define AST_MAX_CONTEXT         80
42
43 #include "asterisk/cdr.h"
44 #include "asterisk/monitor.h"
45 #include "asterisk/utils.h"
46
47 #define AST_CHANNEL_NAME        80
48
49 #define MAX_LANGUAGE            20
50
51 #define MAX_MUSICCLASS          20
52
53 #define AST_MAX_FDS             8
54
55 typedef unsigned long long ast_group_t;
56
57 struct ast_generator {
58         void *(*alloc)(struct ast_channel *chan, void *params);
59         void (*release)(struct ast_channel *chan, void *data);
60         int (*generate)(struct ast_channel *chan, void *data, int len, int samples);
61 };
62
63 struct ast_callerid {
64         /*! Malloc'd Dialed Number Identifier */
65         char *cid_dnid;                         
66         /*! Malloc'd Caller Number */
67         char *cid_num;
68         /*! Malloc'd Caller Name */
69         char *cid_name;
70         /*! Malloc'd ANI */
71         char *cid_ani;                  
72         /*! Malloc'd RDNIS */
73         char *cid_rdnis;
74         /*! Callerid presentation/screening */
75         int cid_pres;
76         /*! Callerid ANI 2 (Info digits) */
77         int cid_ani2;
78         /*! Callerid Type of Number */
79         int cid_ton;
80         /*! Callerid Transit Network Select */
81         int cid_tns;
82 };
83
84 /*! Structure to describe a channel "technology" */
85
86 struct ast_channel_tech {
87         const char * const type;
88         const char * const description;
89
90         /*! Bitmap of formats this channel can handle */
91         int capabilities;
92
93         /*! Technology Properties */
94         int properties;
95
96         struct ast_channel *(* const requester)(const char *type, int format, void *data, int *cause);
97
98         int (* const devicestate)(void *data);
99
100         /*! Send a literal DTMF digit */
101         int (* const send_digit)(struct ast_channel *chan, char digit);
102
103         /*! Call a given phone number (address, etc), but don't
104            take longer than timeout seconds to do so.  */
105         int (* const call)(struct ast_channel *chan, char *addr, int timeout);
106
107         /*! Hangup (and possibly destroy) the channel */
108         int (* const hangup)(struct ast_channel *chan);
109
110         /*! Answer the line */
111         int (* const answer)(struct ast_channel *chan);
112
113         /*! Read a frame, in standard format */
114         struct ast_frame * (* const read)(struct ast_channel *chan);
115
116         /*! Write a frame, in standard format */
117         int (* const write)(struct ast_channel *chan, struct ast_frame *frame);
118
119         /*! Display or transmit text */
120         int (* const send_text)(struct ast_channel *chan, const char *text);
121
122         /*! Display or send an image */
123         int (* const send_image)(struct ast_channel *chan, struct ast_frame *frame);
124
125         /*! Send HTML data */
126         int (* const send_html)(struct ast_channel *chan, int subclass, const char *data, int len);
127
128         /*! Handle an exception, reading a frame */
129         struct ast_frame * (* const exception)(struct ast_channel *chan);
130
131         /*! Bridge two channels of the same type together */
132         int (* const bridge)(struct ast_channel *c0, struct ast_channel *c1, int flags,
133                              struct ast_frame **fo, struct ast_channel **rc);
134
135         /*! Indicate a particular condition (e.g. AST_CONTROL_BUSY or AST_CONTROL_RINGING or AST_CONTROL_CONGESTION */
136         int (* const indicate)(struct ast_channel *c, int condition);
137
138         /*! Fix up a channel:  If a channel is consumed, this is called.  Basically update any ->owner links */
139         int (* const fixup)(struct ast_channel *oldchan, struct ast_channel *newchan);
140
141         /*! Set a given option */
142         int (* const setoption)(struct ast_channel *chan, int option, void *data, int datalen);
143
144         /*! Query a given option */
145         int (* const queryoption)(struct ast_channel *chan, int option, void *data, int *datalen);
146
147         /*! Blind transfer other side */
148         int (* const transfer)(struct ast_channel *chan, const char *newdest);
149
150         /*! Write a frame, in standard format */
151         int (* const write_video)(struct ast_channel *chan, struct ast_frame *frame);
152
153         /*! Find bridged channel */
154         struct ast_channel *(* const bridged_channel)(struct ast_channel *chan, struct ast_channel *bridge);
155 };
156
157
158 #define CHANSPY_NEW 0
159 #define CHANSPY_RUNNING 1
160 #define CHANSPY_DONE 2
161
162 struct ast_channel_spy {
163         struct ast_frame *queue[2];
164         ast_mutex_t lock;
165         char status;
166         struct ast_channel_spy *next;
167 };
168
169
170 /*! Main Channel structure associated with a channel. */
171 /*! 
172  * This is the side of it mostly used by the pbx and call management.
173  */
174 struct ast_channel {
175         /*! ASCII Description of channel name */
176         char name[AST_CHANNEL_NAME];
177         
178         /*! Technology */
179         const struct ast_channel_tech *tech;
180         /*! Private data used by the technology driver */
181         void *tech_pvt;
182
183         /*! Language requested */
184         char language[MAX_LANGUAGE];            
185         /*! Type of channel */
186         const char *type;                               
187         /*! File descriptor for channel -- Drivers will poll on these file descriptors, so at least one must be non -1.  */
188         int fds[AST_MAX_FDS];                   
189
190         /*! Default music class */
191         char musicclass[MAX_MUSICCLASS];
192         /*! Music State*/
193         void *music_state;
194         /*! Current generator data if there is any */
195         void *generatordata;
196         /*! Current active data generator */
197         struct ast_generator *generator;
198
199         /*! Who are we bridged to, if we're bridged  Do not access directly,
200             use ast_bridged_channel(chan) */
201         struct ast_channel *_bridge;
202         /*! Channel that will masquerade as us */
203         struct ast_channel *masq;               
204         /*! Who we are masquerading as */
205         struct ast_channel *masqr;              
206         /*! Call Detail Record Flags */
207         int cdrflags;                                                                              
208         /*! Whether or not we have been hung up...  Do not set this value
209             directly, use ast_softhangup */
210         int _softhangup;                                
211         /*! Non-zero, set to actual time when channel is to be hung up */
212         time_t  whentohangup;
213         /*! If anyone is blocking, this is them */
214         pthread_t blocker;                      
215         /*! Lock, can be used to lock a channel for some operations */
216         ast_mutex_t lock;                       
217         /*! Procedure causing blocking */
218         const char *blockproc;                  
219
220         /*! Current application */
221         char *appl;                             
222         /*! Data passed to current application */
223         char *data;                             
224         
225         /*! Which fd had an event detected on */
226         int fdno;                               
227         /*! Schedule context */
228         struct sched_context *sched;            
229         /*! For streaming playback, the schedule ID */
230         int streamid;                           
231         /*! Stream itself. */
232         struct ast_filestream *stream;          
233         /*! For streaming playback, the schedule ID */
234         int vstreamid;                          
235         /*! Stream itself. */
236         struct ast_filestream *vstream;         
237         /*! Original writer format */
238         int oldwriteformat;                     
239         
240         /*! Timing fd */
241         int timingfd;
242         int (*timingfunc)(void *data);
243         void *timingdata;
244
245         /*! State of line -- Don't write directly, use ast_setstate */
246         int _state;                             
247         /*! Number of rings so far */
248         int rings;                              
249
250         /*! Kinds of data this channel can natively handle */
251         int nativeformats;                      
252         /*! Requested read format */
253         int readformat;                         
254         /*! Requested write format */
255         int writeformat;                        
256
257         struct ast_callerid cid;
258                 
259         /*! Current extension context */
260         char context[AST_MAX_CONTEXT];
261         /*! Current non-macro context */
262         char macrocontext[AST_MAX_CONTEXT];     
263         /*! Current non-macro extension */
264         char macroexten[AST_MAX_EXTENSION];
265         /*! Current non-macro priority */
266         int macropriority;
267         /*! Current extension number */
268         char exten[AST_MAX_EXTENSION];          
269         /* Current extension priority */
270         int priority;                                           
271         /*! Any/all queued DTMF characters */
272         char dtmfq[AST_MAX_EXTENSION];          
273         /*! DTMF frame */
274         struct ast_frame dtmff;                 
275         /*! Private channel implementation details */
276         struct ast_channel_pvt *pvt;
277
278         /*! PBX private structure */
279         struct ast_pbx *pbx;
280         /*! Set BEFORE PBX is started to determine AMA flags */
281         int     amaflags;                       
282         /*! Account code for billing */
283         char    accountcode[AST_MAX_ACCOUNT_CODE];              
284         /*! Call Detail Record */
285         struct ast_cdr *cdr;                    
286         /*! Whether or not ADSI is detected on CPE */
287         int     adsicpe;
288         /*! Where to forward to if asked to dial on this interface */
289         char call_forward[AST_MAX_EXTENSION];
290
291         /*! Tone zone */
292         struct tone_zone *zone;
293
294         /* Channel monitoring */
295         struct ast_channel_monitor *monitor;
296
297         /*! Track the read/written samples for monitor use */
298         unsigned long insmpl;
299         unsigned long outsmpl;
300
301         /* Frames in/out counters */
302         unsigned int fin;
303         unsigned int fout;
304
305         /* Unique Channel Identifier */
306         char uniqueid[32];
307
308         /* Why is the channel hanged up */
309         int hangupcause;
310         
311         /* A linked list for variables */
312         struct varshead varshead;
313
314         unsigned int callgroup;
315         unsigned int pickupgroup;
316
317         /*! channel flags of AST_FLAG_ type */
318         unsigned int flags;
319         
320         /* ISDN Transfer Capbility - AST_FLAG_DIGITAL is not enough */
321         unsigned short transfercapability;
322
323         struct ast_frame *readq;
324         int alertpipe[2];
325         /*! Write translation path */
326         struct ast_trans_pvt *writetrans;
327         /*! Read translation path */
328         struct ast_trans_pvt *readtrans;
329         /*! Raw read format */
330         int rawreadformat;
331         /*! Raw write format */
332         int rawwriteformat;
333
334         /*! Chan Spy stuff */
335         struct ast_channel_spy *spiers;
336
337         /*! For easy linking */
338         struct ast_channel *next;
339
340 };
341
342 /* Channel tech properties: */
343 /* Channels have this property if they can accept input with jitter; i.e. most VoIP channels */
344 #define AST_CHAN_TP_WANTSJITTER (1 << 0)        
345
346 /* This flag has been deprecated by the transfercapbilty data member in struct ast_channel */
347 /* #define AST_FLAG_DIGITAL     (1 << 0) */     /* if the call is a digital ISDN call */
348 #define AST_FLAG_DEFER_DTMF     (1 << 1)        /* if dtmf should be deferred */
349 #define AST_FLAG_WRITE_INT      (1 << 2)        /* if write should be interrupt generator */
350 #define AST_FLAG_BLOCKING       (1 << 3)        /* if we are blocking */
351 #define AST_FLAG_ZOMBIE         (1 << 4)        /* if we are a zombie */
352 #define AST_FLAG_EXCEPTION      (1 << 5)        /* if there is a pending exception */
353 #define AST_FLAG_MOH            (1 << 6)        /* XXX anthm promises me this will disappear XXX listening to moh */
354 #define AST_FLAG_SPYING         (1 << 7)        /* XXX might also go away XXX is spying on someone */
355 #define AST_FLAG_NBRIDGE        (1 << 8)        /* is it in a native bridge */
356 #define AST_FLAG_IN_AUTOLOOP    (1 << 9)        /* the channel is in an auto-incrementing dialplan processor,
357                                                    so when ->priority is set, it will get incremented before
358                                                    finding the next priority to run
359                                                 */
360
361 #define AST_FEATURE_PLAY_WARNING        (1 << 0)
362 #define AST_FEATURE_REDIRECT            (1 << 1)
363 #define AST_FEATURE_DISCONNECT          (1 << 2)
364 #define AST_FEATURE_ATXFER              (1 << 3)
365 #define AST_FEATURE_AUTOMON             (1 << 4)
366
367 #define AST_FEATURE_FLAG_NEEDSDTMF      (1 << 0)
368
369 struct ast_bridge_config {
370         struct ast_flags features_caller;
371         struct ast_flags features_callee;
372         long timelimit;
373         long play_warning;
374         long warning_freq;
375         char *warning_sound;
376         char *end_sound;
377         char *start_sound;
378         int firstpass;
379         unsigned int flags;
380 };
381
382 struct chanmon;
383
384 #define LOAD_OH(oh) {   \
385         oh.context = context; \
386         oh.exten = exten; \
387         oh.priority = priority; \
388         oh.cid_num = cid_num; \
389         oh.cid_name = cid_name; \
390         oh.variable = variable; \
391         oh.account = account; \
392
393
394 struct outgoing_helper {
395         const char *context;
396         const char *exten;
397         int priority;
398         const char *cid_num;
399         const char *cid_name;
400         const char *variable;
401         const char *account;
402 };
403
404 #define AST_CDR_TRANSFER        (1 << 0)
405 #define AST_CDR_FORWARD         (1 << 1)
406 #define AST_CDR_CALLWAIT        (1 << 2)
407 #define AST_CDR_CONFERENCE      (1 << 3)
408
409 #define AST_ADSI_UNKNOWN        (0)
410 #define AST_ADSI_AVAILABLE      (1)
411 #define AST_ADSI_UNAVAILABLE    (2)
412 #define AST_ADSI_OFFHOOKONLY    (3)
413
414 #define AST_SOFTHANGUP_DEV                      (1 << 0)        /* Soft hangup by device */
415 #define AST_SOFTHANGUP_ASYNCGOTO        (1 << 1)        /* Soft hangup for async goto */
416 #define AST_SOFTHANGUP_SHUTDOWN         (1 << 2)
417 #define AST_SOFTHANGUP_TIMEOUT          (1 << 3)
418 #define AST_SOFTHANGUP_APPUNLOAD        (1 << 4)
419 #define AST_SOFTHANGUP_EXPLICIT         (1 << 5)
420 #define AST_SOFTHANGUP_UNBRIDGE     (1 << 6)
421
422 /* Bits 0-15 of state are reserved for the state (up/down) of the line */
423 /*! Channel is down and available */
424 #define AST_STATE_DOWN          0               
425 /*! Channel is down, but reserved */
426 #define AST_STATE_RESERVED      1               
427 /*! Channel is off hook */
428 #define AST_STATE_OFFHOOK       2               
429 /*! Digits (or equivalent) have been dialed */
430 #define AST_STATE_DIALING       3               
431 /*! Line is ringing */
432 #define AST_STATE_RING          4               
433 /*! Remote end is ringing */
434 #define AST_STATE_RINGING       5               
435 /*! Line is up */
436 #define AST_STATE_UP            6               
437 /*! Line is busy */
438 #define AST_STATE_BUSY          7               
439 /*! Digits (or equivalent) have been dialed while offhook */
440 #define AST_STATE_DIALING_OFFHOOK       8
441 /*! Channel has detected an incoming call and is waiting for ring */
442 #define AST_STATE_PRERING       9
443
444 /* Bits 16-32 of state are reserved for flags */
445 /*! Do not transmit voice data */
446 #define AST_STATE_MUTE          (1 << 16)       
447
448 /*! Create a channel structure */
449 /*! Returns NULL on failure to allocate. New channels are 
450         by default set to the "default" context and
451         extension "s"
452  */
453 struct ast_channel *ast_channel_alloc(int needalertpipe);
454
455 /*! Queue an outgoing frame */
456 int ast_queue_frame(struct ast_channel *chan, struct ast_frame *f);
457
458 /*! Queue a hangup frame */
459 int ast_queue_hangup(struct ast_channel *chan);
460
461 /*! Queue a control frame */
462 int ast_queue_control(struct ast_channel *chan, int control);
463
464 /*! Change the state of a channel */
465 int ast_setstate(struct ast_channel *chan, int state);
466
467 void ast_change_name(struct ast_channel *chan, char *newname);
468
469 /*! Free a channel structure */
470 void  ast_channel_free(struct ast_channel *);
471
472 /*! Requests a channel */
473 /*! 
474  * \param type type of channel to request
475  * \param format requested channel format
476  * \param data data to pass to the channel requester
477  * Request a channel of a given type, with data as optional information used 
478  * by the low level module
479  * Returns an ast_channel on success, NULL on failure.
480  */
481 struct ast_channel *ast_request(const char *type, int format, void *data, int *status);
482
483 /*!
484  * \param type type of channel to request
485  * \param format requested channel format
486  * \param data data to pass to the channel requester
487  * \param timeout maximum amount of time to wait for an answer
488  * \param why unsuccessful (if unsuceessful)
489  * Request a channel of a given type, with data as optional information used 
490  * by the low level module and attempt to place a call on it
491  * Returns an ast_channel on success or no answer, NULL on failure.  Check the value of chan->_state
492  * to know if the call was answered or not.
493  */
494 struct ast_channel *ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname);
495
496 struct ast_channel *__ast_request_and_dial(const char *type, int format, void *data, int timeout, int *reason, const char *cidnum, const char *cidname, struct outgoing_helper *oh);
497
498 /*! Register a channel technology */
499 /*! 
500  * \param tech Structure defining channel technology or "type"
501  * Called by a channel module to register the kind of channels it supports.
502  * Returns 0 on success, -1 on failure.
503  */
504 int ast_channel_register(const struct ast_channel_tech *tech);
505
506 /*! Unregister a channel technology */
507 /*
508  * \param tech Structure defining channel technology or "type" that was previously registered
509  * No return value.
510  */
511 void ast_channel_unregister(const struct ast_channel_tech *tech);
512
513 /*! Get a channel technology structure by name
514  * \param name name of technology to find
515  * \return a pointer to the structure, or NULL if no matching technology found
516  */
517 const struct ast_channel_tech *ast_get_channel_tech(const char *name);
518
519 /*! Hang up a channel  */
520 /*! 
521  * \param chan channel to hang up
522  * This function performs a hard hangup on a channel.  Unlike the soft-hangup, this function
523  * performs all stream stopping, etc, on the channel that needs to end.
524  * chan is no longer valid after this call.
525  * Returns 0 on success, -1 on failure.
526  */
527 int ast_hangup(struct ast_channel *chan);
528
529 /*! Softly hangup up a channel */
530 /*! 
531  * \param chan channel to be soft-hung-up
532  * Call the protocol layer, but don't destroy the channel structure (use this if you are trying to
533  * safely hangup a channel managed by another thread.
534  * \param cause Ast hangupcause for hangup
535  * Returns 0 regardless
536  */
537 int ast_softhangup(struct ast_channel *chan, int cause);
538 /*! Softly hangup up a channel (no channel lock) 
539  * \param cause Ast hangupcause for hangup */
540 int ast_softhangup_nolock(struct ast_channel *chan, int cause);
541
542 /*! Check to see if a channel is needing hang up */
543 /*! 
544  * \param chan channel on which to check for hang up
545  * This function determines if the channel is being requested to be hung up.
546  * Returns 0 if not, or 1 if hang up is requested (including time-out).
547  */
548 int ast_check_hangup(struct ast_channel *chan);
549
550 /*! Set when to hang a channel up */
551 /*! 
552  * \param chan channel on which to check for hang up
553  * \param offset offset in seconds from current time of when to hang up
554  * This function sets the absolute time out on a channel (when to hang up).
555  */
556 void ast_channel_setwhentohangup(struct ast_channel *chan, time_t offset);
557
558 /*! Answer a ringing call */
559 /*!
560  * \param chan channel to answer
561  * This function answers a channel and handles all necessary call
562  * setup functions.
563  * Returns 0 on success, -1 on failure
564  */
565 int ast_answer(struct ast_channel *chan);
566
567 /*! Make a call */
568 /*! 
569  * \param chan which channel to make the call on
570  * \param addr destination of the call
571  * \param timeout time to wait on for connect
572  * Place a call, take no longer than timeout ms.  Returns -1 on failure, 
573    0 on not enough time (does not auto matically stop ringing), and  
574    the number of seconds the connect took otherwise.
575    Returns 0 on success, -1 on failure
576    */
577 int ast_call(struct ast_channel *chan, char *addr, int timeout);
578
579 /*! Indicates condition of channel */
580 /*! 
581  * \param chan channel to change the indication
582  * \param condition which condition to indicate on the channel
583  * Indicate a condition such as AST_CONTROL_BUSY, AST_CONTROL_RINGING, or AST_CONTROL_CONGESTION on a channel
584  * Returns 0 on success, -1 on failure
585  */
586 int ast_indicate(struct ast_channel *chan, int condition);
587
588 /* Misc stuff */
589
590 /*! Wait for input on a channel */
591 /*! 
592  * \param chan channel to wait on
593  * \param ms length of time to wait on the channel
594  * Wait for input on a channel for a given # of milliseconds (<0 for indefinite). 
595   Returns < 0 on  failure, 0 if nothing ever arrived, and the # of ms remaining otherwise */
596 int ast_waitfor(struct ast_channel *chan, int ms);
597
598 /*! Wait for a specied amount of time, looking for hangups */
599 /*!
600  * \param chan channel to wait for
601  * \param ms length of time in milliseconds to sleep
602  * Waits for a specified amount of time, servicing the channel as required.
603  * returns -1 on hangup, otherwise 0.
604  */
605 int ast_safe_sleep(struct ast_channel *chan, int ms);
606
607 /*! Wait for a specied amount of time, looking for hangups and a condition argument */
608 /*!
609  * \param chan channel to wait for
610  * \param ms length of time in milliseconds to sleep
611  * \param cond a function pointer for testing continue condition
612  * \param data argument to be passed to the condition test function
613  * Waits for a specified amount of time, servicing the channel as required. If cond
614  * returns 0, this function returns.
615  * returns -1 on hangup, otherwise 0.
616  */
617 int ast_safe_sleep_conditional(struct ast_channel *chan, int ms, int (*cond)(void*), void *data );
618
619 /*! Waits for activity on a group of channels */
620 /*! 
621  * \param chan an array of pointers to channels
622  * \param n number of channels that are to be waited upon
623  * \param fds an array of fds to wait upon
624  * \param nfds the number of fds to wait upon
625  * \param exception exception flag
626  * \param outfd fd that had activity on it
627  * \param ms how long the wait was
628  * Big momma function here.  Wait for activity on any of the n channels, or any of the nfds
629    file descriptors.  Returns the channel with activity, or NULL on error or if an FD
630    came first.  If the FD came first, it will be returned in outfd, otherwise, outfd
631    will be -1 */
632 struct ast_channel *ast_waitfor_nandfds(struct ast_channel **chan, int n, int *fds, int nfds, int *exception, int *outfd, int *ms);
633
634 /*! Waits for input on a group of channels */
635 /*! Wait for input on an array of channels for a given # of milliseconds. Return channel
636    with activity, or NULL if none has activity.  time "ms" is modified in-place, if applicable */
637 struct ast_channel *ast_waitfor_n(struct ast_channel **chan, int n, int *ms);
638
639 /*! Waits for input on an fd */
640 /*! This version works on fd's only.  Be careful with it. */
641 int ast_waitfor_n_fd(int *fds, int n, int *ms, int *exception);
642
643
644 /*! Reads a frame */
645 /*!
646  * \param chan channel to read a frame from
647  * Read a frame.  Returns a frame, or NULL on error.  If it returns NULL, you
648    best just stop reading frames and assume the channel has been
649    disconnected. */
650 struct ast_frame *ast_read(struct ast_channel *chan);
651
652 /*! Write a frame to a channel */
653 /*!
654  * \param chan destination channel of the frame
655  * \param frame frame that will be written
656  * This function writes the given frame to the indicated channel.
657  * It returns 0 on success, -1 on failure.
658  */
659 int ast_write(struct ast_channel *chan, struct ast_frame *frame);
660
661 /*! Write video frame to a channel */
662 /*!
663  * \param chan destination channel of the frame
664  * \param frame frame that will be written
665  * This function writes the given frame to the indicated channel.
666  * It returns 1 on success, 0 if not implemented, and -1 on failure.
667  */
668 int ast_write_video(struct ast_channel *chan, struct ast_frame *frame);
669
670 /* Send empty audio to prime a channel driver */
671 int ast_prod(struct ast_channel *chan);
672
673 /*! Sets read format on channel chan */
674 /*! 
675  * \param chan channel to change
676  * \param format format to change to
677  * Set read format for channel to whichever component of "format" is best. 
678  * Returns 0 on success, -1 on failure
679  */
680 int ast_set_read_format(struct ast_channel *chan, int format);
681
682 /*! Sets write format on channel chan */
683 /*! 
684  * \param chan channel to change
685  * \param format new format for writing
686  * Set write format for channel to whichever compoent of "format" is best. 
687  * Returns 0 on success, -1 on failure
688  */
689 int ast_set_write_format(struct ast_channel *chan, int format);
690
691 /*! Sends text to a channel */
692 /*! 
693  * \param chan channel to act upon
694  * \param text string of text to send on the channel
695  * Write text to a display on a channel
696  * Returns 0 on success, -1 on failure
697  */
698 int ast_sendtext(struct ast_channel *chan, char *text);
699
700 /*! Receives a text character from a channel */
701 /*! 
702  * \param chan channel to act upon
703  * \param timeout timeout in milliseconds (0 for infinite wait)
704  * Read a char of text from a channel
705  * Returns 0 on success, -1 on failure
706  */
707
708 int ast_senddigit(struct ast_channel *chan, char digit);
709
710 int ast_recvchar(struct ast_channel *chan, int timeout);
711
712 /*! Receives a text string from a channel */
713 /*! 
714  * \param chan channel to act upon
715  * \param timeout timeout in milliseconds (0 for infinite wait)
716  * \return the received text, or NULL to signify failure.
717  * Read a string of text from a channel
718  */
719 char *ast_recvtext(struct ast_channel *chan, int timeout);
720
721 /*! Browse channels in use */
722 /*! 
723  * \param prev where you want to start in the channel list
724  * Browse the channels currently in use 
725  * Returns the next channel in the list, NULL on end.
726  * If it returns a channel, that channel *has been locked*!
727  */
728 struct ast_channel *ast_channel_walk_locked(const struct ast_channel *prev);
729
730 /*! Get channel by name (locks channel) */
731 struct ast_channel *ast_get_channel_by_name_locked(const char *chan);
732
733 /*! Get channel by name prefix (locks channel) */
734 struct ast_channel *ast_get_channel_by_name_prefix_locked(const char *name, const int namelen);
735
736 /*! Waits for a digit */
737 /*! 
738  * \param c channel to wait for a digit on
739  * \param ms how many milliseconds to wait
740  * Wait for a digit.  Returns <0 on error, 0 on no entry, and the digit on success. */
741 int ast_waitfordigit(struct ast_channel *c, int ms);
742
743 /* Same as above with audio fd for outputing read audio and ctrlfd to monitor for
744    reading. Returns 1 if ctrlfd becomes available */
745 int ast_waitfordigit_full(struct ast_channel *c, int ms, int audiofd, int ctrlfd);
746
747 /*! Reads multiple digits */
748 /*! 
749  * \param c channel to read from
750  * \param s string to read in to.  Must be at least the size of your length
751  * \param len how many digits to read (maximum)
752  * \param timeout how long to timeout between digits
753  * \param rtimeout timeout to wait on the first digit
754  * \param enders digits to end the string
755  * Read in a digit string "s", max length "len", maximum timeout between 
756    digits "timeout" (-1 for none), terminated by anything in "enders".  Give them rtimeout
757    for the first digit.  Returns 0 on normal return, or 1 on a timeout.  In the case of
758    a timeout, any digits that were read before the timeout will still be available in s.  
759    RETURNS 2 in full version when ctrlfd is available, NOT 1*/
760 int ast_readstring(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders);
761 int ast_readstring_full(struct ast_channel *c, char *s, int len, int timeout, int rtimeout, char *enders, int audiofd, int ctrlfd);
762
763 /*! Report DTMF on channel 0 */
764 #define AST_BRIDGE_DTMF_CHANNEL_0               (1 << 0)                
765 /*! Report DTMF on channel 1 */
766 #define AST_BRIDGE_DTMF_CHANNEL_1               (1 << 1)                
767 /*! Return all voice frames on channel 0 */
768 #define AST_BRIDGE_REC_CHANNEL_0                (1 << 2)                
769 /*! Return all voice frames on channel 1 */
770 #define AST_BRIDGE_REC_CHANNEL_1                (1 << 3)                
771 /*! Ignore all signal frames except NULL */
772 #define AST_BRIDGE_IGNORE_SIGS                  (1 << 4)                
773
774
775 /*! Makes two channel formats compatible */
776 /*! 
777  * \param c0 first channel to make compatible
778  * \param c1 other channel to make compatible
779  * Set two channels to compatible formats -- call before ast_channel_bridge in general .  Returns 0 on success
780    and -1 if it could not be done */
781 int ast_channel_make_compatible(struct ast_channel *c0, struct ast_channel *c1);
782
783 /*! Bridge two channels together */
784 /*! 
785  * \param c0 first channel to bridge
786  * \param c1 second channel to bridge
787  * \param flags for the channels
788  * \param fo destination frame(?)
789  * \param rc destination channel(?)
790  * Bridge two channels (c0 and c1) together.  If an important frame occurs, we return that frame in
791    *rf (remember, it could be NULL) and which channel (0 or 1) in rc */
792 /* int ast_channel_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc); */
793 int ast_channel_bridge(struct ast_channel *c0,struct ast_channel *c1,struct ast_bridge_config *config, struct ast_frame **fo, struct ast_channel **rc);
794
795 /*! Weird function made for call transfers */
796 /*! 
797  * \param original channel to make a copy of
798  * \param clone copy of the original channel
799  * This is a very strange and freaky function used primarily for transfer.  Suppose that
800    "original" and "clone" are two channels in random situations.  This function takes
801    the guts out of "clone" and puts them into the "original" channel, then alerts the
802    channel driver of the change, asking it to fixup any private information (like the
803    p->owner pointer) that is affected by the change.  The physical layer of the original
804    channel is hung up.  */
805 int ast_channel_masquerade(struct ast_channel *original, struct ast_channel *clone);
806
807 /*! Gives the string form of a given cause code */
808 /*! 
809  * \param cause cause to get the description of
810  * Give a name to a cause code
811  * Returns the text form of the binary cause code given
812  */
813 const char *ast_cause2str(int state);
814
815 /*! Gives the string form of a given channel state */
816 /*! 
817  * \param state state to get the name of
818  * Give a name to a state 
819  * Returns the text form of the binary state given
820  */
821 char *ast_state2str(int state);
822
823 /*! Gives the string form of a given transfer capability */
824 /*!
825  * \param transercapability transfercapabilty to get the name of
826  * Give a name to a transfercapbility
827  * See above
828  * Returns the text form of the binary transfer capbility
829  */
830 char *ast_transfercapability2str(int transfercapability);
831
832 /* Options: Some low-level drivers may implement "options" allowing fine tuning of the
833    low level channel.  See frame.h for options.  Note that many channel drivers may support
834    none or a subset of those features, and you should not count on this if you want your
835    asterisk application to be portable.  They're mainly useful for tweaking performance */
836
837 /*! Sets an option on a channel */
838 /*! 
839  * \param channel channel to set options on
840  * \param option option to change
841  * \param data data specific to option
842  * \param datalen length of the data
843  * \param block blocking or not
844  * Set an option on a channel (see frame.h), optionally blocking awaiting the reply 
845  * Returns 0 on success and -1 on failure
846  */
847 int ast_channel_setoption(struct ast_channel *channel, int option, void *data, int datalen, int block);
848
849 /*! Pick the best codec  */
850 /* Choose the best codec...  Uhhh...   Yah. */
851 extern int ast_best_codec(int fmts);
852
853
854 /*! Checks the value of an option */
855 /*! 
856  * Query the value of an option, optionally blocking until a reply is received
857  * Works similarly to setoption except only reads the options.
858  */
859 struct ast_frame *ast_channel_queryoption(struct ast_channel *channel, int option, void *data, int *datalen, int block);
860
861 /*! Checks for HTML support on a channel */
862 /*! Returns 0 if channel does not support HTML or non-zero if it does */
863 int ast_channel_supports_html(struct ast_channel *channel);
864
865 /*! Sends HTML on given channel */
866 /*! Send HTML or URL on link.  Returns 0 on success or -1 on failure */
867 int ast_channel_sendhtml(struct ast_channel *channel, int subclass, const char *data, int datalen);
868
869 /*! Sends a URL on a given link */
870 /*! Send URL on link.  Returns 0 on success or -1 on failure */
871 int ast_channel_sendurl(struct ast_channel *channel, const char *url);
872
873 /*! Defers DTMF */
874 /*! Defer DTMF so that you only read things like hangups and audio.  Returns
875    non-zero if channel was already DTMF-deferred or 0 if channel is just now
876    being DTMF-deferred */
877 int ast_channel_defer_dtmf(struct ast_channel *chan);
878
879 /*! Undeos a defer */
880 /*! Undo defer.  ast_read will return any dtmf characters that were queued */
881 void ast_channel_undefer_dtmf(struct ast_channel *chan);
882
883 /*! Initiate system shutdown -- prevents new channels from being allocated.
884     If "hangup" is non-zero, all existing channels will receive soft
885      hangups */
886 void ast_begin_shutdown(int hangup);
887
888 /*! Cancels an existing shutdown and returns to normal operation */
889 void ast_cancel_shutdown(void);
890
891 /*! Returns number of active/allocated channels */
892 int ast_active_channels(void);
893
894 /*! Returns non-zero if Asterisk is being shut down */
895 int ast_shutting_down(void);
896
897 /*! Activate a given generator */
898 int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params);
899
900 /*! Deactive an active generator */
901 void ast_deactivate_generator(struct ast_channel *chan);
902
903 void ast_set_callerid(struct ast_channel *chan, const char *cidnum, const char *cidname, const char *ani);
904
905 /*! Start a tone going */
906 int ast_tonepair_start(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
907 /*! Stop a tone from playing */
908 void ast_tonepair_stop(struct ast_channel *chan);
909 /*! Play a tone pair for a given amount of time */
910 int ast_tonepair(struct ast_channel *chan, int freq1, int freq2, int duration, int vol);
911
912 /*! Automatically service a channel for us... */
913 int ast_autoservice_start(struct ast_channel *chan);
914
915 /*! Stop servicing a channel for us...  Returns -1 on error or if channel has been hungup */
916 int ast_autoservice_stop(struct ast_channel *chan);
917
918 /* If built with zaptel optimizations, force a scheduled expiration on the
919    timer fd, at which point we call the callback function / data */
920 int ast_settimeout(struct ast_channel *c, int samples, int (*func)(void *data), void *data);
921
922 /*!     \brief Transfer a channel (if supported).  Returns -1 on error, 0 if not supported
923    and 1 if supported and requested 
924         \param chan current channel
925         \param dest destination extension for transfer
926 */
927 int ast_transfer(struct ast_channel *chan, char *dest);
928
929 int ast_do_masquerade(struct ast_channel *chan);
930
931 /*!     \brief Find bridged channel 
932         \param chan Current channel
933 */
934 struct ast_channel *ast_bridged_channel(struct ast_channel *chan);
935
936 /*!
937   \brief Inherits channel variable from parent to child channel
938   \param parent Parent channel
939   \param child Child channel
940
941   Scans all channel variables in the parent channel, looking for those
942   that should be copied into the child channel.
943   Variables whose names begin with a single '_' are copied into the
944   child channel with the prefix removed.
945   Variables whose names begin with '__' are copied into the child
946   channel with their names unchanged.
947 */
948 void ast_channel_inherit_variables(const struct ast_channel *parent, struct ast_channel *child);
949
950 /* Misc. functions below */
951
952 /* Helper function for migrating select to poll */
953 static inline int ast_fdisset(struct pollfd *pfds, int fd, int max, int *start)
954 {
955         int x;
956         for (x=start ? *start : 0;x<max;x++)
957                 if (pfds[x].fd == fd) {
958                         if (start) {
959                                 if (x==*start)
960                                         (*start)++;
961                         }
962                         return pfds[x].revents;
963                 }
964         return 0;
965 }
966
967 #ifdef SOLARIS
968 static inline void timersub(struct timeval *tvend, struct timeval *tvstart, struct timeval *tvdiff)
969 {
970         tvdiff->tv_sec = tvend->tv_sec - tvstart->tv_sec;
971         tvdiff->tv_usec = tvend->tv_usec - tvstart->tv_usec;
972         if (tvdiff->tv_usec < 0) {
973                 tvdiff->tv_sec --;
974                 tvdiff->tv_usec += 1000000;
975         }
976
977 }
978 #endif
979
980 /*! Waits for activity on a group of channels */
981 /*! 
982  * \param nfds the maximum number of file descriptors in the sets
983  * \param rfds file descriptors to check for read availability
984  * \param wfds file descriptors to check for write availability
985  * \param efds file descriptors to check for exceptions (OOB data)
986  * \param tvp timeout while waiting for events
987  * This is the same as a standard select(), except it guarantees the
988  * behaviour where the passed struct timeval is updated with how much
989  * time was not slept while waiting for the specified events
990  */
991 static inline int ast_select(int nfds, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *tvp)
992 {
993 #ifdef __linux__
994         return select(nfds, rfds, wfds, efds, tvp);
995 #else
996         if (tvp) {
997                 struct timeval tv, tvstart, tvend, tvlen;
998                 int res;
999
1000                 tv = *tvp;
1001                 gettimeofday(&tvstart, NULL);
1002                 res = select(nfds, rfds, wfds, efds, tvp);
1003                 gettimeofday(&tvend, NULL);
1004                 timersub(&tvend, &tvstart, &tvlen);
1005                 timersub(&tv, &tvlen, tvp);
1006                 if (tvp->tv_sec < 0 || (tvp->tv_sec == 0 && tvp->tv_usec < 0)) {
1007                         tvp->tv_sec = 0;
1008                         tvp->tv_usec = 0;
1009                 }
1010                 return res;
1011         }
1012         else
1013                 return select(nfds, rfds, wfds, efds, NULL);
1014 #endif
1015 }
1016
1017 #if !defined(ast_strdupa) && defined(__GNUC__)
1018 # define ast_strdupa(s)                                                                 \
1019   (__extension__                                                                                \
1020     ({                                                                                                  \
1021       __const char *__old = (s);                                                \
1022       size_t __len = strlen (__old) + 1;                                \
1023       char *__new = (char *) __builtin_alloca (__len);  \
1024       (char *) memcpy (__new, __old, __len);                    \
1025     }))
1026 #endif
1027
1028 #ifdef DO_CRASH
1029 #define CRASH do { fprintf(stderr, "!! Forcing immediate crash a-la abort !!\n"); *((int *)0) = 0; } while(0)
1030 #else
1031 #define CRASH do { } while(0)
1032 #endif
1033
1034 #define CHECK_BLOCKING(c) {      \
1035                                                         if (ast_test_flag(c, AST_FLAG_BLOCKING)) {\
1036                                                                 ast_log(LOG_WARNING, "Thread %ld Blocking '%s', already blocked by thread %ld in procedure %s\n", (long) pthread_self(), (c)->name, (long) (c)->blocker, (c)->blockproc); \
1037                                                                 CRASH; \
1038                                                         } else { \
1039                                                                 (c)->blocker = pthread_self(); \
1040                                                                 (c)->blockproc = __PRETTY_FUNCTION__; \
1041                                                                         ast_set_flag(c, AST_FLAG_BLOCKING); \
1042                                                                         } }
1043
1044 extern ast_group_t ast_get_group(char *s);
1045 /* print call- and pickup groups into buffer */
1046 extern char *ast_print_group(char *buf, int buflen, ast_group_t group);
1047
1048
1049 #if defined(__cplusplus) || defined(c_plusplus)
1050 }
1051 #endif
1052
1053 #endif